코드 문서를 어디에 두어야합니까?

현재 두 가지 시스템을 사용하여 코드 문서를 작성하고 있습니다 (C ++ 사용).

• 메소드 및 클래스 멤버에 대한 문서는 Doxygen 형식을 사용하여 코드 옆에 추가됩니다. 서버에서 Doxygen은 소스에서 실행되므로 출력은 웹 브라우저에서 볼 수 있습니다
• 개요 페이지 (클래스 세트 설명, 애플리케이션 구조, 예제 코드 등)가 Wiki에 추가됩니다.

개인적 으로이 방법은 멤버와 클래스에 대한 문서가 코드에 가깝기 때문에 개요 페이지가 Wiki에서 편집하기 쉽고 (이미지, 테이블 등을 추가하기도 쉽기 때문에)이 방법이 쉽다고 생각합니다. 웹 브라우저를 사용하면 두 설명서를 모두 볼 수 있습니다.

내 동료는 이제 Doxygen에 모든 것을 넣을 것을 제안합니다. 그러면 Microsoft의 HTML WorkShop 또는 Qt Assistant를 사용하여 하나의 큰 도움말 파일을 그 안에 포함시킬 수 있습니다. 내 우려는 특히 표, 이미지를 추가하고 싶을 때 Doxygen 스타일 문서를 편집하는 것이 훨씬 어렵습니다 (위키와 비교할 때 ...). 결과를 볼 수 있기 전에 코드?)

대규모 오픈 소스 (또는 비공개 소스) 프로젝트에서 코드 문서 작성에 사용하는 것은 무엇입니까? 그들은 이것을 Doxygen 스타일과 Wiki로 나누었습니까? 아니면 다른 시스템을 사용합니까?

문서를 공개하는 가장 적절한 방법은 무엇입니까? 웹 서버 / 브라우저를 통해 또는 큰 (100MB) 도움말 파일을 통해?

코드 문서를 작성할 때 어떤 접근법을 사용합니까?

두 개가 아닌 하나의 시스템 에 모든 문서를 두는 것이 실제로 유리할 수 있습니다. 백업 및 복원, 버전 관리, 전역 검색, 전역 검색 및 교체, 교차 연결 및 문서 작성시 모든 문서를 하나의 최종 문서에 배치하면 일반적으로 서로 다른 두 가지를 유지할 필요가 없을 때 "마찰"이 줄어 듭니다. 겹치는 용량을 가진 시스템.

다른 한편으로, 당신은 이러한 장점이 위키의 용이함을 능가하는지 생각해야합니다. 위키를 사용하면 편집 / 생성 / 정의 수정 / 다시 생성 서클이 더 빠를 수 있습니다. 개요 페이지를 별도의 doxygen 하위 프로젝트로 유지하는 doxygen을 사용하면 사이클을 매우 빠르게 얻을 수 있다고 생각합니다. 물론 "빠른 미리보기"를 대체하는 것이 아니라 그 방향을 향한 단계 인 doxygen 의 외부 연결 기능을 사용할 수 있습니다 . 나는 지금까지 혼자서 이것을하지 않았지만, 그것이 당신의 경우에 효과가 있는지 알고 싶다면 스스로 시도해야한다고 생각합니다.

다른 프로젝트와 관련하여 : doxygen과 같은 도구는 주로 라이브러리 문서 용이라고 생각합니다. 타사 라이브러리 공급 업체가 아니며 라이브러리를 사용하는 모든 사람이 소스 코드에 완전히 액세스 할 수있는 경우 doxygen과 같은 도구가 필요합니다. 예를 들어, 우리 팀에는 최종 사용자 문서와 데이터베이스 모델 문서를 제외하고 코드 외부에 외부 문서가 거의 없습니다. 이러한 종류의 문서화를위한 주요 도구는 docbook 및 fop 이며 만족스러운 결과를 제공합니다.

먼저 코드 설명서를 사용하십시오. 가능하면 Wiki 및 기타 방법 추가

나는 그것을 유지하기가 어려울 것입니다.

실용 답변 :

실제로 개발자가 가장 먼저하는 일은 코드를 확인하는 것입니다.

개발자로서 Wiki (s), 매뉴얼과 같은 외부 문서를 갖고 싶습니다. 그러나 가장 먼저하는 일은 코드를 검토하는 것입니다 (때로는 다른 개발자, 때로는 내 자신의 코드).

여러 프로젝트 및 고객에서 일한 개발자로서 가능한 한 외부 문서를 추가하려고하지만 많은 작업량을 갖고 위키를 지원할 수없는 것이 일반적입니다.

때로는 프로젝트 관리자 및 다른 상사들이 문서화에 신경 쓰지 않고 때로는 다른 개발자들도 신경 쓰지 않습니다.

그리고 내가 할 수있는 최선의 방법은 코드에 주석을 추가하는 것입니다.

행운을 빕니다

일부는 다른 시스템을 사용합니다- 예를 들어 파이썬의 스핑크스 를 살펴보십시오 . 모든 것을 구축하는 올인원 문서 시스템이 있습니다 (C / C ++에서도 작동합니다)

나는 항상 문서가 코드와 분리되어 있다고 생각하고 doxygen은 훌륭하지만 '문서'가 아닌 API에 대한 개요입니다. 이를 위해 위키는 훌륭하지만 ASCIIDOC 를 사용 하고 그 결과를 코드와 함께 소스 제어에 저장하는 것을 선호합니다 . 주로 다른 사람 (예 : 테스터, 고객 등)에게 PDF를 생성 할 수 있기 때문입니다.

