チームはユーザーマニュアルを作成するためにどのツールを使用していますか？ [閉まっている]
https://stackoverflow.com/questions/314117
-
10-07-2019 - |
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
Russian質問
基本的なリクエストは次のとおりです。
- 人間が読める形式/テキスト形式（簡単なバージョン管理用）
- オンライン（コラボレーション用）
- 簡単な書式設定（マークダウンOK、htmlは多すぎます）
- 厳格な書式設定（作成者が新しいタイプのタイトルを発明しないように、 箇条書きなど）
- PDF、HTMLにエクスポート可能
- 簡単なバックアップと展開（したがって、お客様のサイトに「展開」することができます。 読み取り専用バージョン）
何らかのウィキエンジンを使用することを考えていますが、保存にファイルを使用するか、「展開」の他の手段が必要になります。顧客にインストールし、インストール/メンテナンスが簡単であること。また、無料である必要があります/安い（confluenceはあまりにも高価です）
提案はありますか
編集：コードを文書化するためのツールを探しているわけではありません。Sandcastleを使用してカバーしています。
解決
すべてのリクエストに答えるわけではありませんが、 DokuWiki は一見の価値があります。
他のウィキと同様に、シンプルな構文を持ち、リビジョンを追跡、を生成します目次、および全文検索機能。ヘルプシステムに便利です。 。
機能リストを評価して、ニーズに合うかどうかを確認できます。
>また、利用可能なプラグインのコレクションもあるようです。 DokuWikiまたはそのプラグインを使用したことはありませんが、 PDFエクスポート同様に。
他のヒント
APIには、 Doxygen を使用します。これは素晴らしいことです。
Pandoc は、さまざまなマークアップ形式を変換するための素晴らしいツールです。マークダウンでドキュメントを作成し、Pandocを使用して他の形式に変換します。
pandocサイトから：
ファイルを1つから変換する必要がある場合 別のマークアップ形式、pandocは スイス軍のナイフ。 Pandocはマークダウンを読み取り、 （のサブセット）reStructuredText、 テキスタイル、HTML、およびLaTeX。 プレーンテキスト、マークダウン、 reStructuredText、HTML、LaTeX、 ConTeXt、PDF、RTF、DocBook XML、 OpenDocument XML、ODT、GNU Texinfo、 MediaWikiマークアップ、テキスタイル、groff man ページ、Emacs org-mode、EPUB電子ブック、 S5およびSlidy HTMLスライドショー。 PDF 出力（LaTeX経由）もサポートされています 付属のmarkdown2pdfラッパーを使用 スクリプト。
Pandocは、オープンソースであり、Haskellであるホットな言語で記述されていることで追加ポイントを獲得します;）
マニュアルとヘルプファイルにはヘルプとマニュアルを使用します。 htmlエクスポートはありませんが、htmlヘルプ、winhelp、pdfおよびその他の形式を提供します。
ウィキを使用しています。 MoinMoin をお勧めします
- セットアップが非常に簡単（ラップトップでも）
- バックアップが非常に簡単です（Wikiをバージョン管理システムにコミットして、たとえばオフラインで使用するためにラップトップ間で同期させることもできます）。
- 素敵な構文
- 簡単に拡張
- 検索が簡単
Wordのようなものは使用していません。理由は次のとおりです。
- ドキュメントの腐敗が速すぎる
- すべてのドキュメントを検索するのは面倒です
- 情報ビット間のリンクは苦痛です
- バージョン間の違いはありません
- VCSから地獄を取り除くバイナリ形式
- 深いブックマークなし
- ドキュメントが大きくなりすぎて、不器用になります：分割（および検索が不要になります）するか、年齢が読み込まれるのを待ちます。
使用している言語/フレームワークについては言及しません。本当に優れたドキュメントツールがありますが、それらのいくつかは開発対象に固有のものです。私たちはC＃ショップであるため、.NETを使用している場合にのみ私の答えが当てはまります。
Sandcastle を使用します。これは無料であるだけでなく、オープンソースです。人々は主にXMLドキュメントからドキュメントを生成する厳密なアプリケーションと考えていますが、MAMLで独自のコンテンツを提供できます。 CHMとWebサイトの両方の展開を対象とすることができ、ニーズを満たします。お気に入りのマーク付けやトピックの評価などを理解できる追加ツールがいくつかありますが、まだ使用を開始していません。
これにより、内部ドキュメントと外部ドキュメントの両方が提供されます。 Team Foundation Serverも使用しているため、SharepointのTeam Projectに組み込まれているWikiを使用しますが、これはプロジェクトのコラボレーションに適しています。
編集：リンクの破損を修正し、Sandcastleと共に使用する他のツールがあることにも言及したかった。 Sandcastle Help File Builder や GhostDoc は一般的なツールです。 1つ目はSandcastleプロジェクトとMAMLを編集し、2つ目はコードのコメント品質を改善します。
Sphinx をお試しください。すべてのpythonドキュメントは、このツール http://docs.python.org/
を使用して作成されます。「マニュアル」については、Docbook。これは、技術文書用に設計されたSGML方言です。 http://www.docbook.org/ 「簡単なマークアップ」に適合しない場合があります。ただし、独自のCSSスタイルシートを作成すれば、LaTexで優れた出力（PDFに変換可能）と優れたHTML出力を確実に生成します。テキストファイルはバージョン管理に保存されます。すべてのプログラムは、コマンドライン引数の解析と＆quot;-help＆quot;を組み合わせたライブラリも使用します。さまざまな形式（通常、manページ、およびdocbook）で出力します。 APIリファレンスについては、もちろんdoxygenです。
現在の仕事では、使い捨てソフトウェアを大量生産しているので、ドキュメントはしばしばサイドラインに置かれ、Wordで行われます。
しかし、私の最後の仕事で、ドキュメンテーションチームはを絶えず怒らせ、絶賛していたようです。 mad cap softwareの製品＆quot; Flare＆quot; 。 1つの形式で記述し、多くのメディアに公開できるため、マニュアルはオンラインヘルプやWebサイトなどにもなります。
Wordを使用します。バージョン管理に入れられるため、履歴があります（すべてのプロジェクトにリンクされたドキュメントフォルダーがあります）。書式設定はテンプレートを使用して制御できます。テンプレートは現在すべて設定されているため、レイアウト標準内で変更を行うのは簡単です。ファイルはPDFにエクスポートできます。ユーザーと共有するための読み取り専用ドキュメントとして公開できます。
DocToHelp で大きな成功を収めました。 Microsoft Wordベースのドキュメントや他のフォームでもうまく機能し、Visual Studioの優れた統合機能も備えています。
最良の部分は、DocToHelpにインポートされたコアドキュメントベースを取得したら、WinHelp、HTML Help、Java Help、または検索可能な素敵なNet Helpなど、いくつかのエクスポート形式のいずれかを選択できることです。
コードを文書化するには、Doxygenを使用します。 Linuxバージョンの方が好きです。Windowsバージョンのいくつかの機能に問題がありました
私の会社では、ほとんどのドキュメントでMediaWikiとTikiWikiを使用しています。また、印刷/顧客への送信のために、MS WordおよびPDF形式にコンテンツをコンパイルする人もいます。ペストのようなTikiWikiを避けることをお勧めします。 MediaWikiは、非常に使いやすく、誰もが使用方法を知っているため、素晴らしいです。事実上の標準のWikiであり、当然のことながら、IMHOです。
しばらくはDocBookを使用していましたが、より高度で必要な機能（構文の強調表示、複数のファイルへの分割、多言語管理など）で拡張するのは非常に困難でした。その後、独自のシステムをゼロから記述し、オープンソースとしてリリースすることにしました：リンクテキスト。プレーンテキストファイルとMarkdownを構文言語として使用し、必要なものはすべて揃っています。欠点は、現時点ではおそらくHTML出力以外のものを生成するMarkdownパーサーがないことです。今のところこれで十分ですが、PDFサポートをすぐに実装することを考えています。
さらに、MediaWikiはコミュニティベースのヘルプとして維持されています。
