버전 제어와 통합되는 사용자 매뉴얼 (도움말 파일)을 작성하기에 좋은 도구는 무엇입니까 [폐쇄

StackOverflow https://stackoverflow.com/questions/152241

문제

사용자 설명서를 작성하는 사람들은 반드시 프로그래머 일 필요는 없으며 시각적 편집기가 필요합니다. 주요 문제는 저작 도구의 내부 형식입니다. 텍스트/html을 읽을 수 있어야하므로 버전 제어에 체크인 된 개별 페이지의 버전을 쉽게 비교할 수 있습니다.

도움이 되었습니까?

해결책

도움말 파일 작성을 허용하는 다른 전문 제품이 있으며 컨텍스트에 민감한 도움을 줄 수있는 "컨텍스트 ID"를 지원합니다. 도와 드는 문서 그리고 로보 헬프 이러한 유형의 제품입니다.

다른 팁

문서

alt text
(원천: docbook.org)

Microsoft HTML Help Workshop can be used to create good quality professional CHM help files. All you need is a bunch of HTML files. The tool "compiles" all these and bundles into a single Help file. The HTML files can be generated using Microsoft Word/Frontpage or even Dreamweaver. You might want to consider source controlling these HTML files.

Latex. Lyx provides WYSIWYM for writing latex files.

At my old job they used a tool by madcap software called flare.

It seemed to work really well.

A good combination to consider is Subversion, DocBook and Publican.

At the moment, this is one of the toolchains in use by the world's largest provider of open source solutions, and the name behind much of the world's use of Linux-based operation systems in the enterprise market. Most (and close to all) of Red Hat's official documentation is created in such a manner. Same goes for Fedora.

The major "pro" here is that these are freely available tools, with a strong overlap in the market of technical writers. All of which will be able to (but might not want to) write in XML, and picking up DocBook is like picking up HTML in the 90's. Subversion is a very common version control tool, that like DocBook is relatively easy to implement and use. Publican is a great publishing tool that can take DocBook XML, and publish it to PDF, HTML, HTML-single, etc. Obviously your writers can use a WYSIWYG like Serna, but I use snippets in Geany (on Fedora) or TextMate (on OS X) personally.

The major "con" is the perception of technicality. Your writers might want WYSIWYG (and can have it), and depending on your documentation needs, this might be what you end up using. As you would know, there's a market out there for "Technical Writers" who specialize in fixing Microsoft Word styles (and markup), so the arguments for separating "authoring" from "publishing" are based on proven but distinct use cases for organizations that require documentation to be held up to the same standards of the engineering/programming/source production.

Some of the extreme advice you will get comes from people and companies that have been exposed to the value of XML documentation, and especially those in the realms of DITA, where certain multi-nationals have a reputation for acquisitions that are influenced by the format and availability of the product knowledge. there are also the arguments that locking your documentation into a "sticky" or closed format doesn't help the future maintenance requirements. This is where the open source options gain support on a corporate level. Plus, obviously, it's free.

You can use Subversion and MGTEK Help Producer. Help Producer makes help files from Word documents. TortoiseSVN comes with scripts to compare different revisions of Word documents, in Word itself (Word has a version compare tool).

Your users are going to want a visual diff tool that resembles the one they are editing in. If they are just slightly not-technical, DocBook or Latex aren't going to work (I've tried giving my users both, and I even tried Epic Editor as a DocBook editor which is very expensive but didn't work out very well after all). Sticking to something they know (Word) will prevent you many headaches.

I was very reluctant to go this route at first too, because I wanted a solution that was more 'technically perfect', but I realized over time that having happy and productive users was more important. Just saying that I know where you're coming from, but try the Word route - it works much better in practice than all the 'pure' text-based solutions that are out there. Regular users don't like markup based editing.

If you're using Visual Studio, take a look at SandCastle - http://www.codeplex.com/Sandcastle.

There's also a couple of tools that help you build sandcastle files, try searching "sandcastle" on codeplex. One of them is SandCastle Help File Builder (http://www.codeplex.com/SHFB), but I've never used it so I don't know if non-technical users will be happy with that.

Mapcap Flare is the best commercial tool around. Written by the ex-developers of Robodoc

I created a documentation system called Mandown (Markdown/Html/Javascript/file-based relatively linked documents for portability) which would easily go under version control. The visual editor part you would have to figure out separately - I sometimes use HTML-Kit which at least has a preview feature.

See What is the best way to store software documentation?


Here's another tool to check out: Xilize

We are using APT. It integrates well with the CI (standard build artifact) and is more alive than for instance word document. It is also possible to generate PDFs and other formats when needed.

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top