개발자가 문서를 건너 뛰지 않아야하는 이유

모바일 응용 프로그램, 웹 응용 프로그램, 데스크톱 응용 프로그램 또는 JavaScript 라이브러리의 개발 영역에서 설명서는 소프트웨어의 개발 성공 여부를 결정할 수있는 중요한 역할을합니다. 그러나 문서를 작성해 본 사람이라면 개발자가 할 일이 가장 덜 마음에 들었다고 나에게 동의한다..

코드 작성 (개발자가 서명 한 것)과 달리, 문서 (우리는하지 않았 음)는 다음과 같이 쉽게 소화해야합니다. 각자 모두. 기술적으로는 기계 언어 (코드)를 인간이 이해할 수있는 언어로 변환해야합니다..

실제 부담이 될 수 있지만 문서 작성은 중요하며 사용자, 동료 및 특히 자신에게 이점을 제공합니다..

좋은 문서는 사용자를 돕는다.

독자가 도움이되는 설명서 코드 작동 방식 이해하기, 명백하게. 그러나 많은 개발자들은 소프트웨어 사용자가 능숙하다고 가정하는 실수를 범합니다. 따라서 설명서는 처음부터 포함시켜야 할 많은 필수 요소를 건너 뛰고 얇은 재질 일 수 있습니다. 언어에 정통한 사람이라면 자신이 주도적으로 생각할 수 있습니다. 그렇지 않다면 잃어버린 것입니다..

사용자를위한 문서는 일반적으로 실제 사용 또는 “어떻게”. 일반적인 사용자를위한 문서를 만들 때 경험 법칙은 그것은 명확해야한다. 인간 친화적 인 단어를 사용하는 것이 기술적 인 용어 나 전문 용어보다 바람직합니다. 실제 사용 예제 또한 크게 감사하겠습니다..

좋은 레이아웃 디자인은 사용자가 눈을 피로하지 않고도 문서의 각 섹션을 스캔하는 데 도움이됩니다. 몇 가지 좋은 예 (일명 즐겨 찾기)는 Bootstrap 및 WordPress의 설명서입니다. “WordPress의 첫 단계”.

다른 개발자들에게도 도움이됩니다.

각 개발자는 고유 한 코딩 스타일을 갖습니다. 그러나 팀에서 일할 때는 다른 팀 동료와 코드를 공유해야하는 경우가 많습니다. 따라서 표준에 대한 공감대가있다. 모두를 같은 페이지에두기. 적절하게 작성된 문서는 팀이 필요로하는 참조 일 것입니다.

그러나 최종 사용자 설명서와 달리이 설명서에서는 일반적으로 기술 절차 코드 네이밍 규칙, 페이지 구성 방법 및 API가 코드 예제와 함께 작동하는 방식을 보여줍니다. 종종 우리는 코드와 함께 문서를 인라인으로 작성해야합니다 ( 코멘트)를 사용하여 코드가 수행하는 작업을 설명합니다..

또한, 가지고있는 경우 신입 회원 가입 팀이 나중에이 문서를 교육하는 것이 시간 효율적 일 수 있으므로 코드에 대해 1 대 1로 실행하지 않아도됩니다..

이상하게도 코더에 도움이됩니다.

코딩에 관한 재미있는 점은 때때로 개발자들조차도 그들이 작성한 코드를 이해하지 못합니다.. 이것은 특히 몇 년 또는 몇 년 동안 코드가 변경되지 않은 경우에 해당됩니다.

한 가지 이유 또는 다른 이유로 코드를 재검토해야 할 필요가있을 때이 코드를 작성할 때 마음 속에 무슨 일이 벌어지고 있는지 궁금해 할 것입니다. 놀라지 마라. 나는이 상황에 처해 있었다.. 이것은 정확하게 내가 ~ 싶다 내 코드를 제대로 문서화했다..

코드를 문서화하면 코드 하단에 좌절하지 않고 신속하게 접근 할 수 있으므로 변경 사항을 가져 오는 데 많은 시간을 할애 할 수 있습니다..

