背景#
最近、技術ドキュメントをどのように改善できるかについて考えています。
最近、私が考え始めたきっかけは 2 つあります：
- ViteConf で Sarah Rainsberger が共有した「ドキュメントの作成をやめて、ヘルプを始める」というビデオを見たこと
- 最近の sync-to-xlog プラグインのドキュメント PR
それぞれについて説明します。
ドキュメントは人々を助けるために存在します#
Sarah Rainsberger は Astro のドキュメントマネージャーであり、これは彼女が ViteConf2023 で行ったプレゼンテーションです。私はそのビデオを転載しましたので、Bilibili で視聴することができます # Astro 文档负责人分享什么是好的技术文档，如何改进
内部リンク： [[stop writing docs start helping]]
彼女は非常にクラシックな例を挙げています：
ソース元 リンク
上の図は、インストール手順を紹介しています。この例は心に響くものであり、元の技術ドキュメントは非常に優れており、読者を刺激し、著者の考えを説明しています。改善後は、わずかな言葉や数語で済みます。
この時点で、読者が必要としているのは、インストール方法を教えることです。読者に明確かつ明確に伝えるだけで十分です。
ドキュメントの PR#
私の考え：
- 大胆に H1 を使用する
- インストール方法を前提条件で区別する。このスクリーンショットに注釈を追加し、赤で強調し、矢印を付けることは問題ありません
- 冗長な言葉を減らし、中立的で忠実で穏やかに事実を説明する
- もっと読んで書く必要があります
ドキュメントはゼロから始めることも、既存のものを改善することもできます。
今後、ドキュメントを作成する際には、より良いものにするために注意を払います。
言及されているドキュメントの統一理論は非常に良いと思いますので、翻訳することができるかもしれません。