ドキュメント作成

→プロジェクト管理

→要件定義・基本設計

→詳細設計

→データベース設計 ←ER図についてはこちら

→アーキテクチャ←ADRについてはこちら

→PDF関連

サブトピック†

• テスト関連ドキュメント作成
• ドキュメント作成ツール
• メモやナレッジを管理するツール
• Markdown記法

文書作成・管理†

• LLMを味方につけた文章執筆術 - 執筆から校正までの実践的アプローチ 2024.12

• 技術ブログや登壇資料を秒で作るコツ伝授します - Speaker Deck 2024.9

• ハンコを押す技術 (Pythonで画像生成) #Python - Qiita 2024.7

• ドキュメントを書かないことは「負債を生む」ということ #エンジニア - Qiita 2024.6

• ドキュメント作成の手法について(図解作成) #ドキュメント作成,図解作成,見せ方 - Qiita 2024.2

• 技術文書の長音記号どうする？「コンピューター」と「コンピュータ」2022年現在と過去のルールについてのまとめ #English - Qiita 2024.1

• 設計ドキュメント腐る問題、Git管理で運用してみた結果 | フューチャー技術ブログ 2023.11

• データフロー図：情報の流れを視覚化し、ビジネスを理解する 2023.7

• エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita 2023.6

• サーバーサイド仕様書をGitHubで管理してよかったこと - dely Tech Blog 2023.5

• 「エンジニアのためのドキュメントライティング」Docs for Developers 翻訳者 岩瀬 義昌 | エンジニアの生き様をウォッチするメディア 2023.4
  • 【書籍】エンジニアのためのドキュメントライティング 2023.4

• 【NW構成図】は一周まわってエクセルで書けば良いのでは？という提案 / 開発者向けブログ・イベント | GMO Developers 2023.3

• 【書籍】ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング

• 読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜note 2022.12
  • 1. 書くまえに、ドキュメントの目的を明確に定義する
  • 2. 書くまえに、筋道が立っているかを強く意識する
  • 3. 書くときに、読み手視点を強く意識する
  • 4. 書いたあとに、自身で推敲する
  • 5. ドキュメントの冒頭に要点をまとめる
  • 6. 一文一義・一文50文字以内で書く
  • 7. 表や図を用いる

• ユーザーなのか、ユーザなのか 2022.9

• 技術文書の書き方 · GitHub 2022.9

• わかりやすいシステム構成図の書き方 - Qiita 2022.6

• データベースのテーブル定義の仕様書を自動生成しよう | CyberAgent Developers Blog 2022.5

• 最近、意味のない「にぎやかし図解」がやたらと多い気がする。 | Books&Apps 2022.4
• 開米のロジック図解入門・実践講座 – わかりやすく書く技術・説明する技術を追求しています 2021

• Excel方眼紙がダメな２つの理由 2012.7.13
  • まとめると、「Excel方眼紙」がダメな根源的な理由は２つある。プログラミングが合理化されない点、そして仕様情報管理が合理化されない点だ。これらに比べたら「Excelでは保守しづらい」とか「印刷するとずれる」など可憐なほどに瑣末である。
  • そういうわけで、この問題への対応状況には次の３段階がある。使っているツールがExcelだろうがWordだろうが、せめてレベル１を目指そう。レベル０の現場で人生を無駄使いしてはいけない。
    • ＜レベル０＞汎用ツールで仕様書を書いて、いちいちプログラミングしている
    • ＜レベル１＞汎用ツールで仕様書を書いて、プログラミングを合理化している
    • ＜レベル２＞専用ツールで仕様書を書いて、プログラミングと仕様情報管理とを合理化している

• 参考記事：美文書作りには「方眼紙」シートを使う 2013.5.23

• ネットワーク図の書き方 2012.4.4

• 情報の構造化、してますか？ 2012.2.8

