오픈 소스 프로젝트 관련 문서에 대한 권장 사항은 무엇입니까?

우리는 풋내기 인 open source project을 문서화하고 있으며, 좋은 방법이나 도구에 대한 제안을 원합니다. 또한 개발자로서 온라인 문서, 위키 기반 문서, 도움말 파일 또는 다른 것을 선호합니까?오픈 소스 프로젝트 관련 문서에 대한 권장 사항은 무엇입니까?

출처

2009-02-01 ccook

가능한 [훌륭한 API 문서 작성 : 도구 및 기법] (0120-337-0000) – Mark

이 질문에 1 년을 물었습니다. 'duplicate'하기 전에 :) – ccook

응용 프로그램이 C#으로 개발됨에 따라 API 설명서를 생성하기 위해 Doxygen을 살펴보십시오. 이것은 매우 강력합니다 (표준 javadoc 스타일 멤버 문서를 수행하지만 호출, 상속, 파일 종속성 및 공동 작업 그래프도 생성합니다). 그 힘에도 불구하고 사용하기 쉽습니다. HTML, 라텍스, 맨 페이지 등 다양한 형식의 API 문서를 생성 할 수 있습니다.

설명서, 자습서 및 기타보다 유연한 유형의 문서를 작성하려면 위키 설정을 심각하게 고려하십시오. 나는 많은 성공과 함께 DokuWiki을 사용했습니다. 구문 강조를 지원하므로 코드 프로젝트에 유용합니다. 또한 오픈 소스 프로젝트에 유용 할 사용자 ACL도 있습니다. 또한 PHP와 데이터베이스가 필요하지 않습니다. 물론 버전 관리와 같은 표준 wiki 기능을 제공합니다.

마지막으로 위키, 버전 관리, 버그 추적기 하이브리드 인 trac을 언급해야합니다. 확실히 볼만한 가치가 있습니다.

출처

2009-02-01 19:07:13 wilsoniya

실제로 오픈 소스 프로젝트를 후원하지는 않았지만 내가하는 많은 작업은 공동 작업입니다. 필자는 적절한 권한을 가진 위키가 사람들이 공통 문서 작성에 협조 할 수있는 훌륭한 방법이라는 것을 알았습니다. 제 경우에는 일반적으로 개발 이야기입니다. 저는 고객과 고객이이를 생성하는 작업을합니다. 나는 이것이 당신의 프로젝트를위한 협업 문서에서도 잘 작동한다고 생각한다.

출처

2009-02-01 16:26:09 tvanfosson

나는 wiki에 대한 아이디어를 좋아한다. – ccook

같은 소리는 Sandcastle과 같이 적합합니다.

출처

2009-02-01 16:42:16 Irwin

제가 선호하는 모든 것을 포함하는 방식은 위키를 사용하는 것입니다. 그러나 소스 코드에서 문서를 자동 생성하는 기능을 좋아합니다. 거기에 많은 도구가 있지만 나는 특히 좋아한다 SandCastle입니다. 그것은 대부분의 .NET 개발자가 이미 사용 경험이 있어야하며 .NET에서 빌드 된 것으로 보이는 MSDN 문서에서와 동일한 스타일을 제공합니다. 지금까지 알 수 있듯이 지원되는 최신 프레임 워크는 .NET 2.0입니다.

출처

2009-02-01 17:00:49 user61230

온라인 문서는 항상 좋은 생각입니다. 특히 위키를 기반으로 할 때 특히 좋습니다. 그들은 더 많은 검색이 가능하고, 실수의 경우에 보관 된 역사가 있으며, 긴 문서화 서술의 "설탕"이 없기 때문에 일반적으로 더 짧습니다. 그러나 기사의 이름 지정 및 링크에 특별한주의를 기울여야합니다.

그러나 프로젝트 코드의 특정 부분이 API로 작동하는 경우 관련 지식을 코드에 캡처해야 IDE의 "호출 위에 마우스를 놓기"메커니즘을 사용하여 탐색 할 수 있습니다. 지식의 비 국가 화는 큰 문제이며 사람들은 일반적으로 컨텍스트 전환을 꺼립니다. 함수 머리글 문서에 무언가가 표시되면 다른 곳에서 나타나는 것보다 더 높은 (전체적으로 그렇게 높지는 않지만) 항상 읽힐 가능성이 있습니다.

함수 헤더 문서를 작성할 때 클라이언트에 직접 영향을주는 지시문에 초점을 맞 춥니 다. 이는 필수적 일 수 있습니다 (예 : X를 먼저 호출). 유익한 정보 (예 : X ...를 알고 있어야 함).

출처

2009-02-01 19:13:36 Uri

는 Doxygen을이 API/프로그래머 문서에 대한
을 Docbook XML은/SGML은 (HTML에서 사용할 수있는 온라인 버전) 공식 PDF 매뉴얼
사용자가 만든 물건에 대한 위키에 대한

는 어떻게 다른 사람을 참조 그것 (내가 말한 큰 오픈 소스 프로젝트)

그러나 나는 다른 위키 (다른 포스터에 의해 언급)와 떨어져 어떤 official 설명서 alw입니다 구조/가이드 라인에 필요한 것들. 위키는 knowledge base에 대한 것입니다. IMHO

출처

2009-02-01 19:52:25 kazanaki

제가 개인적으로 작성한 문서는 Sphinx입니다. ReST으로 작성된 문서를 LaTeX (인쇄/PDF 용) 또는 HTML로 처리합니다.

doxygen과 같은 API 문서 도구를 사용하여 에만을 사용하지 않는 것이 좋습니다. 그것도 사용하는 것이 좋지만 문서의 유일한 형태가되어서는 안됩니다.

사용자 커뮤니티의 활동 방식에 따라 요리법이나 다른 자습서에 위키를 추가하는 것이 좋습니다. 그 내용은 스핑크스가 사용하는 ReST 문서로 수시로 접을 수 있습니다.

출처

2009-02-01 20:02:13 Ryan

오픈 소스 프로젝트 관련 문서에 대한 권장 사항은 무엇입니까?

답변

관련 문제