프로그래밍 언어 문서화 : 참조 설명서

우리는 제품 라인 전체에서 문서를 수정하고 있습니다. 그 일부에는 시스템의 일부로 사용되는 프로그래밍 언어에 대한 참조 매뉴얼 이 포함되어 있습니다.

프로그래밍 언어에 대한 참조 매뉴얼을 작성할 때 언어에 익숙하지 않은 사용자에게 최대한의 유용성을 제공하도록이를 구성하는 가장 좋은 방법은 무엇입니까?

각 키워드 의 주요 특징 은 무엇입니까 ?

• 통사론
• 기술
• 인수-해당되는 경우
• 반환 값-적용 가능한 경우
• 사용법의 예?
• 내가 누락 된 다른 사람이 있습니까?

개념 (예 : 잠금 전략, 성능 관련 세부 사항)도이 참조 매뉴얼에 문서화되어야합니까, 아니면 별도의 문서입니까?

_{외부 소 비용입니다. 이미 전체 문서 세트를 보유하고 있습니다 ( http://www.rocketsoftware.com/u2/resources/technical-resources 참조 ). 우리가해야 할 일을 해결하기 – 나는 이미 내 생각을 가지고 있지만, 언제나처럼 내 의견에만 의존하지는 않습니다.}

_{대상 : 데이터베이스 및 도구를 사용하여 여러 산업에서 소프트웨어를 생산하는 기술 개발자.}

대상 독자 요구에 따라 문서를 구성하십시오.

귀하의 경우, 주요 대상은 분명히 소프트웨어 개발자입니다. 여기서 고려해야 할 부분은이 부분의 다른 "하위 청중"을 다루는 것입니다.

1. 안녕하세요 세계.
   신속하게 맛을보고자하는 사람들은 샘플 애플리케이션을 빌드하고 실행하여 어떻게 보이는지 확인하십시오.
   관객을 MySQL "15 분 규칙"에서 다루는 것처럼 생각하십시오 .
   

   _{... 다운로드를 마치고 15 분 후에 MySQL을 설치하고 실행할 수있는 사용자.}

2. 기본 사항.
   작동하는 소프트웨어 제작을 시작하는 데 필요한 것들을 빨리 배우려는 사람들을 위해.
3. 고급 주제.
   이미 기본 지식을 익히고 익힌 개발자들에게는 그 이상을 알고 싶어합니다. 기초 에서 다루지 않은 주류 주제 .
4. 스타일 가이드 / 권장 사례.
   일을하는 방법에 관심이있는 사람들을위한 주관적인 조언과지도.
   _{질문은 이것이 귀하의 사례에 상당한 청중을 가질 수 있는지 여부를 나타내지 않으므로 고려해야 할 옵션은 고급 주제 의 일부 / 부록으로 포함 시키 거나 완전히 삭제하는 것입니다.}
5. 쿼크.
   주류 외부에서 모호한 사람들에게 관심이있을만한 모호한 주제. 예를 들어 레거시 회선이 있거나 레거시와의 업그레이드 / 마이그레이션 / 상호 운용성과 같은 항목을 여기에 넣으십시오. 특정 "이국적인"환경에서 일부 기능에 대한 부작용이 있으면이 부분으로 넘어갑니다.

^{매뉴얼의 내용이 의심 스럽거나 모호한 경우 어떻게해야합니까? 특정 개념에 대한 철저한 설명으로 인해 매뉴얼을 읽기가 어려울 경우 어떻게해야합니까? 특정 버전의 설명서에 실수가 있으면 어떻게해야합니까?}

관리자에게 고려해야 할 두 가지 사항은 다음과 같습니다.

1. 기술 / 공식 사양.
   매뉴얼에 의심 스럽거나 모호하고 / 설명하기 어려운 주제가있을 때마다 독자는 사양에서 특정 단락을 참조하여 엄격하고 명확한 "공식적인"진술을 얻을 수 있습니다. 언어 구문에 대한 엄격하고 완전한 (그리고 아마도 지루한) 설명이 더 좋습니다. 사양 에
   대한 가장 중요한 고려 사항 은 가독성을 희생하더라도 기술적 정확성과 완전성입니다.
2. 온라인 보충.
   URL을 예약하고 릴리스 한 모든 문서의 시작 부분에 넣으면 방금 읽은 지옥이 무엇인지 궁금해하는 사람들 이 (수동 유지 관리자를 괴롭히는 대신) 거기에 가서 실수를 설명 할 수 있습니다.

   _{28 페이지의 에라타> 기본 사항> 릴리스 2.2> 오타, 두 번째 문장은 luck로 시작하고 대신 읽기 잠금 입니다.}

예를 들어 수동 관리자는 동시성에 대한 완전하고 정확한 설명과 공식 사양의 잠금에 관심이있는 것 같습니다. Fundamentals 또는 Advanced 주제의 독자는 사양에서 추출하고 요구 사항에 맞게 조정 된 개요 / 소개 / 가이드에 관심이있을 수 있습니다.

_{다른 언어로 제공되는 참조 문서에 대한 비교 연구를 준비하는 것이 도움이 될 수 있습니다. 이 연구가 전에 경험했던 사람들의 경험을 활용하고 실수를 피하는 방법을 배우는 것을 목표로합니다.}

_{마지막은 아니지만 소프트웨어 개발과 유사한 방식으로 문서 개발을 설정하는 것이 좋습니다. 버전 관리, 정식 릴리스, 문제 추적, 품질 보증 등과 같은 것을 의미합니다. 기술 작성자가 그러한 것에 익숙하지 않은 것으로 판명되면 약간의 타협을 원할 수 있습니다. 우리는 완벽한 개발 프로세스를 위해 "교류"콘텐츠를 얻고 싶지 않습니까?}

가장 먼저해야 할 일은 청중을 평가하는 것입니다. 대상 Linux 커널 해커이거나 소프트웨어 도구를 사용하여 업무를 수행하지만 소프트웨어 자체에 관심이없고 CS 배경이없는 하드웨어 설계자입니까? 전기 기술자는 const와 non-const 인수, 객체에 대한 포인터, 참조에 대한 포인터 등의 차이점에 대해 완전히 명확하지 않을 수 있습니다. 기본 요소에 이름이 오버로드 된 경우 해당 개념을 대상 사용자에게 적절한 수준으로 설명하는 것이 좋습니다. C ++ 프로그래머라면 아무것도 아닐 것입니다.

두 번째로 평가해야 할 것은 언어의 기본 요소의 세분성입니다. 세분성이 높을수록 각 기본 요소의 구문 스펙에 근접한 사용 예제를 더 많이 제공해야합니다. 즉, 컨텍스트를 인스턴스화하는 저수준 프리미티브가 있고 유용한 것을 수행하기 전에 세 가지 다른 저수준 프리미티브로 작업 해야하는 경우 유용한 함수의 완전한 예를 더 잘 볼 수 있습니다. 매뉴얼에서. 거의 사용할 수없는 문서에 대한 훌륭한 반례 는 온라인 openssl 설명서를 참조하십시오 .

기능의 부작용 에 대한 설명을 반드시 포함하십시오 .

어쨌든, 고객 프로그래머가 매일 밤 자기 전에 저주를하지 않게하려면, 일부 고급 기능 기본 요소를 수행하는 테스트 된 예제 코드를 많이 포함 시키십시오. 예제는 코드 스니 펫일뿐 아니라 완벽하고 컴파일 가능하거나 즉시 실행 가능한 것이어야합니다.

전통적으로 기술 작가는 참조 매뉴얼 과 사용자 안내서를 구분했습니다 . 참조 매뉴얼에는 일반적으로 구문 사양, 기능 또는 기본 요소의 이해하기 쉬운 정의, 문제에 대한 설명, 성능 및 부작용, 간단한 사용 예가 포함됩니다. 사용 설명서에는보다 확장 된 사용 예와 광범위한 엔지니어링 문제에 대한 설명이 포함되어 있습니다. Kernigan과 Ritchie "C Programming Language"는이 컨벤션에 대한 훌륭한 예이지만,이 방법은 문서화하는 언어가 비교적 간단한 경우에만 작동합니다.

필자는 1987 년에서 1991 년 사이에 Ready Systems Inc의 개발 센터에서 엔지니어링 서비스 부서의 관리자로 5 명의 기술 작가로 구성된 팀을 관리했습니다.