マークアップ言語におけるドキュメント記述技法

ソフトウェアプロジェクトには良いドキュメンテーションが必要です.これは、ソフトウェアをより親しみやすく、ユーザーと貢献者に影響を与えます.さらに重要なことに、ソフトウェアの信号対雑音比を増加させ、ソフトウェアが必要に応じて開発者がよりよく理解できるようにする.これは革新的ではありません:今日開発されたハイレベルのソフトウェア(すなわちCプログラミング言語を使用している)は、サードパーティ製のコード、オープンソースを使用しています.しかし、ソフトウェアドキュメンテーションを書くことは、挑戦的で思慮深い仕事です.これは、技術企業が技術的な作家や開発者の支持者を雇う理由です:彼らは良いドキュメントは、その製品に重要です知っている.
MarkdownとASCIIのようなマークアップ言語は、ソフトウェアドキュメンテーションを開発する際に不可欠になりました.ツールチェーンと軽量構文を使用してプログラミングとの類似性は、従来のワープロよりも開発者の考え方と一致します.それらの中に書かれた文書には、読みにくい障壁がありますmore ) 読みやすいdiff sは、彼らの歴史を簡単にバージョン管理システムを使用して追跡すること.
ソフトウェアソースコードのように、マークアップ言語によって、著者は同じ内容を1000の異なる方法を書くことができます.このタイプの柔軟性と創造性をドキュメンテーションプロセスにおいて、それはコードを書くのと同じくらい楽しいドキュメンテーションを文書化して、ドキュメンテーション源ファイルを審美的に満足していて、一貫していて、効率的にスタイルのソースコードとして作るために技術を使うのを助けます.このポストは、私の執筆経験を改善した4つのそのような技術を共有します.
しかし、最初に、私の旅の技術的なドキュメントを書くの短い概要::)

個人的文脈

私が現在2012年に会社に加わったとき、マイクロソフトWordは主にオーサリングソフトウェアドキュメンテーションのために会社中で使われました.ソフトウェアライブラリAPIドキュメントには使用されませんでしたdoxygenやjavadocのようなツールが使用されました.Wordは、ユーザーと管理者ガイド、チュートリアル、よくある質問(FAQ)などを作成するためのものでした.単語を使用する主な理由は、顧客がWord文書としてドキュメントを期待し、顧客は、アプリケーションのユーザーではなく、開発者だった.
Subversionが会社の支配的なバージョン管理システムであったとき、これは戻りました、そして、ドキュメンテーション生成と変換のまわりでツーリングに投資するスラックは存在しませんでした.これらのいくつかの他の古い学校の考え方と組み合わせることは、ドキュメントを管理することが少し痛かったことを意味:ドキュメントの最新かつ安定版は一人で維持されました.人がドキュメントを修正することになっていたならば、人は最新のバージョンのコピーを得なければなりませんでした.User_Guide-km.docx ), 単語のトラック変更機能を有効にし、変更を行い、変更されたファイルをメンテナに送信します.管理者はすべての貢献者の編集を文書に合併する責任がありました.
ドキュメントは、編集が失われたことを確実にするために、レビューのためにすべての寄稿者に送られました.レビュー中にエラーが見つかった場合は、ワークフローの再帰はすべてのドキュメントが満たされるまでキックインされました.
これはちょっとしたガットだった.私はラテックスでレポートと論文を書いた大学院を終えた後、会社に加わりました.私はコードのようなドキュメントを扱うことに慣れていました:ソースファイルを出力形式に変換し、ドキュメント生成を自動化する(例えばGNU makeで)ツールキットを使用し、バージョン管理への変更をコミットします.私の脳は、最初に内容の最初とそのプレゼンテーションについて考えるために配線されました.*.cpp -> *.o -> {libmylib.a, libmylib.so} ).
会社がGitに移動した後、Markdownがスタッフとヒットしたとき、チームはマークアップ言語を使用してソフトウェアドキュメンテーションを書き始めました.貢献者は分岐して、GitでMarkdownファイルに編集を合併しました.Markdownファイルへの各変更は簡単に経由で見ることができるgit diff and git show . それは貢献者フレンドリーであり、世界は正しかった:P .最後のステップは、最終的なピアレビューコンテンツダウンワードワードに変換することでした.PanDocのようなツールはこれに役立つことがわかった.時間が経つにつれて、物事は良くなっていた:顧客は、PDFやHTMLにオープンになった、チームは、マルクダウンからアスキー医師に豊かなドキュメントを作成するために移動し、同社は、変更を検討してGitlabのインスタンスをホストした.
しかし、世界は白黒ではなく、ソフトウェア開発者にとって普通であるように、テクニックとスタイルは議論の話題になりました.単語についての良いことの一つは、それが心の同じフレームにすべての作家を置くということです.言葉の構造は一様で普遍的です.それは我々が幼い頃から書く方法を教えられている方法にマッチします:紙の空白の部分を抜き出し、左から右へ、上から下への書き込みを開始します.間違いをした?消去、ウェイトアウト、または開始を使用します.文や変数置換をコメントアウトすることはありません.あなたが書くものはあなたが得るものです、そして、語はこれに続きます.少なくとも私の知識は、単語のプレゼンテーションからコンテンツを分離することはできません:文章は期間と空間で区切られています.段落は改行で区切られます.順序および順序のないリストは、デフォルトのアイコンとスキームを使用します.振り返って、この厳格な語処理環境は、ナンシーが1つの文書に彼女の貢献を制限したが、別々の線の上で各々の文を書いた間、あなたがボブに別々のWord文書に彼のセクションを壊していないという感覚で貢献と合併プロセスを緩和しました.WordからMarkupへの移行はドキュメンテーション貢献を管理する際に「開発者カオス」を導入しました.このカオスは、コーディングのベストプラクティスとスタイルを経験しているミラー.
マークアップ言語の柔軟性をどのように管理するかについての前書きの後、私はいくつかのコアテクニックを見つけました.

