ユーザーマニュアルを作成するための推奨プログラムを教えてください。マークアップ言語 (LaTeX や DocBook など) ではなく、Scribus のようなインタラクティブな言語です。マニュアルを更新するのは私だけではないので、ソフトウェアは初心者が簡単に習得できるものである必要がありますが、それでもいくつかの高度な機能 (外部ソース/テーブルからのテキストへのリンク、マスターページ/テーマの処理など) を備えている必要があります。 .
よろしく、オスカー
finnsson
質問する
7914 次
11 に答える
109
テクニカル パブリッシング ソフトウェア - FrameMakerとその代替案に関する見解
LaTeX と Framemaker を使用して仕様書を作成し、保険引受システムの仕様書を作成する 5 人のアナリストのチームをサポートする Framemaker ワークフローを設計しました。この文書は 2,000 ページ程度になると予想されていました。何年も前 (1992 年から 1993 年頃) に、私はタイプセッターとしても短期間働きました。
Framemaker は技術文書用に設計されており、実際に非常にうまく機能します。 また、複数の著者による非常に大きなドキュメントをサポートするように設計された機能も備えています。このシステムを使用して、100,000 ページを超えるドキュメントを処理しています。また、ワード プロセッシング ソフトウェアに慣れているユーザーにとっては、LaTeX よりもアクセスしやすくなっています。
フレームメーカーの主な機能:
複数のファイルで構成される文書:異なるファイルに複数のサブセクションがある「ブック」をまとめることができます。ドキュメントは、ソース管理に保持することもできます。
インポート/エクスポート用のテキスト MIF 形式:インポーターは多少面倒ですが (動作する LaTeX を生成する方が簡単であることがわかりました)、データ ディクショナリなどのアイテムを生成してドキュメントにインポートできます。ファイルにはテキスト アンカー (以下を参照) があるため、インポート間で安定した相互参照リンクを作成できます。これは、相互参照を生成されたアイテムに直接リンクできるため、仕様の重要な機能であることがわかりました。
強力なタグ付け、索引付け、および相互参照システム:すべてが Framemaker のタグに基づいており、タグをすばやく簡単に適用できます。これは、相互参照、索引付け、条件付きテキスト、スタイルの一括適用が簡単で、 うまく機能することを意味します。タグに基づいてインデックスと TOC を生成できるため、複数の特殊なインデックス (画面やデータ ディクショナリからのデータ フィールド名のリストなど) を簡単に作成できます。上で説明したドキュメントには、4 つの個別のインデックスがありました。
安定: Framemaker は専門家向けに設計されているため、その言葉のようにユーザーを推測することはありません。また、大きなドキュメントでもはるかに安定しています。Word で 50 ～ 100 ページを超える文書を作成しようとしたことがある人なら、これが何を意味するかについてかなり公平な考えを持っているはずです。
スクリプト可能: FM には C API があり、FM でジョブを自動化するために使用できるさまざまなスクリプト プラグイン ( FrameScriptとFMPython がおそらく最も広く使用されています) があります。 Framemaker 10は、 Extendscriptと呼ばれる Javascript ベースのスクリプト ツールのサポートを追加します。これは、おそらく InDesign のスクリプト機能から移植されたものです。
単一ソース:単一の FM ドキュメントから、PDF、Windows ヘルプ (CHM)、HTML、および印刷ドキュメントをかなり簡単に作成できます。相互参照もハイパーリンクに解決されます。
グローバル スタイル コントロール:ドキュメントのスタイルを簡単に設定して、ドキュメント全体に適用できます。また、ヘッダーとフッターの実行を容易にし、セクション、バージョン、章などを非常に柔軟に追跡できます。
フレームメーカーの代替品
LaTeX/Lout:マークアップ言語は必要ないとすでにおっしゃいましたが、TeXと Loutシステムは大規模な構造化ドキュメントに使用されており、これをうまく行っています。
Ventura Publisher:そのようなユーザー インターフェイスが必要な場合は、おそらく Framemaker に代わる唯一の代替手段です。構造化文書と XML ベースの文書交換フォーマットを強力にサポートしています。現在は Corel が所有しており、今でも積極的に宣伝しているようです。
市場には他にもテクニカル パブリッシング ツールがいくつかあります。Quicksilver (以前はInterleaf として知られていました) とArborTextです。これら 2 つは強力なツールです。Interleaf は、かつてこの分野のマーケット リーダーでした。ただし、非常に高価です。
Adobe Indesign: Adobeは、InDesign で大きなドキュメントを作成できると主張していますが、相互参照やその他の大きなドキュメント機能は、Framemaker の愛好家には欠けていると見なされる傾向があります。ただし、 InCopyと呼ばれるテキスト入力システムがあり、明らかにこの種の機能と、タグ付けやその他の機能をサポートするサードパーティ プラグインの非常に大きな本体を備えています。InDesign には、スクリプトを実行するためのスクリプト API と JavaScript インタープリターもあります。
私は Indesign を使用したことがないので、実際にどれだけうまく機能するかについてコメントすることはできません。
DocBook: これは実際には構造化ドキュメントの標準的な形式ですが、ドキュメントを作成およびレンダリングするためのツールの大規模なエコシステムがあります。LaTeX を使用したくない場合は、同様の理由で DocBook も使用したくないでしょう。Vinko Vrsalovic が (+1) を指摘しているように、このリンクは、実際に DocBook を使用していることを説明している誰かからの StackOverflow 投稿に移動します。私は DocBook を実際に使用したことがなく、この投稿に非常に多くの編集を加えたため、現在は Wiki モードになっているため、DocBook に詳しい人がこれについて詳しく説明したいと思うかもしれません。
ワード プロセッシング ソフトウェア: Word はテクニカル パブリッシング ツールとしては重大な欠点があるため、お勧めしません。 OpenOfficeは、Word よりも構造化されたドキュメント機能がいくぶん優れているため、.doc をドキュメント交換形式として使用するという政治的要件または要件により、より適切な代替手段が排除される場合には、OpenOffice の方が適している可能性があります。 また、 Wordperfectは大規模な文書化に関しても Word よりもかなり優れており、法律事務所などのいくつかの垂直市場で依然として存在感を示しています。
Madcap Software の BlazeとFlare :これらはブロックの新しい子供であり、Framemaker とほぼ同じスペースに住んでいます。同社は元 eHelp (RoboHelp の作成者) の従業員によって設立され、積極的に開発を行っており、毎年複数のリリースを行っています。彼らの製品は過去 2 年間で大幅に拡大し、個々の製品の品質が損なわれました。新製品を生み出すことに焦点が当てられているようで、その結果、それぞれに多くの「フィット感と仕上がり」の問題があります. 作成者は、多くの方法で車輪を再発明することを選択したため、実装が混乱し、しばしば壊れてしまいました。頻繁に保存すると、未処理の例外が発生します。ソース管理の統合は不安定です。たとえば、ファイルのグループを移動または削除すると、ファイルの削除ごとに 1 つのソース管理コミットが発生します。ソース管理の電子メール通知があると、大きな PITA が発生します。こんにちは、500通のメール。Flare は Word および Framemaker ファイルをインポートできますが、インポートはシームレスとはほど遠いものです。すべてのコンテンツを保持することを期待しますが、最初から完全にスタイルを変更することを計画してください。Flare は、Word の多くの傾向と同じように、舞台裏で多くのことを行い、ユーザーが何を選択するかを推測します。HTML は、HTML をエクスポートしたときに Word が出力するものと同じように見えます - 多数のカスタム タグと属性、深くネストされたインライン スタイルなど。
Framemaker 対 LaTeX
これら 2 つは、私が大規模で見栄えのするシステム ドキュメントを作成するために使用した主なシステムであり、両方で良い結果が得られました。
学習の容易さ: TeX は完全な制御を提供しますが、実際に複雑な LaTeX ドキュメントで他のアイテムを壊すことなくこれを達成することは簡単ではありません。特に、多数のマクロ パッケージが関係している場合はそうです。基本的な LaTeX を習得するのは難しくありませんが、TeX の深いハッカーではない場合、.sty ファイルの変更されたバージョンを作成してまだ機能するようにするには、少し手間がかかります。それは可能ですが、いじるのにかなりの時間を費やすことを覚悟してください。
Framemaker を使用すると、ドキュメントの外観を適切に制御でき、習得するのはそれほど難しくありません。家のスタイルを取得し、レイアウトを微調整する (おそらく行う必要がある) ことは、Framemaker を使用すると簡単になります。
テキスト入力の容易さ: Lyxなどのツールを使用して、ワープロのようなフロント エンドを LaTeX に提供できます。これは、大量のテキストを書きたい場合に適しています。Framemaker の DTP に似たユーザー インターフェイスは、ワード プロセッシング ソフトウェアに慣れている人にはなじみのある方法で機能します。この観点からは、実際的な違いはほとんどありません。
ドキュメント構造のテンプレート化:フレームメーカーでは、ドキュメント構造をタグまたは XML スキーマ (構造化フレームメーカーを使用している場合) で定義できます。LaTeX には、有用な柔軟性を備えた既定の構造要素のセットがあります。追加の構造要素 (データ ディクショナリ アイテムなど) の追加はマクロとして実行できますが、それらを自動番号付けするのは少し難しく、舞台裏をいじる必要があります。どちらでも実行できますが、些細な場合を除き、LaTeX で実行するのはかなり技術的です。
また、LaTeX には、Structured Framemaker のようにドキュメント構造をテンプレート化する機能がありません。ただし、このタイプの効果を DocBook で実現し、必要に応じて LaTeX に生成することができます。
統合の容易さ:非常に複雑な MIF ファイルのジェネレーターを作成するのは非常に面倒であることがわかりました。MIF パーサーは、FM では非常に厄介で、実際には適切な診断を提供しません。LaTeX ははるかに優れたエラー メッセージを生成し、かなり手間がかかりません。
テクニカル パブリッシング ソフトウェアとレイアウト ソフトウェアの比較
ページ レイアウト ソフトウェアはPagemakerで始まり、この分野の他の主なプレーヤーは競合他社のQuark Xpessであり、現在は InDesign であり、Adobe は本質的にそれと Framemaker を廃止し、置き換えようとしています。 先ほどおっしゃったScribusは、これらの製品と同じ空間に住んでいます。
(たとえば) 50 ～ 100 ページ未満のマニュアルを作成している場合、パッケージの 1 つがおそらく適切な仕事をするでしょう。それらは実際には、広告や雑誌などのレイアウトの多い出版作業向けに設計されているため、Framemaker に見られるような大きなドキュメント機能のサポートはかなり制限されています。これらの製品の主な問題はスケーラビリティです。大きなドキュメントではうまく機能しません。
参考までに、Pagemaker を使って実際に 200 ページの本 (誰かの自伝) を組版しました。きめの細かいカーニングと行送りのコントロールは、コピーフィッティングに少し役立ちますが、本サイズのドキュメントをレイアウトするのは依然として非常に手作業のプロセスです。この場合、本は章以外の重要な相互参照や構造を持たない単なるテキストでした。このサイズの複雑な技術仕様書やマニュアルを Pagemaker で作成するのは非常に面倒で、間違いなく正しく作成することはおそらく不可能に近いでしょう。
テクニカル パブリッシングとワープロ ソフトウェアの比較
これは、大規模な仕様文書に対する MS-Word の主な欠点の説明です。ただし、大規模なドキュメントに必要な主な機能のいくつかを示します。
索引付けと相互参照:これは Word では非常に厄介な作業であり、非常に不安定です。Framemaker のタグ付け機能と LaTeX のラベルにより、タグまたは既知のラベルを (必要に応じて予測可能な形式で) 割り当てることができます。タグ アンカーのテキスト形式はユーザー インターフェイスで公開され、リンクに使用されます。Word では、アンカーははるかに不透明であり、この方法で簡単に制御することはできません。不器用なユーザー インターフェイスと製品の不安定性が相まって、これらの保守は手間がかかり、多くの場合不安定になります。多くの場合、手動で修正する必要があります。
テンプレート化されたレイアウト: Word でのスタイル サポートは非常に基本的であり、番号付けはやや不安定になる傾向があります。FrameMaker は、タグから駆動し、タグに基づいてスタイルを適用することがすべてです。グローバル スタイルの変更は、Word では機能しない方法で Framemaker で機能します。
大きな複数ファイルのドキュメント: Word でこれをうまく機能させることはできませんでしたが、これは Framemaker と LaTeX の重要な機能です。繰り返しになりますが、Word は不安定なので、後片付けに多くの時間を費やす傾向があります。ドキュメントが大きくなるにつれて、この作業に費やされる時間の割合は二次的に増加します - n (ドキュメントのサイズ) に比例する破損の傾向 * サイズn (修正する時間) に比例する修正時間
Word が非常に不安定な理由: Word は、初心者ユーザーをサポートし、レイアウトに介入するために、舞台裏で多くのことを行っています。また、実際にはフレームベースではありません (ドキュメント レイアウトとは概念的に分離されたテキスト フロー) が、開発者は UI にさまざまなフレームのような動作を実装しようとしています。AI が複雑なドキュメントを推測するとき、多くの場合、間違ったことを行います。Framemaker は「ユーザーを大人として扱い」、これを行わないため、配置した場所にとどまります。
Open Office や WordPerfect などの他のワード プロセッサは、Word とまったく同じように誤動作することはありません。これが、Word 以外のほぼすべてのワード プロセッサが技術文書をより適切に処理できる理由の 1 つです。
Pre-Flighting:ドキュメントで言えば、これは、印刷をコミットする前に、ドキュメントのファイル (画像ファイルなど) の集合が正しいことを確認するプロセスです。プロのシステムは、間違っていることについて文句を言い、それを修正する機会を与えてくれます。Word はただうれしそうな顔をして、舞台裏で問題を解決しようとします。
これの良い例は、グラフィックがリンクされたワードファイルです。ファイルとグラフィックを別のディレクトリにコピーし、その場でグラフィックの1つを更新すると、Wordは更新したばかりの新しいパスではなく、古いパスからファイルを読み取る可能性があります（これを確認しました）。ただし、この動作には一貫性がなく、その製品で不安定なヒューリスティックが横行していることの典型です。
プリプレスサポート:パブリッシング システムは、ワークフローのプリプレス フェーズに拡張されます。これは、印刷の準備をカバーすることを意味します。ワード プロセッシング ソフトウェアには、この機能がないか、非常に限定された形式である傾向があります。
深入りしなくても、重要な違いは、パブリッシング ソフトウェアはユーザーを同意した大人のように扱う傾向があり、物事をスケーリングまたは自動化したいときに邪魔にならないことです。ワードプロセッシングソフトウェアを使用して大規模なドキュメントを作成することもできますが、品質をほとんど考慮せずに短いドキュメントを作成するカジュアルなユーザーに適した多くの設計上の決定があります。これらの適応は、大規模な文書作成作業の適性を犠牲にして行われます。Word の仕様書に関する主な問題は、索引付けと相互参照が不十分なことと、常に戻って修正しなければならない一般的な不安定性の問題です。ただし、ほとんどの環境 (私は請負業者です) での政治的な考慮事項により、多くの場合、それに行き詰まることになります。
テクニカル ドキュメンテーション ソフトウェアの状態に関する一般的なコメント
Adobe が Framemaker を非推奨にし、そのユーザー ベースを InDesign に移行しようとしているというシグナルを発し続けなければ、Framemaker は当然の選択となるでしょう。ただし、FM は航空宇宙、ソフトウェア、およびエンジニアリングの分野で広く使用されており、Adobe の経営陣は、信頼できる移行パスなしで実際に製品を EOL にした場合、リンチの群れに直面することになります。Web で読んだことによると、Adobe による FM の買収は John Warnock によって推進されましたが、彼は追放され、FM は社内政治の犠牲者になりました。最終的な結果として、メンテナンス モードに移行し、かなり停滞しています。
Ventura Publisher もある程度ニッチ市場に追いやられているが、少なくとも Corel には、Adobe のように競合する 2 つの製品ラインはない。これはおそらく FM のまずまずの代替品であり、「ビジネス出版」システムとして販売されているため、PHB タイプには政治的に受け入れられる可能性があります。
Quicksilver と Arbortext はどちらも実行可能な製品のようですが、非常に高価です。私はどちらも使ったことがないので、それらのメリットについて本当の判断を下すことはできません.
マークアップ言語システムは無料で、多くの点で非常に強力です。Lout は、LaTeX ほどのレベルのレガシー バゲージがないため、操作が少し簡単かもしれません。DocBook も非常に広く使用されており、かなりのツールがサポートされています。これらのテクノロジーは、Framemaker の市場シェアの「ギーク」エンドを大幅に圧迫し、そのメリットを利用しています。おそらく、長年にわたって Adobe の利益率をかなりの部分を奪ってきたでしょう。これらのテクノロジーを無意味に無視するつもりはありませんが、実際に習得するのは難しくなります。
InDesign と選択したプラグインのセットを評価してみてください (タグ付けと相互参照/インデックス管理用のプラグインに集中してください)。最後に、一部のワード プロセッシング ソフトウェア (Wordperfect および OpenOffice) は、構造化された文書を作成するための適切なツールキットを提供し、MS-Word よりもはるかにうまく機能します。
ポストスクリプト
はい、それは駄洒落です。これらの製品のプリプレス機能については触れていません。印刷とプリプレスはそれ自体が技術分野であり、費用のかかるミスが発生する可能性があるため、おそらく専門家に任せるべきです。Framemaker、InDesign、Ventura、QuickSilver、Arbortext、および (おそらく) MadCap 製品にはすべて、印刷前の準備を行うための機能が備わっています。概して、ワープロ ソフトウェアはそうではありません。
LaTeX でプリプレスを行うには、PS 出力をpsutilsなどのソフトウェアで後処理するか、PDF にレンダリングし、そこからプリプレス ワークフローを取得する必要があります。一般に、ほとんどのプリプレス ハウスは PDF から作業できるため、Distiller のような優れた PDF 書き込みツールは、プリプレス作業用に設計されていないツールから準備された作業に最適なインターフェイスです。Distillerからの出力の品質は、PDFCreatorなどのGhostscriptベースのものよりも優れている傾向があることに注意してください。
モニターの RGB カラー スペースには、印刷機で使用される CYMK カラー スペースへの直接マップがないことに注意してください。適切なキットを持っていない場合、印刷機で実際に色 (特にカラー写真) を正しく印刷するには、多少の困難が伴います。印刷物の制作については、自分が何をしているかを理解していると信じる理由がない限り、専門家に相談してください。カジュアルなユーザーには、私がこの業界に携わってから 15 年経った今でもこれをお勧めします。
どうしても社内でカラー印刷作業を行いたい場合は、おそらくモニターを調整する必要があります。最良の結果を得るには、HP からこのような忠実度の高いモニターを入手する必要があります。モニターを調整するには、モニターにセンサーが付属していない場合、このレビューで説明されているようなセンサーが必要になる場合があります。Nvidia、AMD、またはMatroxのようなほとんどのプロフェッショナル グラフィックス カードには、ガンマ補正をサポートする機能があります。多くの消費者も同様です。また、印刷に使用する印刷機のキャリブレーション データを取得する必要がありますが、プリプレス ハウスではおそらくこれを行うことができます。
前述のように、印刷メディアはそれ自体が非常に技術的であり、間違いが起こりやすく、印刷されなくなった後の修正には費用がかかります。キャリブレーションが正しいかどうか 100% 確信が持てない場合は、クロマリンなどのカラー プルーフを入手してください。これは実際のフィルムセパレーションから行われるため (したがって、非常に費用がかかります)、最終的な印刷物の実際の色を正確に表現できます。いくつかのサンプル ページに対してこれを行うと、キャリブレーションが正しく設定されているかどうかについて正確なフィードバックが得られます。
謝辞: Madcap 製品のセクションを拡張してくれたAidan Ryanに感謝します。
于 2008-12-16T17:22:38.850 に答える
5
EC Software の「 Help & Manual 」をお勧めします。1 つのソース ドキュメントから、印刷されたマニュアル、PDF、Windows ヘルプ ファイル (CHM)、および HTML Web ベースのヘルプを作成できます。
于 2008-12-16T17:38:07.413 に答える
4
FrameMakerについて良いことを聞いたことがあります。自分で使ったことはありませんが、そんな用途にオススメしてもらいました。
于 2008-12-16T15:44:52.947 に答える
2
Adobe Framemaker は確かに、ユーザー マニュアルを作成するための古典的なツールです。あらゆる種類の長いドキュメントに使用しましたが、非常にうまく機能します。残念なことに、Adobe は、ユーザーが切り替えないことに気付く前に、何年もの間、それを放置していました。
MSWord は 2003 年までに箇条書き/番号付けのバグを修正しましたが、最終的にマスター ドキュメントが機能するようになったかどうかはわかりません。
LaTeX は依然として妥当な代替手段です。この形式は処理が簡単で、wiki から生成できます。
于 2008-12-16T16:15:29.797 に答える
1
O'Reilly（実際にはこれらすべての本を販売しているもの...）が使用するものについての非常に素晴らしい説明：
複雑に見えるかもしれませんが、書くページの量によっては、それを考慮に入れる必要があるかもしれません。
于 2013-02-24T17:43:27.733 に答える
1
コラボレーションが必要な場合は、言語ベースのアプローチ（XMLベースのアプローチも適していますがLaTeXが私の好みです。ここではDocbookが主力です）は、特にバージョン管理システムでファイルを追跡している場合に意味があります。
バイナリ形式またはプロプライエタリ形式のソフトウェアのように複雑なことは、ここでは役に立ちません。
それがあなたが望む答えでないなら申し訳ありません。
于 2008-12-16T15:40:22.240 に答える
1
私は、DocBook（またはLaTEX）を使用することが、簡単な変換、適切なフォーマット、優れたバージョン管理を実現するための最も賢明なアプローチであるというOllivierに同意します。
幸いなことに、DocBookエディターを使用して、ケーキを手に入れて食べることもできます。
このリストにあるものを試して、ニーズを満たすものがあるかどうかを確認してください（私は使用していません）。
于 2008-12-16T15:43:58.533 に答える
1
EC Softwareの「Help & Manual」を使用していますが、非常にうまく機能しています。私たちの作成者は米国中に散らばっているため、ホストされた SVN サーバーを介してコンテンツ ファイルを共有し、バージョン管理を管理しています。各ワークステーションでは、Tortoise SVN を使用して同期を維持しています。この製品は非常に使いやすく、生産的です。
于 2009-03-09T20:40:29.760 に答える
0
Word（またはお気に入りのワードプロセッサ）
私はすべてのユーザーマニュアル（ユーザーヘルプファイルと混同しないでください）をWordで作成しています。次に、それらをPDF、RTF、DOC、またはHTMLに変換する必要があるかどうかを判断できます。マルチユーザー更新の問題を解決するために、これらすべての楽しいことを処理するソース管理にファイルを保存します。
于 2008-12-16T15:42:21.063 に答える
0
DocBookなどを使用することのトレードオフの詳細については、 Fastware Projectのブログを参照してください。ScottMeyerは多くの可能性を試し、彼の考えを共有しています。
于 2008-12-16T15:55:57.217 に答える
0
Adobe InDesign CS5.5 is much better at cross references and long documents than earlier versions. It is very powerful and relatively easy to learn and use. The feature set is very rich and the more you learn about it the more you can do with it. It supports very powerful XML features and can import and export XML as needed. It can also map Styles to Tags and Tags to styles allowing you to create your XML in an automated fashion if you simply use a full set of character and paragraph styles. I have used the program for years and produced multiple projects from books to one-off advertisements. It is a graphic design tool, but has support for many aspects of book and manual production. I recommend it if you are more concerned with graphics, images or illustrations. InDesign support a wide number of import and export formats.
InDesign CS5.5 has added and improved support for both interactive content and export for EPUB (electronic book) and Adobe's Digital Publishing Suite (DPS) electronic magazine formats.
Framemaker is an excellent tool for books, manuals and long technical documents. It is a bit harder to learn than InDesign but has a richer set of tools for building variables and running headers and footers, if you have the time and inclination to learn how to use them. It also has a very robust XML feature-set, but I have not used it personally.
Unfortunately, Framemaker suffers from lack of support for graphic design. The color system is based very kludgey and spot (PMS) colors are hard to define. Simple things like adding a stroke color and fill color are rudimentary at best. For example, you still can't select a stroke color that's different from an objects fill color. The program is intended to output to laser and inkjet printers and not really to printing presses.
One feature that is really cool is the ability to apply master pages based on the Paragraph styles appearing on the page. The paragraph/illustration numbering in Framemaker is superior to any other program that I have ever used. But it is also difficult to learn and use.
Both programs support output to PDF and PostScript file formats and can generate hyperlinks and interactive content.
于 2011-11-28T18:53:19.720 に答える