• 報告書の書き方 2011.10

     目標は何だったか
     その目標は達成されたか
     達成されたのは何が原因か
     達成できなかったのは何が原因か
     問題があった場合、解決のために自分はどんな努力をしたか
     解決できなかった問題は、どうすれば解決できるか
     そのためには何をしてほしいか

• 仕様書の記述要領を決めるときに注意すべき一般的な項目
  • 大勢で仕様書を書くとき、平仄を合わせることが必要になり、以下のような規約をあらかじめ決めておく必要がある。決めて置かないと後から治すハメになる。
  • スペースの表現方法。△を使うか、クォートで囲うか。
  • 改ページしたときにヘッダを再度表示するか。表で改ページした場合も
  • 注のつけ方。章ごとに注の本体を書くのか、ページごとに書くのか
  • 章立て、項目立ての項番体系。単項目になったときに番号をつけるか（外すことが多い模様）
  • 既存の仕様書を修正で項番を削除するとき、詰めるのか、欠番にするのか。取り消し線を引くのか
  • ファイル名のつけ方のルール
  • 修正履歴の書き方。修正の理由も書くか。いつからバージョン1.0とするか
  • 図表の番号、キャプションのつけかた
  • Wordの場合、見出しにどんなスタイルをつけるか
  • テンプレート(.dot)を使うか
  • 英数字は全角か、半角か

• 読みやすい文章の極意は「修飾語」にあり 2010.1.19

• MSが長音付けルール変更、「ドライバ」を「ドライバー」に 2008.7.25
• 発注者が理解しやすいシナリオの記述方法 2008.7.17
  • システム化業務説明書とは，ある「システム化業務」の中で「利用者がシステムに対して行うこと」「システムが利用者に対して行うこと」「システムが内部的に実行する処理」を，「シナリオ形式」で記述した仕様書のことです。
  • 基本，代替，例外の3つのシナリオを記述すること
  • システム化業務のシナリオを利用者とシステムに分けて記述すること

• ユーザと意思疎通が取れない外部設計書は危ない 2008.5.22

• 議事録を書くときに意識すべきこと 2011.2.25

• 議事録のプロ 2008.4.8
  • 議事録には決まったことだけ書く

• どんな作業のマニュアルも３時間あれば作れる
  • 個人的には以下のようなマニュアル観は間違っていると思う。
    • 不完全なマニュアルを配られても困る
    • マニュアルに書いてある通りにやって問題が起きるぐらいなら、そんなの無いほうがいいんじゃないの
    • 書いてある通りにやって問題が起きても作業者の責任ではない。嘘のマニュアルを書いたやつが悪い
    • マニュアルとは「書いてある通りに作業するためのもの」なのだから、例外事項がたくさんある作業のマニュアルなんて書けない
    • マニュアルがあると、それに頼り切って頭を使わなくなるので、作業者が成長しなくなるのが問題だ
  • どこが間違っているかというと、こう考える組織では永遠にマニュアルができないから

• 計画書をコピペしてはいけない 2008.4.8
  • 「参考にする」ということと「コピペ」するということは違う
  • ここはコピーしても大丈夫だろうと思っても，必ず一度自分の頭で考え，判断した上でコピペすべきである

• 文章チェックを省略してはいけない 2008.4.7
  • 「○○だけで（も）動く」と「○○でだけ動く」の違い

• 仕様書の意義
  • 仕様書について人々が犯す最大の過ちは、公式のレビュー会議を開催するまで内容のフィードバックを得ようとしないことです。レビューは確認と洗練を行うための場であり、たたき台の検討と最終決定を同時に行うための場ではありません

関連サイト†

• はじめに | IT英語スタイルガイド 2023.3
• ドキュメント作成に役立つ「日本語スタイルガイド」の紹介
• ラプラス取説研究所

ツール†

→ドキュメント作成ツール ＜Draw.ioもこちら

Help File†

• Sandcastle Help File Builder
• HTMLHelp

最新の50件