좋은 문서를 만드는 이유?

좋은 문서를 만드는 몇 가지 요소가 있습니다..

1. 결코 가정하지 마라.

사용자가 무엇을 알고 있다고 가정하지 마십시오. 당신 알고있을뿐만 아니라 무엇을 그들 알고 싶어요. 항상 더 좋다. 처음부터 시작하기. 사용자의 숙련도에 관계없이.

예를 들어 jQuery 플러그인을 만든 경우 SlickJS의 설명서에서 영감을 얻을 수 있습니다. HTML을 구조화하는 방법, CSS와 JavaScript를 넣을 위치, 가장 기본적인 레벨에서 jQuery 플러그인을 초기화하는 방법, 그리고이 모든 것들을 추가 한 후에 완벽한 최종 마크 업을 보여주는 방법을 보여줍니다..

결론은 문서가 개발자가 아닌 사용자의 생각 프로세스로 작성되었다는 것입니다. 이 방법으로 자신 만의 문서에 접근하면 자신의 작품을 구성하는 데 더 나은 시각을 얻을 수 있습니다..

2. 표준을 따른다.

코드와 인라인으로 연결되는 문서 추가시, 언어의 예상 표준을 사용한다.. 각 함수, 변수 및 함수가 반환 한 값을 설명하는 것이 항상 좋은 생각입니다. 다음은 PHP를위한 좋은 인라인 문서의 예제입니다.

 / ** * 바디 클래스의 배열에 사용자 정의 클래스를 추가합니다. * * @param array $ classes body 요소의 클래스. * @return 배열 * / function body_classes ($ classes) // 게시자가 두 명 이상인 블로그에 그룹 블로그 클래스를 추가합니다. if (is_multi_author ()) $ classes [] = 'group-blog';  반환 $ 클래스;  add_filter ( 'body_class', 'body_classes'); 

다음은 PHP, JavaScript 및 CSS의 모범 사례가 적용된 인라인 문서 서식에 대한 참고 자료입니다.

• PHP: WordPress 용 PHP 문서 표준
• 자바 스크립트: UseJSDoc
• CSS: CSSDoc

SublimeText를 사용하는 경우 인라인 문서로 코드를 미리 채울 DocBlockr을 설치하는 것이 좋습니다..

3. 그래픽 요소들

그래픽 요소를 사용하면 텍스트보다 효과적입니다. 이 미디어는 특히 그래픽 인터페이스로 소프트웨어를 제작할 때 유용합니다. 화살표, 원 또는 화살표와 같은 포인팅 요소를 추가 할 수 있습니다. 사용자가 추측하지 않고 단계를 수행하기 위해 어디를 가야하는지 파악하는 데 도움이 될 수있는 모든 것.

다음은 영감을 얻을 수있는 Tower 앱의 예입니다. 그들은 버전 제어가 즐겁게 작동하는 방식을 일반 텍스트 명령 줄을 사용하는 것보다 이해하기 쉽게 설명합니다.

4. 섹션

글 머리 기호 목록 및 표 내의 문서에서 몇 가지 사항을 래핑하면 긴 내용으로 인해 사용자가 더 쉽게 스캔하고 읽을 수 있습니다..

내용의 테이블을 추가하고 문서를 쉽게 소화 할 수있는 섹션으로 분할하면서 각 섹션을 다음 섹션과 관련되게 유지하십시오.. 짧고 간단하게. 아래는 Facebook에서 잘 정리 된 문서의 예입니다. 목차는 우리가 클릭으로 뛰어 넘고 싶은 곳에서 우리를 데려 간다..

5. 수정 및 업데이트

마지막으로 실수 나 수정을 위해 문서를 검토하고 필요할 때 또는 제품, 소프트웨어 또는 라이브러리에 중요한 변경이있을 때마다 수정하십시오. 제품과 함께 정기적으로 업데이트되지 않으면 문서가 아무 쓸모가 없습니다..