2

Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.

I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:

  • My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
    • It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
    • As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
    • Search is of course a must-have
  • It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
  • The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
  • For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.

Are there any projects or languages that are suited to this sort of documentation?

4

6 に答える 6

1

他の多くの言語もサポートしていますが、CおよびC++プロジェクトでdoxygenを使用して良好な結果が得られました。単純または複雑なHTMLマークアップの可能性があるコードのコメントにドキュメントを配置します。コードの一部であるため、更新は非常に簡単です。ドキュメントのビルドをビルドプロセスの一部にすることができます。APIに厳密に関連していない追加のトピックは、個別のHTMLドキュメントとして追加できます。私が使用しているバージョンは検索をサポートしていないため、これらのページを検索するには別の製品を追加する必要があります。HTMLなので、コードサンプルや図などを追加できます。

于 2009-10-14T17:59:37.523 に答える
0

If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.

于 2009-10-14T17:53:42.737 に答える
0

ドキュメントリポジトリとしてconfluenceを使用します。パブリックセクションとプライベートセクションを作成するのはかなり簡単で、優れたWYSIWYGエディターがあります。添付ファイルを処理でき、必要に応じてPDFドキュメントとして保存できます。

于 2009-10-14T17:59:35.900 に答える
0

私はrobohelpを使用して良い結果を出しました。プレーンなhtmlですが、すべての一貫性を保つ生成プロセスがあります。アプリと一緒に.hlpファイルとしてパッケージ化するか、Webサイトに公開することができます。それをチェックしてください、それはあなたがあなたの仕事をすることに戻ることができるように簡単です:)

于 2009-10-14T18:06:46.190 に答える
0

クリーンな方法はDocBookを使用することです。書きやすく、理解しにくいです。XMLパーサーは標準であり、他の形式のドキュメント（たとえば、コメントに埋め込まれたドキュメントから）をこの形式に簡単に変換できるため、解析も簡単です。

DocBookソースからPDF、HTML、またはその他の形式を生成するのは簡単です（この目的のためのツールが存在します）。

于 2009-10-14T18:14:02.487 に答える
0

DokuWikiを使い始めました。それは私が最初に探していたものではありませんが（私は本当にCMSを探していたと思います）、それは仕事をし、私が最初に考えていたもの（特にウィキ-私はまだしていません）よりも優れていますしかし、これをお客様に公開することはできたので、それがどれほどうまくいくかはわかりません）

IndexMenuプラグインとArcticテンプレートを使用して左側のナビゲーションツリーを取得しています。Wiki自体を公開する場合は、ディスカッションプラグインを使用して、ユーザーがフィードバックを投稿できるようにします。

現在、生成されたコンテンツを処理する私の方法は、xsltテンプレートを使用してdokuwiki構文を生成し、その出力を「data/pages」フォルダー内のファイル/フォルダーに直接書き込むことです。

于 2009-10-20T15:47:27.270 に答える