엔지니어가 작성한 문서의 일반적인 실수와 해결 방법

지난 6개월 동안 우리 개발팀은 "코드로서의 문서" 접근 방식을 채택했습니다. ). 기술 부서 동료들이 작성한 문서를 정기적으로 검토하면서 기술 문서 작성 시 발견되는 가장 일반적인 문제 목록을 작성했습니다.

이 기사에서는 "문서로서의 코드" 접근 방식 도구를 사용하여 이러한 문제를 해결하는 방법을 보여 드리겠습니다.

Issue 1. “문서 작성은 저희 책임이 아닙니다”

임시적으로 문서를 처리하는 것은 전체 개발 팀의 발에 총을 쏘는 것과 같습니다. 팀의 역량이 부족할 경우 문서 유지 관리를 더욱 기술 중심적이고 예측 가능하게 만들어야 하는 강력한 이유가 됩니다.

고치다:

• 문서 개발에 "코드로서의 문서" 접근 방식을 통합합니다. 이렇게 하면 기술적 부채가 누적될 위험 없이 코드베이스와 함께 문서를 반복적으로 업데이트할 수 있습니다.
• 기술 문서를 렌더링하고 단일 정보 소스 역할을 할 수 있는 공간이나 플랫폼을 개발하거나 통합합니다.
• 통합개발환경(IDE)을 활용하세요. IDE를 사용하면 플러그인을 통합하고 문서 개발을 위한 사용자 정의 스크립트를 생성할 수 있습니다. 는 문서 작성을 위한 훌륭한 도구이지만 응용 프로그램 중에서 가장 좋아하는 도구가 있을 수 있습니다.
• 오타를 방지하려면 맞춤법 검사 플러그인을 설치하세요. IDE에 플러그인을 추가하는 과정은 빠르고 쉽습니다.
• 기술 문서 작성 커뮤니티(있는 경우)의 통찰력을 고려하여 회사에서 특별히 제작한 내부 지침을 채택하여 회사 내 문서 개발을 위한 표준화된 접근 방식을 확립하십시오. 이러한 지침을 따르면 문서화 과정이 간소화되어 무엇을 어떻게 정확하게 작성해야 할지 고민하는 시간을 절약할 수 있습니다.
• 지침에 따라 검사를 자동화하여 문서 검토 시간을 크게 줄이거나 없애세요.
• 가능한 모든 것을 템플릿화하고 문서 구성 요소 표준화에 관해 팀과 합의합니다.

기술 문서 작업을 하면서 자신감을 높일 수 있는 귀중한 리소스를 제공하겠습니다. 저는 다음 리소스가 기술 문서를 효과적으로 처리하는 데 도움이 될 만큼 충분히 포괄적이라고 믿습니다.

• " "는 개발자 문서를 위한 포괄적인 핸드북 역할을 합니다. 여기에는 형식 지정, 구두점, 나열 및 코드 블록 추가에 대해 알아야 할 모든 내용이 포함되어 있습니다. 이 가이드는 충분하며 내부 지침을 개발하는 데 귀중한 참고 자료가 되었습니다. 모범 사례.
• “ "는 개발, 작성, 유지 관리 등 개발자 문서 작업과 관련된 모든 사람이 꼭 읽어야 할 책입니다. 이 책에는 기술 문서 작성 분야에서 유명하고 존경받는 여러 저자가 등장합니다.

• " 기술 작가 Anne Gentle의 "는 OpenStack의 문서 문화를 보여주는 실용적인 가이드입니다. 저자는 실제 사례를 통해 문서가 GitHub에서 관리되어야 하는 이유와 효과적인 문서를 위한 기술 프로세스를 구현하는 방법을 설명합니다. 이 책은 또한 유용한 정보를 제공합니다. 개발자인지 기술 작가인지에 관계없이 전문적인 문서 작성에 대한 통찰력을 얻을 수 있습니다.

• 또한 템플릿과 형식 지정 규칙을 포함해야 하는 기술 문서 작성을 위한 내부 지침도 언급하겠습니다. 이러한 지침은 모든 회사에 존재합니다. 일반적으로 기술 작가이자 선구자 및 개발 문서 챔피언과 공동으로 개발되며 팀 내 문서화 문화가 성장함에 따라 발전합니다.

Issue 2. 혼자 문서 작성하기

전체 문서를 단독으로 개발한 다음 검토를 위해 제출하면 의도한 목적에 부합하지 않는 중복되거나 관련 없는 문서가 생성될 위험이 있습니다.

