:-) 🏕

ドキュメントの価値

August 14, 2017

TL;DR

  • 本当に必要なのはドキュメントなのか考えましょう

Living Documentation

リーダブルコード

自分の考え

  • ドキュメントを書くつもりでテストを書く
  • Doc Test 不要論

    • 動かせるのでメンテナンスはされている(Good)
    • ソースコードよりも長いテストを書くことは珍しくない
    • ソースの情報が増える、が情報の比重が高いとは限らない
    • それなら綺麗にテストを書く
  • ドキュメント生成

    • JSDoc, esdoc
    • FlowType, TypeScript の型定義ファイルなどの登場によりその役割は不要になりつつある気持ち
    • ソースコードの情報比率の高まりも重要
    • 可読性
    • 補完
  • 動いているものには価値が高い

    • storybook
    • style guide
  • 使い始めるための最短ルート

このエントリーの価値

読まれなければ意味がない。


Written by Keisuke Kan who lives and works in Japan building useful things. You should follow him on Twitter