2021-01-28

仕事があまりうまく行かなかったのでテンション下がり気味。そんなこと言ってても問題は解決しないので、一つ一つ倒していこう！

いいウェブログがあったので、それについての感想をもって、今日の日記としよう。

今日のウェブログ

質の高い技術文書を書く方法 - As a Futurist…

riywoさんのめっちゃいい文章が公開されていた。

「文章から得られるアウトプットをまず定める」や「結論を最初に書く」というのはなるべく意識していて、最近会社で書いている短めのドキュメントは、ページタイトルで誰が何に困っているときに読む文章なのかがわかるように気をつけいているつもり。(例えば「サービスAが閲覧できない障害に対応する」といった感じ)

「箇条書きを乱用しない」というのは本当にそう。私は、箇条書きを乱用しまくるくせがあることを自覚しているので、まとまった文章を書くときは意識的に箇条書きを避けるようにしている。<ul>と<ol>の意味で表現するのが正しいと思ったときにだけ箇条書きを使うように心がけている。

一方で、ドキュメントがないよりは箇条書きであってもあったほうがいいとも思っている。この点、scrapboxは箇条書きを一級市民として扱うことで、ドキュメントを書くための心理的障壁やクオリティの底上げ(変な構造になっているよりは箇条書きのほうが構造がわかりやすい)ができるんだろうなと考えている。( 箇条書き - 橋本商会 )

最後に、この記事で重要だと言っている以下の一文の後半は、自分はあまり意識できてないところだったので、これからは(自己)レビューのときに意識しようと思う。

文書から得られるアウトプットが明確で、読み手のレベルによらず一定に伝わること

今日の読書

今日はお休み

今日の英語

今日はお休み