소프트웨어 문서를 저장하는 가장 좋은 방법은 무엇입니까?[닫은]
https://stackoverflow.com/questions/99419
-
01-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian문제
분명한 대답은 "내부 위키"입니다.소프트웨어 문서화에 사용되는 위키의 장점과 단점은 무엇입니까?다른 제안이 있나요?소프트웨어 문서화에 무엇을 사용하고 있습니까?
로렌 시걸 - 불행하게도 우리는 소스 코드 주석에서 정보를 컴파일하는 문서 도구를 지원하지 않지만 이것이 기술 문서를 저장하는 가장 좋은 방법이라는 데 동의합니다.내 질문은 시스템 관리자 유형부터 사용자 문서까지 모든 종류의 문서에 관한 것이었습니다.
해결책
이는 매우 개방적인 질문이며 여러 요인에 따라 달라집니다.
일반적으로 말해서, 좋은 문서 생성 도구(javadoc, doxygen, MS의 C# 등)가 있는 언어를 사용하는 경우 메서드 위에 문서를 작성하고 도구에서 페이지를 생성하도록 해야 합니다.장점은 그대로 유지된다는 점 원천 코드와 함께 텍스트를 편집합니다. 이는 논리적으로 올바른 위치에 구성되어 있으며 메소드 동작을 변경할 때 쉽게 편집할 수 있음을 의미합니다.
좋은 문서 도구 지원이 없거나 소스 코드에 접근할 수 없다면 위키가 나쁜 생각은 아니지만 위키에 대한 두 번째 선택입니다.
메모:여기서는 코드 문서에 대해서만 이야기하고 있습니다.다른 아티팩트는 코드와 함께 저장할 수 없습니다. 위키는 이러한 문서를 보관하기에 좋은 장소입니다.또는 일부 CMS를 사용하는 경우 일부 CMS에서 간단히 커밋할 수 있습니다. docs/ 저장소를 통해 편집할 수 있는 텍스트/pdf/모든 파일로 폴더를 지정합니다.장점은 이동하더라도 저장소에 남아 있는 반면 위키는 그렇지 않다는 것입니다(반드시).
다른 팁
도구는 중요하지만 마법 도구를 찾는데 너무 얽매이지 마세요.내가 찾은 도구에는 아직 "보이지 않는 작은 엘프를 사용하여 모든 것을 마술처럼 문서화" 확인란이 있습니다.:-)
위키는 잘 작동할 것이다.아니면 셰어포인트.아니면 구글 문서.또는 SVN 저장소를 사용할 수도 있습니다.정말로 해야 한다면 펜, 메모지, 파일 캐비닛을 사용하여 할 수 있습니다.(정말 추천하지 않습니다!)
가장 중요한 핵심은 조직 전체의 동의가 필요하다는 것입니다.많은 상점에서 일어나는 일은 Sharepoint와 같은 멋진 솔루션에 많은 시간과 돈을 소비하고 모든 사람들이 약 2주 동안 그것을 종교적으로 사용하고 사람들은 최신 이정표를 달성하느라 바쁘고 그것이 마지막입니다. 누구든지 그것에 대해 듣습니다.
조직, 분야, 개발 중인 제품 유형 등에 따라 몇 가지 해결 방법이 있지만 어떤 식으로든 시스템을 설정하고 사용 그것.누군가를 공식 문서 책임자로 임명하고, 힌트를 주고, 그들이 "아, 그래, 다음 주에 문서화를 끝낼게..."라고 말할 때마다 사람들의 머리를 때리라고 말하세요.그게 필요한 거라면.:-)
도구의 경우...나는 추천하고 싶다 합류 Atlassian으로.이것은 훌륭한 위키이고 기업 환경에서 작동하도록 설계되었으며 멋진 기능이 많이 있고 사용자 정의가 가능하며 Atlassian의 다른 멋진 도구 중 일부와 잘 통합되며 기본적으로 매우 견고한 제품입니다.
«소프트웨어 문서»는 매우 일반적인 용어입니다."최종 사용자 문서", "개발자 문서", "QA 문서"가 있습니다.첫 번째는 일반적으로 자격을 갖춘 기술 작가가 개발합니다.다른 것들은 위키, 소스 코드의 문서 주석 등으로부터 동적으로 형성될 수 있습니다.이 모든 유지 관리 프로세스는 일반적으로 매우 복잡하며 각 소프트웨어 회사는 자체 방식을 따릅니다.그러나 이 모든 방법에는 한 가지 필요한 사항이 있습니다.각 코드 커미터, 설계자, 관리자, QA 엔지니어는 다른 사람에게 도움이 될 수 있는 각 정보를 잘 정리하여 저장해야 합니다.그리고 다른 사람은 이 조각 보관을 감시하고 필요한 경우 조각을 재배열해야 합니다.이 모든 단계 매우 개발 프로세스와 관련된 모든 활동을 개선합니다.
코드 문서와 사용자 문서에 대해 이야기한다고 가정할 때, 코드에 대한 문서를 조직 외부, 계약자 또는 파트너에게 배포할 필요가 없다면 내부 위키가 유용합니다.
배포 가능한 코드 문서를 원하는 경우 Javadoc 또는 DOxygen이 더 적합합니다.
사용자 문서를 참조하는 경우 다음을 살펴보는 것이 좋습니다. 디타.
저는 다음과 같은 목표를 가지고 사용자 문서를 작성하는 방법을 실험하기 시작했습니다.
Markdown/Html/Javascript/파일 기반의 상대적으로 연결된 문서 휴대성을 위해 (로컬 파일 시스템에서 실행하거나 웹 서버에서 실행할 수 있습니다.), 내장된 스크린샷 처리(대화형으로 크기 조정), 그리고 다른 누군가가 미친 짓을 하고 싶어할 경우를 대비해 오픈 소스도 있습니다.
문서 소스는 Markdown으로 작성되고 브라우저 런타임 시 Javascript를 통해 Html로 렌더링됩니다.
현재 우리는 외부 애플리케이션(PHP + PhpDocumenter)과 다양한 내부 위키로 구문 분석된 인라인 문서를 사용하고 있습니다.때때로 그것은 기껏해야 고통스럽습니다(주로 한 사람만이 위키나 문서를 업데이트하기 때문에...)
그러나 나는 사용을 살펴 보았습니다. 이키위키 내부 문서를 작성합니다.소스 카운트롤 시스템(Git, Subversion, Mercurial, Bazaar, TLA 및 Monotone 포함)과 통합되어 모든 문서가 프로젝트와 함께 추적됩니다.Perl로 구축되었으며 광범위한 플러그인 시스템(여러 마크업 언어 포함, 기본값은 Markdown임)을 갖추고 있습니다.또한 소스 제어 시스템은 플러그인 기반이므로 사용하는 것이 즉시 지원되지 않는 경우 직접 추가할 수 있습니다.Perl이 아닌 플러그인도 지원하므로 필요한 경우 원하는 언어로 사용하세요.
우리 회사에서는 다양한 Sharepoint와 Wiki를 사용합니다.요구사항, 프리젠테이션, 계약서 등과 같은 특정 문서에 대한 공유포인트이고 Wiki는 내부적으로 개발된 라이브러리 사용에 대한 튜토리얼을 위한 개발자 저장소의 도움말 가이드로 사용됩니다.
예, 우리는 위키를 사용하고 Google 문서도 사용합니다.나는 Google 문서가 내가 시도한 대부분의 Wiki보다 낫다는 것을 알았으며 모든 변경 사항을 추적할 필요가 없다면 아무것도 잃지 않습니다.Google 문서는 훌륭한 협업 프레임워크를 제공합니다.
