문서화 된 문서 : 개발자 가이드
프로젝트를 만들고 유지 관리하는 데 관련된 모든 작업으로 인해 문서를 작성하면 균열을 겪을 수 있습니다. 그러나 좋은 문서는 모든 프로젝트의 큰 자산입니다. 이점을 고려하십시오.
- 더 나은 협업: 명확하고 일관된 문서는 직계 팀에서 외부 이해 관계자에 이르기까지 모든 사람이 같은 페이지에있게합니다. 또한 DOCS는 독립적 인 문제 해결을 촉진하여 핵심 기고자에게 모든 질문에 대답하는 시간과 노력을 절약합니다.
- 더 매끄러운 온 보딩: 시작하는 방법을 제공하고, 핵심 개념을 설명하고, 튜토리얼 스타일 컨텐츠를 포함하여 좋은 문서화를 통해 새로운 팀원들은 신속하게 증가 할 수 있습니다.
- 입양 증가: 프로젝트를 이해하고 설정하고 실행하기가 더 쉬울수록 누군가가 프로젝트를 사용할 가능성이 높아집니다.
이러한 이점을 염두에두고 문서화의 중요한 원칙을 살펴보고 프로젝트에 효과적인 문서를 빠르게 만들 수있는 방법을 살펴 보겠습니다.
문서의 주요 신조
프로젝트를 문서화 할 때 따라야 할 세 가지 주요 원칙이 있습니다.
명확하게 유지하십시오
이해하기 쉬운 일반 언어를 사용하십시오. 목표는 문서를 최대한 액세스 할 수 있도록하는 것입니다. 좋은 지침은 문서에 대상 고객의 일부 사람들이 이해하지 못하는 약어 나 기술 용어가 있는지 스스로에게 물어 보는 것입니다. 이 경우 더 간단한 언어로 교체하거나 문서에 정의되어 있는지 확인하십시오.
간결하게 유지하십시오
필요한 정보 만 문서화하십시오. 가능한 모든 엣지 케이스를 덮으려고하면 독자들을 압도 할 것입니다. 대신, 대다수의 독자들이 시작하는 데 도움이되는 문서를 작성하고 핵심 개념을 이해하며 프로젝트를 사용합니다.
또한 각 문서가 특정 주제 나 작업에 중점을 두십시오. 필요한 정보가 필요하지 않은 정보를 포함하는 경우 별도의 작은 문서로 옮기고 도움이 될 때 링크하십시오.
구조적으로 유지하십시오
스캔하고 이해하기 쉽도록 각 문서의 구조를 고려하십시오.
- 가장 중요한 정보를 먼저 배치하여 문서가 문서와 관련이 있는지 독자가 신속하게 이해하도록 도와줍니다.
- 제목과 목차를 사용하여 독자에게 특정 정보를 찾을 수있는 곳을 알려줍니다. 공통 제목이있는 문서 템플릿을 사용하여 구조화 된 컨텐츠를 빠르고 일관되게 작성하는 것이 좋습니다.
- 독자가 컨텐츠를 스캔하도록 도와주기 위해 Boldface 및 Bulleted Lists와 같은 형식의 요소와 같은 텍스트 강조 표시를 사용하십시오. 강조 된 텍스트가 눈에 띄도록 10% 이하의 텍스트 강조 표시를 목표로합니다.
- 스타일링과 일치하십시오. 예를 들어, 중요한 용어를 한 문서에 굵게 표시하면 다른 내용에서도 동일하게 수행하십시오.
문서 구성
개별 문서를 작성할 때 따라야 할 원칙이있는 것처럼, REPO에서 문서를 구성하기위한 프레임 워크를 따라야합니다.
Repo에는 문서를 구성하는 데 많은 접근 방식이 있지만 여러 프로젝트에 사용한 것은 Diátaxis 프레임 워크입니다. 이것은 프로젝트와 관련된 모든 문서를 구성하는 체계적인 접근법입니다.
저장소 문서를 문서화하는 데 체계적인 접근 방식을 적용하면 사용자가 필요한 정보를 쉽게 알 수 있습니다. 이것은 좌절감을 줄이고 사람들이 프로젝트에 더 빨리 기여할 수있게합니다.
Diátaxis는 목적에 따라 문서를 네 가지 범주로 나눕니다.
- 튜토리얼: 학습 지향 문서
- 방법 안내: 특정 작업에 대한 목표 지향 지침
- 설명: 프로젝트에 대한 이해를 제공하는 토론
- 참조: 기술 사양 및 정보
저장소의 각 문서는 이러한 범주 중 하나에 적합해야합니다. 이를 통해 사용자는 새로운 개념을 배우거나 특정 문제를 해결하거나 기본 원칙을 이해하거나 기술적 인 세부 사항을 찾아야하는지 여부에 관계없이 현재 상황에 대한 적절한 자원을 신속하게 찾을 수 있습니다.
또한 저장소가 누락 된 문서를 식별하는 데 유용한 안내서가 될 수 있습니다. 리포지토리가 참조 문서가없는 도구가 있습니까? 기고자들이 저장소를 시작할 수있는 튜토리얼이 충분합니까? 저장소 내에서 달성 해야하는 일반적인 작업 중 일부를 설명하기위한 방법 안내서가 있습니까?
이 프레임 워크에 따라 문서를 구성하면 프로젝트의 주요 컨텐츠를 구축하고 유지 관리하는 데 전체적인 접근 방식을 취할 수 있습니다.
작성자가 작성했습니다
Post Comment