기술 문서에 사용할 도구/프레임 워크는 무엇입니까?

Question

우리는 우리 조직에서 사용할 제품과 프레임 워크를 개발합니다. 나는 프로그래머에게 친숙한 문서 도구를 찾고있다. 언젠가 몇 가지 옵션을 연구했지만 어느 것을 사용할 지 결정할 수 없었습니다. 이 도구를 이미 사용한 사람들로부터 제안을 찾고 있습니다.

1. 의 DocBook : 스프링 프레임 워크 및 사용이 형식을 최대 절전이 좋아 보인다. 하지만 그들은 기본 xslt/stylesheet를 사용자 정의했다고 생각합니다. xslt 및 css (색상 및 이미지가 변경된 상태)를 복사하여 사용할 수 있습니까? maven을 사용하여 문서 생성을 통합 할 수 있습니까?

2. 위키 : 기술 문서 작성자에게는 친숙하지 않으며 문서가 전문적으로 보이지 않습니다. 버전 관리도 가능하지 않습니다. 믿을 수 없습니다.

3. 워드 문서 : 현재 사용하고 있지만 일반적인 문서를 링크하고 다시 사용하기가 어렵습니다.

4. DITA? 당신이 그들에 추가 제안하거나 피드백을 찾는 경우

Answer 1

의 DocBook

복사 스타일 : 예, 당신은 복사 스타일 시트를 적용 할 수 있습니다. DocBook을위한 XSL 스타일 시트는 매우 유연하지만 이해하기 쉽지 않습니다. 당신은 그들이 당신이 그것을 좋아하는 방식으로 일하도록 몇 일간해야합니다.

메이븐 통합 : 예, 빌드 프로세스에서 문서 생성 (예 : PDF, HTML 등)을 통합 할 수있는 메이븐 플러그인이 있습니다. SNAPSHOTS 만 워터 마킹하고 릴리즈시 archiva에 배포하는 등의 작업을하고 있습니다.

Answer 2

확실하지 당신은

Python

이 reStructuredText 및 Sphinx의 조합을 사용하여 ... /가 그것을 좁혀 나열 만하는 저는 직장에서 입양하기 시작했고 즐기는 도구 모음입니다.

내가 나열한 것들 중에서, 나는 전에 wiki를 사용했는데, 그 중 몇 가지를 만지면 많은 이유로 불쾌했습니다. Word는 가난한 선택 인 것 같습니다. 그 중 내가 도크 북을 선택 하겠지만, 그것에 대해서는 거의 알지 못합니다 ...

Answer 3

초기 램프 업 (스타일 시트 조정 포함)은 쉽지 않지만 DocBook에 상당히 만족합니다. 그러나 모든 것이 끝나면 사용하기가 정말 쉽습니다.

표준 XSLT 작업을 통해 Ant build.xml에서 내 docbook 생성을 실행합니다. 메이븐 (Maven)이 XSLT 프로세서를 호출 할 수 있다면 모든 것이 잘되어야한다.

유일한 단점 (내가 발견) 큰 책이

각 장에서는 불행히도 완료되지 않은 별도의 XML 파일입니다 (하나 개의 큰 XML 파일에 모든 것을 피하기 위해) 관리 할 필요가 어떻게 방법입니다

 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
[ 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
]> 

<?xml-stylesheet href="html.css" type="text/css"?> 

<article lang="en"> 
    <title>The Manual</title> 

    &chapter_1; 
    &chapter_2; 

</article> 

다음 chapter_1.xml는 다음과 같습니다 :

이

 
<section id="chapter_1"> 
.... 
</> 

내기가있을 수 있습니다 그것으로 DocBook으로 파일 시스템 엔티티를 통해 사용이 포함됩니다 거기 밖으로 해결책을 찾을 수 있지만 그들을 발견하지 못했습니다;)

Answer 4

같은 질문은 또한 우리의 프로젝트에서 발생했습니다. 이 시점까지는 일반 HTML 및 워드 문서를 사용했지만 이러한 솔루션은 만족스럽지 않았습니다.

이제 DITA를 사용하며 실제로 권장합니다. DocBook보다 가벼우 며 소프트웨어 설명서에 잘 적용됩니다.

일부 전문가 :

• DITA 콘텐츠의 분리 및 내용과 스타일의 분리는 HTML이나 PDF 등 다양한 포맷의 문서를 생성 할 수 있습니다
• 스타일링을 할 수 있습니다. 예를 들어 DITA를 사용하여 Eclipse RCP 기반 응용 프로그램의 EclipseHelp를 생성합니다.
• DITA는 소프트웨어 특정 네임 스페이스 (예를 들어 <input> 또는 <menu-item> 등)
• DITA 쉽게 사용자의 특정 요구에 적용 할 수있는 다양한 출력 포맷에 대한 빌드 스크립트와 함께 제공됩니다를 정의합니다.

도 DITA Open Toolkit Project Home

Answer 5

사용 위키를 참조하십시오.

귀하의 반대는 :

이 기술 문서 작성자에게 친절하지 않고 문서는 전문 보이지 않는다. 버전 관리도 가능하지 않습니다. 믿을 수 있습니다.

WYSIWYG 편집을 허용하는 위키가 있습니다. 하우스 내부 프로젝트에 대한 기술 문서는 "전문적으로 보이지"않아도됩니다. 글로벌 버전 관리는 문제이지만, 중요한 것은 아닙니다.

한편, 위키의 큰 장점은 특히 내부 제품의 경우 충분히 높게 평가할 수없는 이점입니다. 기여 및 협업이 쉽습니다. 제품의 모든 사용자가 문서에 기여할 수 있으며 문서에 공동 작업 문화를 구축 할 수 있다면 그 결과는 평균보다 "문자 그대로"10 배 더 유용 할 것입니다 "버튼 X는 A, 버튼 Y는 B"기술 실제로 제품을 사용하지 않는 작가가 만든 문서. 아무도 그것들을 필요로하지 않는다. 사람들은 "Howto"안내서, 용어집, FAQ 및 해결 방법을 필요로합니다.

위키는 이런 종류의 유용한 공동 작업을 가능하게하고 촉진합니다. 액세스 제한 및 승인 프로세스가있는 "프로페셔널"저작 도구는 그것을 제거합니다.

Answer 6

또한 결합 할 수 있습니다 접근 방법 :

• 사용 위키 저작은 단지 기술 작가로 참여 사람들이 더있을 수 있습니다. 예 : 개발자 또는 지원 직원이 쉽게 참여할 수 있습니다.
• 적어도 DocBook Wiki 나 회사의 Scroll Wiki Exporter (http : // k15t.)와 같이 Wiki를 DocBook으로 변환하는 도구가 있습니다.Confluence 위키에서 DocBook으로 내보내고 확장 된 사용자 정의를 위 해 DocBook 스타일 시트를 통합합니다 (위의 주석 참조). RenderX XEP. 이 도움이

희망,

-Stefan 여기