ドキュメントライティング周りの雑記

作成日時：2023-12-06
更新日時：2023-12-06

記事と言うかメモ+ポエム。

最近の私のドキュメント作成方針

Markdownで記述する。
- 書きやすい。見やすい。
- htmlに変換出来るのでどこかに公開するときに便利。
- Hugoを使ってSSG的な事をしたい。
- Backlogの課題/WikiとかGitのReadmeとかもMarkdownだし慣れておきたいから。
VS Codeを使う。
- 下記の拡張機能を使用して、文章やMarkdownのフォーマットに問題が無いかをチェックする。
- Markdown All in One / markdownlintでMarkdownのフォーマットに問題が無いかを確認。
- vscode-textlint / テキスト校正くんで文章をチェック。(詳細は下記参照)
- Code Spell Checkerで英単語のスペルをチェックする。
- 完全に問題を検知は出来ないけども。
コーディングの概念をライティングにぶち込む(詳細は下記参照)
半角文字と全角文字の間にスペースを入れるか問題(詳細は下記参照)
STAR,BOSCAR,PREPなどのフレームワークを使用。(詳細は後で書く)

「コーディング規約がコードの可読性を上げるというならば、それをライティングに適用すれば見やすい文章が出来るんじゃね？」
と、最近思ったので実践している。

コーディングにおける原理・原則をそのままライティングに適用できそう。
ライティングの本を読むとだいたい似たようなことを書いているし。
以下は例。

昨日Googleで検索した。
昨日Googleで検索した。

どっちが見やすいかね。
textlintの設定ファイルを作る時、どっちを許可するか悩んだ。
私はこれまで前者だったが、いろいろ調査した結果、後者に統一した。理由は下記。
- 技術系のサイトを見たらだいたい空けていないから。
- 「空白の分、ファイルサイズ増えるよね」という意見を聞いたから。
- 「記事の文字数にその空白も含まれちゃって、正しい文字数が分からんよね」という意見を聞いたから。
- 「そういう見た目の部分はCSSとかブラウザとか表示する媒体が何とかするべきだよね」という意見を聞いたから。
[Solved] 日本語文章中、英単語の両端にスペースをつける人 #ポエム - Qiita