ユーザー マニュアルを書いている人は、必ずしもプログラマーである必要はなく、ビジュアル エディターが必要です。主な問題は、オーサリング ツールの内部形式です。読み取り可能な text/html である必要があるため、バージョン管理にチェックインされた個々のページのバージョンを簡単に比較できます。
11 に答える
DocBook
(ソース: docbook.org )
Microsoft HTML Help Workshop を使用すると、質の高い専門的な CHM ヘルプ ファイルを作成できます。必要なのは大量の HTML ファイルだけです。このツールは、これらすべてを「コンパイル」し、1 つのヘルプ ファイルにまとめます。HTML ファイルは、Microsoft Word/Frontpage または Dreamweaver を使用して生成できます。これらの HTML ファイルのソース管理を検討することをお勧めします。
私の以前の仕事では、 flareと呼ばれる madcap ソフトウェアによるツールが使用されていました。
それは本当にうまくいくように見えました。
検討すべき良い組み合わせは、Subversion、DocBook、Publicanです。
- バージョン管理= Subversion
- コンテンツオーサリング= DocBook
- 出版=収税吏
- オプションのWYSIWYG= Serna
現在、これはオープンソースソリューションの世界最大のプロバイダーによって使用されているツールチェーンの1つであり、エンタープライズ市場でのLinuxベースのオペレーティングシステムの世界的な使用の多くの背後にある名前です。Red Hatの公式ドキュメントのほとんど(およびほぼすべて)は、このような方法で作成されています。Fedoraについても同じことが言えます。
ここでの主な「長所」は、これらが無料で利用できるツールであり、テクニカルライターの市場で大きな重複があることです。これらはすべてXMLで書き込むことができます(ただし、書きたくない場合もあります)。DocBookを入手することは、90年代にHTMLを入手することと似ています。Subversionは非常に一般的なバージョン管理ツールであり、DocBookと同様に、実装と使用が比較的簡単です。Publicanは、DocBook XMLを取得して、PDF、HTML、HTML-singleなどに公開できる優れた公開ツールです。ライターはSernaのようなWYSIWYGを使用できますが、私はGeany(Fedoraの場合)またはTextMate( OS X)個人的に。
主な「欠点」は、専門性の認識です。あなたのライターはWYSIWYGを欲しがっているかもしれません(そしてそれを持つことができます)、そしてあなたのドキュメンテーションの必要性に応じて、これはあなたが最終的に使用するものかもしれません。ご存知のように、Microsoft Wordスタイル(およびマークアップ)の修正を専門とする「テクニカルライター」の市場が存在するため、「オーサリング」と「パブリッシング」を区別するための議論は、ドキュメントは、エンジニアリング/プログラミング/ソース制作と同じ基準に準拠している必要があります。
あなたが得る極端なアドバイスのいくつかは、XMLドキュメントの価値にさらされてきた人々や企業、特に特定の多国籍企業がフォーマットと製品知識の可用性。ドキュメントを「スティッキー」またはクローズドフォーマットにロックしても、将来のメンテナンス要件には役立たないという議論もあります。これは、オープンソースオプションが企業レベルでサポートを得る場所です。さらに、明らかに、それは無料です。
ヘルプ ファイルの書き込みを可能にする他の専門的な製品があり、それらはコンテキスト依存のヘルプを可能にする「コンテキスト ID」をサポートしています。Doc To HelpとRoboHelpは、これらのタイプの製品です。
Subversion と MGTEK Help Producer を使用できます。ヘルプ プロデューサーは、Word ドキュメントからヘルプ ファイルを作成します。TortoiseSVN には、Word 自体で Word 文書の異なるリビジョンを比較するためのスクリプトが付属しています (Word にはバージョン比較ツールがあります)。
あなたのユーザーは、編集中のものに似た視覚的な差分ツールを欲しがるでしょう。彼らが少し技術的でない場合、DocBook や Latex は機能しません (ユーザーに両方を提供しようとしましたが、 Epic Editor を DocBook エディターとして試してみましたが、これは非常に高価ですが、結局うまくいきませんでした)。彼らが知っていること (Word) に固執することで、多くの頭痛の種を防ぐことができます。
より「技術的に完璧」なソリューションが欲しかったので、私も最初はこの道を進むことに非常に消極的でしたが、時間が経つにつれて、幸せで生産的なユーザーを持つことがより重要であることに気付きました. 私はあなたがどこから来たのか知っていると言っているだけですが、Word ルートを試してみてください。実際には、そこにあるすべての「純粋な」テキストベースのソリューションよりもはるかにうまく機能します。通常のユーザーは、マークアップ ベースの編集を好みません。
Mapcap Flare は、最高の商用ツールです。ロボドックの元開発者によって書かれました
簡単にバージョン管理できるMandown ( Markdown/Html/Javascript/ファイルベースの比較的リンクされたドキュメント)というドキュメント システムを作成しました。ビジュアル エディターの部分については、個別に把握する必要があります。私は、少なくともプレビュー機能を備えたHTML-Kitを使用することがあります。
ソフトウェア ドキュメントを保存する最良の方法は何ですか? を参照してください。
チェックアウトする別のツールは次のとおりです。Xilize
Visual Studio を使用している場合は、SandCastle - http://www.codeplex.com/Sandcastleをご覧ください。
サンドキャッスル ファイルの作成に役立つツールもいくつかあります。codeplex で「サンドキャッスル」を検索してみてください。それらの 1 つに SandCastle Help File Builder ( http://www.codeplex.com/SHFB ) がありますが、私はこれを使用したことがないので、技術者以外のユーザーが満足するかどうかはわかりません。
APTを使用しています。CI (標準ビルド アーティファクト) とうまく統合され、たとえば Word 文書よりも有効です。必要に応じて PDF やその他の形式を生成することもできます。