문서의 품질을 평가하는 방법

안녕, 하브르! 제 이름은 Lesha이고 Alfa-Bank 제품 팀 중 하나의 시스템 분석가입니다. 이제 저는 법인과 개인 기업가를 위한 새로운 온라인 은행을 개발하고 있습니다.

그리고 당신이 분석가라면, 특히 그러한 채널에서 문서화와 긴밀한 작업 없이는 아무데도 갈 수 없습니다. 그리고 문서화는 항상 많은 질문을 불러일으키는 것입니다. 웹 애플리케이션이 설명되지 않은 이유는 무엇입니까? 사양에는 서비스 작동 방식이 명시되어 있지만 전혀 작동하지 않는 이유는 무엇입니까? 왜 그것을 작성한 사람 중 한 명만이 사양을 이해할 수 있습니까?

그러나 명백한 이유로 문서를 무시할 수는 없습니다. 그리고 우리의 삶을 더 쉽게 만들기 위해 문서의 품질을 평가하기로 결정했습니다. 우리가 이것을 정확히 어떻게 했고 어떤 결론에 도달했는지는 아래에 나와 있습니다.

문서 품질

본문에서 '뉴인터넷뱅크'를 수십 번 반복하지 않기 위해 NIB로 표기하겠습니다. 이제 우리는 기업가와 법인을 위한 NIB 개발을 위해 노력하는 XNUMX개 이상의 팀을 보유하고 있습니다. 또한, 각각은 새로운 서비스나 웹 애플리케이션에 대한 자체 문서를 처음부터 생성하거나 현재 문서를 변경합니다. 이 접근 방식을 사용하면 원칙적으로 문서의 품질이 높아질 수 있습니까?

그리고 문서의 품질을 결정하기 위해 우리는 세 가지 주요 특징을 식별했습니다.

1. 그것은 완전해야합니다. 이것은 다소 선장처럼 들리지만 주목하는 것이 중요합니다. 구현된 솔루션의 모든 요소를 ​​자세히 설명해야 합니다.
2. 관련성이 있어야 합니다. 즉, 솔루션 자체의 현재 구현에 해당합니다.
3. 이해할 수 있어야합니다. 이를 사용하는 사람은 솔루션이 어떻게 구현되는지 정확히 이해할 수 있습니다.

요약하자면, 완전하고 이해하기 쉬운 최신 문서입니다.

Опрос

문서의 품질을 평가하기 위해 우리는 직접 작업하는 사람인 NIB 분석가를 인터뷰하기로 결정했습니다. 응답자들은 "10부터 1까지의 척도(완전히 동의하지 않음 - 전적으로 동의함)" 체계에 따라 5개의 진술을 평가하도록 요청 받았습니다.

이 진술에는 질적 문서의 특성과 NIB 문서에 관한 조사 작성자의 의견이 반영되었습니다.

1. NIB 애플리케이션에 대한 문서는 최신 상태이며 구현과 완전히 일치합니다.
2. NIB 애플리케이션의 구현은 완전히 문서화되어 있습니다.
3. NIB 애플리케이션에 대한 문서는 기능 지원에만 필요합니다.
4. NIB 신청서에 대한 문서는 기능 지원을 위해 제출하는 시점에 최신 상태입니다.
5. NIB 애플리케이션 개발자는 문서를 사용하여 구현해야 할 사항을 이해합니다.
6. NIB 애플리케이션이 구현되는 방법을 이해하는 데 충분한 문서가 있습니다.
7. 나는 NIB 프로젝트에 대한 문서가 (우리 팀에 의해) 마무리되면 즉시 업데이트합니다.
8. NIB 애플리케이션 개발자는 문서를 검토합니다.
9. NIB 프로젝트를 위한 문서 준비 방법을 명확하게 이해하고 있습니다.
10. NIB 프로젝트에 대한 문서를 언제 작성/업데이트해야 하는지 이해합니다.

단순히 "1부터 5까지"라고 대답하는 것만으로는 필요한 세부 사항이 공개되지 않을 수 있으므로 각 항목에 댓글을 남길 수 있습니다.

