Toss、テクニカルライティングガイドを公開

良い技術文書を書くための核心原則

1. 文書の種類を決める

文書の目的によって、より効果的に書く方法は異なります。

• 学習中心の文書: 新しい技術やツールに初めて触れたとき、全体の流れを把握することが目的
• 問題解決文書: 背景知識がある状態で、特定の問題を解決することが目的
• リファレンス文書: すでに使い方は分かっているが、特定の機能やAPIの使い方を確認することが目的
• 説明文書: 概念、原理、背景知識を詳しく理解することが目的

2. 情報構造を作る

新しい知識を理解するには努力が必要ですが、情報を構造化すればその努力を減らせます。

• 1ページでは1つだけを扱う
• まず価値を提供する
• 効果的なタイトルを書く
• 概要を欠かさない
• 予測可能にする

3. 文章を磨く

文章の伝達力を高めれば、読者は内容をより理解しやすくなります。細部の内容が理解しにくい文章で表現されると、伝達力は大きく落ちます。

• 文の主体を明確にする
• 必要な情報だけを残す
• 具体的に書く
• 自然な韓国語表現を使う
• 一貫して書く

[tested]

トスが作ったこういうサイトをまとめた場所はありませんか？

[dontdieych]

「〜です・ます」調は慣れにくいですね。

[gera1d]

その通りです。

[winterjung]

いいですね。特に文章の推敲に関する内容は、few-shotでGPTsとして作って使ってみたいです。

[mathgig]

こういう文章は良いと思います。LLM時代には、このようなガイドラインはどのように変化し得るのでしょうか？

[bluejoyq]

とても良いプロジェクトですね ^^