Doxygen을 사용하면 생각할 수있는 거의 모든 PDF, HTML, 위키 페이지를 작성할 수 있습니다.

개인적으로 선호하는 것은 Doxygen과 Wiki와 스크립트가 발산 될 때 확인하는 것입니다.

버전 1.8.0부터 doxygen 은 Markdown을 지원하므로 위키 시스템에서와 마찬가지로 정적 페이지 작성 경험을 편리하게 수행 할 수 있습니다.

대상 고객

이 질문에 대답 할 때이 문서를 읽을 사람을 물어봐야한다고 생각합니다. 개발자는 사용자 또는 비즈니스 분석가와 크게 다른 요구를 가지고 있습니다.

• 개발자로서 : 연구중인 코드와 관련된 문서, 인터페이스 계약과 같은 세부 사항 및 사용 예. 아마도 일부 고급 문서와 프로토콜 사양이 적합 할 것입니다.
• 사용자로서 : 도움말 메뉴 또는 소프트웨어 사용 방법에 대한 액세스 가능한 웹 사이트를 통해 제공되는 설명서.
• 비즈니스 분석가 : 문서 또는 액세스 가능한 웹 사이트로 제공되는 문서가 유용합니다. 프로토콜, 높은 수준의 아키텍처 및 사용 사례에 대한 적절한 세부 정보가 가장 좋습니다.

유지

이 문서의 소스를 어디에 둘 것인지는 청중과 청중을 위해 글을 쓰는 사람에 따라 다릅니다.

• 개발자 집만 있습니까? 코드에 모든 것을 넣습니다. 업데이트하도록 권장합니다. 문서 업데이트가 코드 변경만큼 중요하도록 권장하는 문화를 연구해야합니다.
• 개발자 및 문서 작성자가 있습니까? 책임을 나눈다. 개발자를위한 개발자 중심 도구를 사용하고 문서 작성자를 위해 문서 작성 도구를 사용하십시오.

가능한 경우 코드 예제 또는 사용 사례를 실행할 수 있는지 확인하십시오. 실행을 자동화하고 내부적으로 오류를 표시합니다. 이러한 페이지가 잘못되었거나 문서가 잘못되었을 수 있습니다.

또한 문서를 작성하기 위해 선택한 도구가 무엇이든 특정 버전의 문서를 특정 버전의 코드와 연관시킬 수있는 안정적인 수단이 필요합니다. 이는 단일 상록 배포로 행복한 클라우드 환경에서도 여전히 유용합니다.

문서 통합

일부 문서를 작성하려면 통합이 필요할 수 있지만 사용자는 한 곳에서 필요한 모든 문서에 액세스 할 수 있어야합니다.

비즈니스 분석가는 API 사양, 디자인 사양 및 사용 시나리오가 별도의 문서 또는 웹 사이트의 별도 섹션에있는 것에 매우 만족합니다.

개발자는 소스에서 볼 수있는 모든 것을 선호하지만 동일한 체크 아웃 내에서 코드 외부에 몇 가지 고급 디자인 문서와 자세한 프로토콜 사양 문서를 제공하는 것이 매우 기쁩니다.

너의 경우

솔직히 말해서, 위키의 문서는 아마도 코드베이스의 문서와 같은 종류가 아닐 수도 있습니다. 병합하는 것도 이치에 맞지 않을 수 있습니다.

반면에 두 가지를 통합하면 몇 가지 간단한 방법으로 얻을 수 있습니다.

• doxygen과 같은 소스 문서 도구는 HTML을 생성 할 수 있으며 위키는 웹 서버에 있습니다. 위키와 함께 빌드 된 버전을 제공하고이 둘을 서로 연결하는 것은 단순한 통합 지점입니다.
• 일부 위키 제품을 사용하면 코드베이스에 체크인 할 수있는 파일에서 직접 위키를 실행할 수 있습니다. 이것은 문서를 코드와 쌍으로 유지하면서 간단한 wysiwyg 툴링을 제공합니다.
• pdf와 같은 다른 형식도 수용 할 수 있지만 사용하려는 특정 툴링이 나타납니다. 위키를 마크 다운 파일로 긁어 doxygen (또는 다른 도구)을 통해 제공하는 것이 좋습니다. 위키와 소스를 별도로 pdf로 작성하고 pdf 병합 도구를 사용하는 것이 좋습니다.

하루가 끝나면 유지 관리 비용이 저렴한 문서 시스템을 파악하고 개발자, 비즈니스 분석가 및 사용자의 대상이 보는 것처럼 고품질 제품을 제공하는 데 도움을줍니다. 이들 그룹 중 하나를 방해하는 것은 반드시 제품 품질을 떨어 뜨릴 것입니다.

ASCII를 사용하는 경우 문서 데이터 숨기기를 소스 코드의 높은 비트에 저장해야합니다! 그런 다음 가장 똑똑한 사용자 (읽기 : 가치가있는 사용자) 만 문서를 사용할 수 있습니다.

문서를 잘 정의되고 쉽게 내보낼 수있는 휴대용 형식으로 만드는 것이 실제로 유리할 수 있습니다. 스핑크스 가 죽는 경우 (아마도) 다른 시스템으로 변환하면 스크립트 작업이 될 것입니다. 위키에서 데이터를 옮기는 것은 (아마도 독점 형식으로 데이터베이스에 저장되어있을 수도 있습니다).