バージョン管理と統合するユーザーマニュアル（ヘルプファイル）を作成するための優れたツールは何ですか

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

質問

ユーザーマニュアルを作成する人は必ずしもプログラマーではなく、ビジュアルエディターが必要です。主な問題は、オーサリングツールの内部形式です。読みやすいtext / htmlである必要があるため、バージョン管理にチェックインされた個々のページのバージョンを簡単に比較できます。

役に立ちましたか？

解決

ヘルプファイルの書き込みを許可する他のプロフェッショナル製品があり、「コンテキストID」のサポートがあります。これにより、状況依存ヘルプが可能になります。 ヘルプへのドキュメントおよび RoboHelp はこれらのタイプの製品です。

他のヒント

DocBook

代替テキスト
（ソース： docbook.org ）

Microsoft HTML Help Workshopを使用して、良質のプロフェッショナルなCHMヘルプファイルを作成できます。必要なのは、たくさんのHTMLファイルだけです。ツール「コンパイル」＆quot;これらすべてとバンドルを1つのヘルプファイルにまとめます。 HTMLファイルは、Microsoft Word / FrontpageまたはDreamweaverを使用して生成できます。これらのHTMLファイルを制御するソースを検討することをお勧めします。

ラテックス。 Lyx は、ラテックスファイルを書き込むためのWYSIWYMを提供します。

以前の仕事では、 flare というmadcapソフトウェアのツールを使用していました。

本当にうまくいったようです。

検討すべき適切な組み合わせは、Subversion、DocBook、およびPublicanです。

現時点では、これはオープンソースソリューションの世界最大のプロバイダーが使用しているツールチェーンの1つであり、エンタープライズ市場でのLinuxベースのオペレーティングシステムの使用の多くの背後にある名前です。 Red Hatの公式ドキュメントのほとんど（およびほぼすべて）は、このような方法で作成されています。 Fedoraについても同様です。

主要な「プロ」ここでは、これらは自由に利用できるツールであり、テクニカルライターの市場で強い重複があります。これらはすべてXMLで記述できます（ただし、そうではない場合があります）。DocBookを取り上げるのは、90年代にHTMLを取り上げるようなものです。 Subversionは非常に一般的なバージョン管理ツールであり、DocBookのように実装と使用が比較的簡単です。 Publicanは、DocBook XMLを取得してPDF、HTML、HTMLシングルなどに公開できる優れたパブリッシングツールです。明らかに、ライターはSernaのようなWYSIWYGを使用できますが、Geany（Fedora）またはTextMate（on OS X）個人的に。

主要な＆quot; con＆quot;専門性の認識です。ライターはWYSIWYGを必要とする場合があります（また、それを使用することもできます）。ドキュメントのニーズによっては、これが最終的に使用するものになる場合があります。ご存知のように、「テクニカルライター」には市場があります。 Microsoft Wordスタイル（およびマークアップ）の修正を専門としているため、「オーサリング」を分離するための引数は、 「公開」からエンジニアリング/プログラミング/ソース制作と同じ標準にドキュメントを保持する必要がある組織向けの、実証済みの明確なユースケースに基づいています。

いくつかの極端なアドバイスは、XMLドキュメントの価値にさらされている人々や企業、特にDITAの分野の人々から得られます。DITAの分野では、特定の多国籍企業が、製品ナレッジの形式と可用性。ドキュメントを＆stick; sticky＆quot;にロックする引数もあります。または閉じた形式は、将来のメンテナンス要件に役立ちません。これは、オープンソースオプションが企業レベルでサポートを得る場所です。さらに、明らかに、それは無料です。

SubversionおよびMGTEK Help Producerを使用できます。ヘルププロデューサーは、Word文書からヘルプファイルを作成します。 TortoiseSVNには、WordのさまざまなリビジョンのWordドキュメントを比較するためのスクリプトが付属しています（Wordにはバージョン比較ツールがあります）。

ユーザーは、編集中のツールに似た視覚的な差分ツールが必要になります。技術的に少しだけであれば、DocBookまたはLatexは機能しません（ユーザーに両方を提供しようとしましたが、そして、私はEpic EditorをDocBookエディターとして試してみました。これは非常に高価ですが、結局はうまく機能しませんでした）。彼らが知っている何か（Word）に固執することで、多くの頭痛を防ぐことができます。

私は、最初はこの方法を採用することに非常に抵抗がありました。なぜなら、「技術的に完璧な」ソリューションが必要だったからです。私はあなたがどこから来たのか知っていると言って、Wordのルートを試してください-それは実際にそこにあるすべての「純粋な」テキストベースのソリューションよりもはるかに優れています。通常のユーザーは、マークアップベースの編集を好みません。

Visual Studioを使用している場合は、SandCastleをご覧ください- http://www.codeplex.com /サンドキャッスル。

サンドキャッスルファイルの作成に役立つツールもいくつかあります。「サンドキャッスル」を検索してみてください。コードプレックス上。それらの1つはSandCastle Help File Builder（ http://www.codeplex.com/SHFB ）です。使用したことがないので、技術に詳しくないユーザーがそれで満足するかどうかはわかりません。

Madcap Flareは、最高の商用ツールです。ロボドックの元開発者によって書かれた

Mandown （ Markdown / Html / Javascript / file-basedという名前のドキュメントシステムを作成しました。移植性のために比較的リンクされたドキュメント）を簡単にバージョン管理できます。個別に把握する必要があるビジュアルエディターの部分- HTML-Kitを時々使用します少なくともプレビュー機能があります。

ソフトウェアを保存する最良の方法を参照してくださいドキュメント？

チェックアウトする別のツール： Xilize

APT を使用しています。 CI（標準ビルドアーティファクト）とうまく統合され、たとえばワードドキュメントよりも生き生きしています。必要に応じてPDFやその他の形式を生成することもできます。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top