TOP > IT・テクノロジー > ドキュメント作成時のあるあるアンチパターン20 - Qiita

ドキュメント作成時のあるあるアンチパターン20 - Qiita

36コメント 登録日時:2016-09-30 10:40 | Qiitaキャッシュ

業務でドキュメントを作成するケースは多々ある例:仕様書・設計書・提案書・メール・障害票...ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。1. 表記がバイト表示・マイクロ秒表示プログラムが出した数値をありのままに表示するパターンファイルサイズが100MB, 1GBあろうと、バイト表示にする桁数が多い数値に、桁区切り(,)を入れない時間を何でもマイクロ秒・ミリ秒にする(1/100万秒までの...

Twitterのコメント(36)

ドキュメントの目的を考えて、内容を理解しやすいものにしていきたいですね

> ドキュメントを見る人は内容を理解したいのであって、以下のような作業はしたくない。
文章の校正(見直し係?)
作成者の意図の読解(国語のテスト?)
結論を探す、無いので考える(クイズ?)
これはドキュメントのみならず人に見られる文章全般に言えること
ドキュメント作成を行っていて参考にしてみた
ドキュメントだけじゃなくて普段のチャットコミュニケーションでも気をつけたい内容じゃった。
頭がいいから大体できてた。
たいへんわかりみがある。言葉じゃ分かりにくいときはその状況を録画してyoutubeとかに上げてそのリンクを貼っつけたりする(もちろん冗長にならないよう30秒以内をこころがけてるし、フォーカスも合わせてる)。
“図を使わない” “例を書かない” “対象者を考えていない”
良いまとめ。エンジニアは文章を書くことが多いので定期的に見返そう。
暗黙の了解で理解しろってドキュメント多いね。オイラも気をつける /
@Qiita
どれも「あー、そうだよなあ」と思う内容ばかりだった。こういう考え方はブログを書くときにも役立つと思う。
@Qiita
あっ、私の書くドキュメントだ…。/
これは良さある。
@Qiita
(。・ω・。)ノ
300ストック突破!
仕事の文書はわかりやすくてはダメなので、むしろベストプラクティスといえる。
(・3・)
@Qiita
とても参考になる /
こういうのってまとめられているものが少ないので、参考になります。
日ごろ気を付けてはいますが、
日本語はどうしても表記ゆれしやすいので常に心掛けてないとだめですね。
@Qiita
これは卒論書くときに注意しとこ
よいまとめ。コメントも良いです。 /
Win95周辺のロゴ変更後と変更前でしょ!!「例:Microsoft と MICROSOFT」 >>
「ましなパターン」っていう対比すき: @Qiita
エンジニアでなくても社会人や大学生なら必読、報告書・文書作成の答え合わせに。 /
コメント欄も含め、良いまとめ /
ちょいちょいう〜〜〜んってなるとこあるけど大半はわかる。 / @Qiita
「悪いパターン」に対して「ましなパターン」というのがwabi-sabiを感じる もっとよくしていこう💪 /
見てる:
どれも気を付けたいけど、特に「16. 対象者を考えていない」かな。 / @Qiita
@Qiita
ドキュメント、推敲するの結構めんどくさいからコンパイラ(Linter)欲しい
いつもレビューで指摘することばっかりだ。
いくつかやらかしてそうな気が…
すごく大事なこと。実用文書であればどんな文書にも目的があるし、読むのは他人の誰かです。「この文書を書く目的は何か?」「誰が読むのか?」は、書く前に想像しましょう。 / - Qii…”
「そもそもドキュメントを作る必要があるのか」っていうパターン(?)が抜けてる。ドキュメント書くこと自体が目的化してる奴とか、もうね...
@Qiita
以上

記事本文: ドキュメント作成時のあるあるアンチパターン20 - Qiita