우리는 이 모든 것을 기업 Slack을 통해 수행했습니다. 우리는 단순히 시스템 분석가에게 설문조사에 참여하도록 초대장을 보냈습니다. 분석가는 15명(모스크바에서 9명, 상트페테르부르크에서 6명)이었습니다. 설문조사가 완료된 후 우리는 10개 진술 각각에 대한 평균 점수를 생성한 다음 이를 표준화했습니다.

그것은 그것이 무엇인지 밝혀졌습니다.

설문 조사에 따르면 분석가들은 NIB 애플리케이션 구현이 완전히 문서화되어 있다고 믿는 경향이 있지만 명확한 동의를 제공하지는 않습니다(0.2). 구체적인 예로 기존 솔루션의 많은 데이터베이스와 대기열이 문서에서 다루어지지 않았다는 점을 지적했습니다. 개발자는 분석가에게 모든 것이 문서화되지는 않았다고 말할 수 있습니다. 그러나 개발자가 문서를 검토한다는 주장 역시 명확한 지지를 받지 못했습니다(0.33). 즉, 구현된 솔루션에 대한 설명이 불완전할 위험이 남아 있습니다.

관련성이 더 쉽습니다. 명확한 합의가 없더라도(0,13), 분석가는 여전히 문서를 관련성이 있다고 생각하는 경향이 있습니다. 의견을 통해 우리는 관련성 문제가 중간보다 앞쪽에 더 자주 발생한다는 것을 이해할 수 있었습니다. 그러나 그들은 우리에게 후원에 관해 아무 것도 쓰지 않았습니다.

문서를 작성하고 업데이트해야 하는 시기를 분석가가 스스로 이해하는지 여부에 대한 합의는 설계(1,33)를 포함하여 훨씬 더 균일했습니다(1.07). 여기서 불편한 점은 문서 유지에 대한 통일된 규칙이 없다는 것입니다. 따라서 '누가 숲에 가고, 누가 장작을 구하는가' 모드를 켜지 않기 위해서는 기존 문서의 예를 토대로 작업해야 한다. 따라서 문서 관리에 대한 표준을 만들고 해당 부분에 대한 템플릿을 개발하는 것이 유용합니다.

NIB 신청서에 대한 문서는 기능 지원 제출 시점(0.73)에 최신 상태입니다. 기능 지원을 위한 프로젝트 제출 기준 중 하나가 최신 문서이기 때문에 이는 이해할 수 있습니다. 때로는 질문이 남아 있기는 하지만 구현(0.67)을 이해하는 것만으로도 충분합니다.

그러나 응답자들이 만장일치로 동의하지 않은 것은 원칙적으로 NIB 애플리케이션에 대한 문서가 기능 지원에만 필요하다는 것입니다(-1.53). 분석가는 문서 소비자로 가장 자주 언급되었습니다. 나머지 팀(개발자) - 훨씬 덜 자주 사용됩니다. 더욱이 분석가들은 개발자들이 만장일치로(-0.06)는 아니지만 구현해야 할 사항을 이해하기 위해 문서를 사용하지 않는다고 생각합니다. 그런데 이는 코드 개발과 문서 작성이 동시에 진행되는 상황에서도 예상됩니다.

결론은 무엇이며 왜 이 숫자가 필요한가요?

문서의 품질을 향상시키기 위해 우리는 다음을 수행하기로 결정했습니다.

1. 개발자에게 서면 문서를 검토하도록 요청하세요.
2. 가능하다면 적시에 문서를 앞면부터 업데이트하세요.
3. 모든 사람이 어떤 시스템 요소와 정확히 어떻게 설명해야 하는지 빠르게 이해할 수 있도록 NIB 프로젝트 문서화를 위한 표준을 만들고 채택합니다. 글쎄, 적절한 템플릿을 개발하십시오.

이 모든 것이 문서의 품질을 새로운 수준으로 높이는 데 도움이 될 것입니다.

적어도 나는 그러기를 바란다.

출처 : habr.com