고치다:

• 항상 개요부터 시작하여 팀 리더, 제품 소유자, 기술 작가 또는 전문가 의견을 제공하려는 동료와 공유하세요.
• 위에서 언급한 동일한 동료에게 단계별로 작성하고 검토를 위해 풀 요청을 할당합니다.
• 피드백을 수집하고 작업합니다.
• 의견을 고려하십시오. 그리고 리뷰의 목소리 톤을 여유롭게 하세요. 때로는 거칠게 느껴질 수도 있지만 이는 단지 리뷰 과정의 특징일 뿐입니다.
• 문서 흐름을 간과하지 마십시오. 아래는 우리 회사에서 채택하고 있는 일반적인 흐름이지만, 이 흐름의 특징은 개발팀과 회사에 따라 달라질 수 있습니다.

Issue 3. “이해할 사람은 이해할 것이다”

때때로 나는 팀으로부터 "나는 개발팀을 위해 글을 쓰고 있습니다", "이해해야 할 사람들을 위해 글을 쓰고 있습니다", "이것이 우리 팀 내에서 역사적으로 발전한 방식입니다"라는 말을 듣습니다.

그러나 전문 용어와 영국식 표현에는 적절성과 일관성이 필요합니다. 이를 과도하게 사용하면 미친 엔지니어의 메모와 유사한 문서가 작성될 수 있습니다.

문서화를 위해서는 가능한 가장 간단한 단어와 구조를 사용하세요. 주요 원칙 중 하나는 스크롤을 위한 글쓰기입니다. 문서는 광범위하기 때문에 작성하기 어려울 수 있지만 독자가 처음부터 끝까지 살펴보는 경우는 거의 없습니다. 대신 스크롤하거나 키워드 검색을 사용하는 경향이 있습니다. 그러므로 본문은 어느 부분에서 펼쳐 보아도 쉽게 이해할 수 있어야 한다.

고치다:

• 사전과 최신 규범을 사용하여 영어 용어와 전문 용어를 확인하세요(또는 간단히 Google에서 검색하세요). 사전에 단어가 있으면 해당 언어 철자법의 규칙에 따라 쓰세요.
• 해당 단어가 해당 언어에 없으면 원래 언어로 작성하고 괄호 안에 해당 언어로 번역하여 제공합니다.
• 용어집 섹션에 단어를 추가하고 약어 및 두문자어 목록에 약어를 추가합니다. 이는 "독점적" 약어에 특히 중요합니다(PO에 대해 아무리 많이 언급되거나 쓰여도 그 의미는 문서를 읽을 때 여전히 일반적인 질문 중 하나입니다).
• 일관성 – 문서 전체에서 선택한 쓰기 스타일과 약어를 고수하십시오(회사에서 사용 가능한 모든 문서에 더 좋습니다).
• 문서 탐색을 신중하게 계획하세요. 문서 전체를 읽지 않고도 관련 섹션을 빠르게 찾을 수 있는 방법이 있어야 합니다. 따라서 명확하고 간결한 제목으로 내용을 신중하게 구성하는 것이 중요합니다. 내부 문서 템플릿은 단순성과 편의성을 위해 개발되어야 합니다.

Issue 4. 여러 곳에서 동시에 문서 작성

문서화의 경우 단일 정보 소스, 즉 정확성에 대한 걱정 없이 필요한 정보를 찾을 수 있는 단일 공간을 갖는 것이 중요합니다. 기술 문서의 경우 자체 개발 플랫폼이 그러한 공간 역할을 합니다. 오래된 정보로 인해 오해를 불러일으키는 것을 방지하려면 다양한 공간에서 문서를 조각화하는 것을 피하는 것이 필수적입니다.

고치다:

• 기술 문서를 어디에든 게시하기 전에 회사가 지식 공유를 위해 여러 공간을 사용하는 경우 해당 문서가 다른 곳에 존재하지 않는지 확인하세요.
• 오래된 기술 문서를 보관하거나 삭제합니다(소유권이 있는 경우). 조기 삭제가 우려되는 경우(예: 페이지에 대한 외부 링크로 인해) 페이지가 오래되었음을 알리는 콜아웃과 추가 업데이트가 필요한 유효한 문서의 현재 문서 위치를 추가하세요.
• 귀중한 정보나 통찰력을 발견하면 문서에 추가하세요. Slack이나 다른 곳에, 특히 비공개 채팅에 남겨두지 마세요. 공유할 가치가 있는 지식!

게시자: 안나 곤차로바