文書の書き方

2015年に、私は見つけて、見ましたDan Allen 'Devnexusの上でsプレゼンテーションは、タイトルをつけました完全なプレゼンテーションは素晴らしいかどうかはASCIIの医師を使用しています.しかし、作者のための金は、彼のセクションです.
完全な開示:下記のテクニックは、ダンアレンの2015年のdevnexusプレゼンテーション(上記の関連を見ます)からあります.完全な信用は彼に行きます.私は、単に彼らを共有して、彼らがどれくらいものすごいかを証明しようとする試みで彼らを反響しています.
信用があるところに信用を与えた後に、彼のプレゼンテーションでダンが共有するテクニックのいくつかに飛び込みましょう.この投稿は「プログラマー毎に4つのライティングテクニック」のようなものであるかもしれませんが、それは私にClickbaitのように聞こえます.もう一度、私は一般的にタイトルを作成すると良いです.

1 .コードのように、自分自身を繰り返さないでください

マークアップ言語で技術文書を書くのは、コードを書くようなものです.アプリケーション全体のコピーと貼り付けのコードと同じように矛盾をもたらす可能性があります、あなたのドキュメントを通して同じテキストを複製すると、1つのセクションが変更されるときにそれらを断片化させることができます.
著者にドキュメントを他のドキュメントにインポートさせるツールがあります.これは、簡単に自分自身のドキュメントにライセンス、紹介、付録、画像などを引き出すことができますし、他にインポートします.これらのすべての変更は、他のすべてのドキュメントにファン.

2 .コードと同様に、1行あたりの文を書きます

コードのほとんどのステートメントには独自の行が与えられます.あなたのドキュメントにこの同じ原則を適用してください:あらゆる文か重要な条項(またはセミコロン、コロン、またはリスト)は新しい線を開始します.ほとんどのドキュメントフォーマットでは、段落を導入する空白行が必要です.したがって、行あたりの連続した文は1つのパラグラフとしてレンダリングされます.これは、いくつかの理由で強力な書き込み技法です.

それはあなたのプログラミングマインドをタップし、あなたが知っていると他の場所で使用する技術的な、構造化されたワークフローに合わせて.

変更が発生した場合は、その行に対してローカライズされます.

長い文章は、おそらく、ランニングや蛇行していることを意味80文字列を実行します.
技術文書は小説ではない.彼らは簡潔で要点を得なければならない.
もちろん、いくつかの文章は80文字以上になるだろうが、100文字を押している場合は、改正を検討する.
言い換えれば、賢明である.
(A thesaurus あなたがより少ないと言うのを助けることができます

文章を簡単に移動することができます.

文章を簡単にコメントアウトすることができます(ドキュメントの構文がコメントをサポートしている場合).

3 .コードのように、コメントを書く

コメントのコードで強力であり、ドキュメントと同じくらい強力です.ドキュメント内のコメントを使用すると、生成されたドキュメントにレンダリングされずにテキストの塊を保存できます.これは、段落、セクションなどのための思考や目的を維持するために重要です.これは、他の作家や編集者が達成しようとしているかを理解するのに役立ちます.
すべてのマークアップ形式がコメントをサポートしているわけではありません.あなたが使うものが彼らを支持するならば、彼らを使用するのを恐れないでください.

コードのように、変数を使う

多くのドキュメンテーションフォーマットは、ドキュメントを通して繰り返し使われる情報をカプセル化できる変数をサポートします.これは、単一の行に合わせて、自分自身を繰り返すことから保つために文章を短縮する方法です.私はASCII博士の属性を使用して、私が書いているアプリケーションの長い名前と省略名を保存します.

// attributes
:app-abbr: App
:app-name: Long Application Name Here
:app-uri-downloads: https://sourceforge.net/
:app-uri-downloads-link: {app-uri-downloads}[Downloads]

== Introduction

{app-name} ({app-abbr}) is an application that *blah blah blah*.

// ...

== Getting Started

Get started with {app-abbr} by downloading a pre-built binary from {app-uri-downloads-link}.

// ...

== FAQs

[quote]
Where can I download {app-abbr}?

Pre-built binaries can be downloaded from {app-uri-downloads-link}.

// ...

結論

このポストの目的は、マークアップ言語で楽しいソフトウェアドキュメントを楽しく書くためのテクニックを共有することでした.共有された4つのテクニックは、ASCII博士プロジェクトのダンアレンに信用されました.
フィン.