웹 개발자를 위한 '좋은 문서를 작성하는 방법'

 

 

 

웹 개발을 위한 코드 작성과 달리, 문서는 모든 사람들이 쉽게 알 수 있도록 해야 합니다.

사람들이 이해할 수 있는 언어로 코드를 번역해야 하는 이 작업은 꽤나 어렵습니다.

 

하지만 문서를 작성하는 것은 필수적입니다.

좋은 문서를 작성한다면, 고객과 동료, 특히 개발자 자신에게도 많은 이점을 제공할 것입니다.

 

 

좋은 문서의 이점

 

 

1. ‘사용자’에게 도움이 된다

 

좋은 문서는 사용자가 코드가 어떻게 작동하는지 정확히 이해할 수 있도록 합니다.

수많은 개발자들은 사용자들이 능숙할 것이라고 가정해버리는 실수를 합니다.

 

 

- 일반 사용자를 위한 문서를 작성할 때는 명확하게 작성합니다.

 

- 기술적이고 전문적인 용어보다 인간 친화적인 단어를 사용합니다.

 

- 눈의 피로가 없도록 좋은 레이아웃 디자인을 사용합니다.

(Ex. Bootstrap 및 WordPress의 "First Steps With WordPress")

 

 

 

2. ‘동료 개발자’에게 도움이 된다

 

모든 개발자마다 자신만의 코딩 스타일이 있습니다.

그러나 팀과 함께 작업할 때는 다른 팀원과 코드를 공유를 해야 하기 때문에, 표준에 대한 합의가 있어야 합니다.

적절하게 작성된 문서는 팀이 필요로 하는 참고 자료가 될 것입니다.

 

 

- 코드 이름 지정 규칙과 같은 코딩 기술을 설명하고, 특정 페이지를 구성하는 방법과

API가 코드 일러스트레이션과 함께 작동하는 방법을 보여줍니다.

 

- 코드가 수행하는 일을 설명하기 위해 코드와 함께 문서를 인라인으로 작성해야 합니다.

 

- 나중에 팀에 새 구성원이 합류하는 경우 이 문서는 효율적인 교육 방법이 될 것입니다.

코드에 대해 1:1로 실행할 필요가 없을 것입니다.

 

 

 

3. ‘코더‘에게 도움이 된다

 

코딩의 재미있는 점은 웹 개발자도 가끔 자신이 작성한 코드를 이해하지 못한다는 것입니다.

코드를 작성한 지, 긴 기간이 지났을 때에 특히 그렇습니다.

 

갑자기 코드를 방문해야 하는 경우, 내가 이 코드를 작성할 때 뇌에서 무슨 일이 있었는지 궁금해할 수도 있습니다.

놀랄 일은 아닙니다. 저도 이런 상황을 겪은 적이 있으니까요.

 

 

- 코드를 문서화하면 코드 기반에 신속하게 접근할 수 있습니다.

 

- 작업하는 과정에서 많은 시간을 절약할 수 있습니다.

 

 

 

 

좋은 문서를 작성하는 방법

 

 

 

1. 사용자가 모두 알고 있다고 생각하지 마라

 

사용자의 숙련도와 상관없이 처음부터 시작하는 것이 좋습니다.

 

예를 들어 jQuery 플러그인을 구축했다면 SlickJS 문서에서 영감을 얻을 수 있습니다.

HTML을 구성하는 방법, CSS와 JavaScript를 넣을 위치, 가장 기본적인 수준에서 jQuery 플러그인을 초기화하는 방법,

이러한 모든 항목을 추가한 후의 완전한 최종 마크업까지 보여줍니다.

 

 

 

결론은 문서가 개발자가 아닌 사용자의 사고 과정으로 작성되어야 합니다.

 

 

 

2. 코딩의 표준을 따르라

 

코드와 일치하는 문서를 추가할 때 해당 언어의 표준을 사용하세요.

코딩의 각 부분, 변수 및 함수에서 반환하는 값을 설명하는 것이 좋습니다.

 

다음은 PHP에 대한 좋은 인라인 문서의 샘플입니다.

 

 

 

 

3. 그래픽 요소를 사용하라

 

그래픽 요소를 사용하면 어떤 콘텐츠보다 더 효과가 좋습니다.

특히 그래픽 인터페이스로 프로그래밍을 구성하는 경우에 유용합니다.

사용자가 쉽게 파악할 수 있도록 화살표, 원 과 같은 포인팅 요소를 추가할 수 있습니다.

 

 

 

4. 단면화 하라

 

문서의 몇 가지 항목을 글머리 기호 목록과 표로 래핑 해보세요.

그러면 사용자가 콘텐츠를 쉽게 읽을 수 있습니다.

 

각 섹션은 다음에 올 내용과 관련이 있도록, 짧고 간단하게 유지합니다.

 

(Ex. Facebook에서 잘 정리된 문서. 목차는 클릭 한 번으로 이동하려는 곳으로 이동합니다.)

 

 

 

5. 수정 및 업데이트를 지속적으로 하라

 

마지막으로 문서에서 실수가 있는지 검토하고, 변경 사항이 있을 때마다 지속적으로 수정하는 것이 좋습니다.

정기적으로 업데이트가 되지 않으면 누구에게도 유익하지 않을 것입니다.

 

 

 

 

 

 

*본문 내용은 (https://www.hongkiat.com/blog/why-documentation-essential/)를 각색한 자료입니다.