Skip to content

Instantly share code, notes, and snippets.

@ymdysk

ymdysk/tech_article.adoc

Last active June 4, 2016 16:21
Show Gist options
  • Save ymdysk/a3cabafb4ef81813a234677f70231e86 to your computer and use it in GitHub Desktop.
Save ymdysk/a3cabafb4ef81813a234677f70231e86 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
tech_article.adoc

技術記事の書き方

自分の作業内容を記録しておき、他の人も使えるようにしておきたい。

記事にすることで、汎用的で客観的な記録の残し方を練習できる。

このため簡単でも良いのでWeb上に記録を残すようにする。

記述内容

  • 目的と、その手段を選んだ理由を書いている

  • バージョンを明記している

  • 参考情報へのポインタを記載している

記述の仕組み

  • 更新日時がわかる

  • 更新差分がわかる

具体的な方法

記述スタイルには AsciiDoc を使い、記述環境には CodingGround の AsciiDoc エディタを使ってみる。

記述した記事は GitHub の Gist に拡張子 .adoc で保存することとして、編集時は AsciiDoc の内容を CodingGround のエディタにコピペして編集/プレビューすることにする。

理由は下記の通り。

  1. 体系的かつできるだけ手軽に記述したい

    Markdown も手軽ではあるが、仕様が統一されていない。 AsciiDoc は書籍等の複雑な構造を執筆する事にも使われており、基本的な記述方法も大きく複雑ではなさそうだったためこちらを使う。

  2. コミットなしで、インタラクティブに出力を確認しつつ記述したい

    GitHub の Gist で拡張子 .adoc で保存すると AsciiDoc で表示できる。 ただし表示を確認するにはコミットが必要で、余計な試行錯誤の履歴が残ってしまう。 些細な変更はすぐに表示してみて調整する環境が必要だった。 CodingGround は、対応言語が非常に多いオンラインIDEで、 AsciiDoc も編集可能であるため使わせていただくことにする。

  3. 履歴は管理したいが、GitHub の Contribution にはカウントしたくない

    CodingGround は Github, Dropbox, Google Drive, OneDrive にプロジェクトを保存できる仕組みがある。Github に保存すると当然履歴も管理できる。 ただしこの機能を使うとファイルが Github のリポジトリに保存されるため、記事編集が Github の Contribution にカウントされて、芝が緑になってしまう。 執筆自体が成果物の場合はそれでも良いかもしれないが、私は今のところ記事を書くことを主目的としていないので、Contribution にカウントされないことが望ましい。 GitHub の Gist を使うと、編集履歴は残るが Contribution にはカウントされないため、保存先は Gist にすることにする。

なお本節の内容は後で更新することがある。

参考情報

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment