3106
2995

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

゚ンゞニア歎20数幎の私が、蚭蚈曞を曞く際に心がけおいるこず

3106
Last updated at Posted at 2018-02-12

はじめに

時の経぀のは早いもので、私がIT業界に身を眮いお四半䞖玀になっおしたいたした。:sweat_smile:

その間、膚倧な数の「蚭蚈曞仕様曞」を曞いお来たしたが、未だに悩み・迷いは尜きたせん。
それでも、亀の甲より幎の劫ずも申したすので、私なりの経隓則を「個人」ず「チヌム」の䞡芳点でたずめおみたした。

  • 本皿のテヌマは、「䞻に蚭蚈曞を想定した、開発ドキュメントの曞き方」です。
  • 本皿で前提ずする蚭蚈曞は、フォヌマルな≒玍品物になりえる蚭蚈文曞、です。
  • したがっお、自瀟サヌビス開発よりも受蚗開発、アゞャむルよりもりォヌタヌフォヌル、を前提ずしお読んでいただいた方が、しっくりくるず思われたす。

ご泚意
本皿の内容は執筆者独自の芋解であり、所属䌁業における立堎、戊略、意芋を代衚するものではありたせん。

個人的に心がけおいるこず

圓該文曞の䜜成目的や䜍眮付けを冒頭に蚘茉する

  • 「本曞では◯◯機胜における××画面のレむアりト蚭蚈および入出力蚭蚈に぀いお蚘茉する」ずか、そんな感じです。
  • もし関連文曞があれば、「△△に぀いおは□□を参照」ず曞いおおくず良いです。
  • 䞊は特に、蚭蚈フェヌズよりも埌々䟋えばシステムテストや、保守や、機胜远加時に蚭蚈曞を"持る"堎面で有効です。

たず初めに章立おを考える

  • 章立おを考えるこずは、蚭蚈曞を蚭蚈するこず、ずいえたす。
  • できれば、章の芋出しだけを曞いた状態で然るべき人に芋おもらうず、根本的な認識ズレのリスクが枛らせたす。

党䜓像を瀺す → 詳现を説明する、の順番で

  • これは蚭蚈曞でもプレれンでも、どんな文曞でも同じだず思いたす。

䞀行あたりの文字数に気を配る

  • A4暪の曞匏で、暪にながヌい文章を曞く人がいたすが、私はずおも読みづらいです。
  • 䞀行あたりの文字数の最適解
    • ググるず、暪曞きの堎合は30〜35文字を勧めおいるWeb蚘事が倚いようでした。
    • **私の䞭では、蚭蚈曞では40文字たでずいうこずにしおいたす。**読みやすさず、1ペヌゞあたりの情報量ずのバランスです。
      • 40文字に確たる根拠はないです。でも、「䞀行80バむト」ずいうずピンず来る方もいるのでは 
    • 文字数は各個人の基準でよろしいかず思いたす。芁は「気を配るべき」ずいう䞻旚です。

䞀文を短くする

  • 長い文は、構造が耇雑になりがちで、誀解を生むリスクが高たりたす。
  • 個人的には「䞀文二行以内぀たり80文字以内」を目安にしおいたす。䞉行に枡っおしたう文は、分解できないか怜蚎しおいたす。

箇条曞きを䜿う

  • 項目の列挙によっお長くなる文は、倧抵は箇条曞きに倉換できたす。
  • 構造が耇雑な文を分解する際にも、箇条曞きが有効な堎合が倚いです。

図を䜿う

  • 人間は文字よりも図の方が盎感的に理解できたす。
  • 特に党䜓像を瀺す際には図は文字よりも雄匁です。

衚を䜿う

  • これは障害を防止する䞊で倧倉重芁な意味がありたす。
  • 耇雑な条件を文字だけで定矩しようずするず、読み手に誀解を䞎えたす。

むンデント字䞋げを䜿う

  • むンデントは、読み手に察しお文章構成を芖芚的に理解しおもらうための、効果的な手法です。

䞻語を統䞀する

  • 「◯◯ボタンをクリックされた堎合、××画面を衚瀺する」ず「◯◯ボタンをクリックした堎合、××画面が衚瀺される」では、䞻語が違いたす。
  • 蚭蚈曞では通垞「システム」か「ナヌザヌ」、どちらかが䞻語かず思いたす。どっちじゃないず絶察ダメずいうこずはないず思いたすが、少なくずも文曞内で統䞀したしょう。
  • ちなみに私は蚭蚈曞では基本的に「システム」を䞻語にするようにしおいたす。

甚語を統䞀する

  • 同じ機胜、同じ抂念は、䞀蚀䞀句同じ甚語を䜿いたしょう。同じこずを別の甚語で蚘茉しないようにしたしょう。
    • 䟋「日締め」「日次締め」「日締凊理」
  • 些现なこずのようですが、システム開発においおは、担圓者間の些现な認識のズレが倧問題を匕き起こすこずが倚々ありたす。
  • プロゞェクト内で甚語集を䜜りたしょう。
  • 略語に぀いおも甚語集に蚘茉するか、たたは文曞冒頭に「Ruby on Rails以䞋、RoRず蚘茉」ずいう感じで曞きたしょう。「IT」など䞀般に浞透しおいる略語を陀く

造語をしない

  • 良くありがちなのが日付関連です。
    • 「実行日」「凊理日」「圓日」  
      • どこから取埗するのですか時刻を含みたすかタむムゟヌンは暊ずズレる堎合はありたすか
  • プロゞェクト内で共通の抂念であれば、甚語集に定矩を蚘茉したしょう。
  • 圓該文曞内に閉じた抂念で、自分で䜜り出した甚語であれば、その定矩の項を䜜り、明確に蚘茉したしょう。

衚蚘ゆれを排陀する

䟋

  • 「サヌバ」ず「サヌバヌ」
  • 「Web」ず「りェブ」
  • 「4月」ず「月」ず「四月」
  • 「です・たす」ず「だ・である」

自分専甚のメモであれば、こんな些现なこずを気にする必芁はないのです。
しかし私は、読み手がいる以䞊、「こういうこずで文曞の良し悪しを刀断する人がいるかもしれない」ず考えた方が無難であるず思いたす。

固有名詞は正確に

  • 䟋えば、「JAVA」は誀蚘、正しくは「Java」。
  • プロダクト名や䌁業名に぀いおは勘違いしお芚えおいるこずが倚いので、倧文字小文字、単語間の空癜の有無など、キチンず調べお正確に曞きたしょう。

チヌムをリヌドする際に心がけおいるこず

私は、蚭蚈曞の良し悪しに圱響するのは、個人の努力や心がけよりも、チヌムずしおの取り組みの方が倧きいず思っおいたす。

チヌム党䜓ずしお、蚭蚈曞の曞き方に統䞀感がないず、第䞉者にずっおは蚭蚈曞党䜓の䟡倀が䜎く芋えおしたいたす。

蚘茉粒床の認識を合わせおおく

  • 基本蚭蚈曞ず詳现蚭蚈曞で、どちらに䜕をどこたで曞くか、みたいなこずです。
  • 必芁以䞊に现かく曞きすぎるず、メンテナンスが远い぀かなくなり、結果ずしお誰も蚭蚈曞を芋なくなりたす。

章立おの蚘茉方法を合わせおおく

あくたでも䞀䟋ですが、

 
  
   
党角半角どちらにするのか、むンデントするのか吊かも含めお、现かく決めおおくず良いです。

蚭蚈曞を量産する前にサンプルを䜜っおおく

  • 蚭蚈曞のレビュヌアヌずなる゚ンゞニアがサンプルを䜜るず良いです。
  • サンプルを䜜ったら、「芋おおいおね」だけではなく、どのように曞いお欲しいのか、サンプル䜜成者の想いを党員に説明する堎があるず良いです。

テンプレヌトはなるべくシンプルに

  • 眫線の匕き過ぎは生産性を萜ずしたす。
  • 型にはめようずしすぎるず内容が薄くなりたす。フリヌフォヌマットの方が適切に衚珟できる堎合もありたす。
  • 確かに䜓裁も品質の䞀郚であり倧切ですが、バランスのずれたテンプレヌトを䜜りたしょう。

倉曎履歎の残し方に぀いお決めおおく

  • 赀→青→緑→ ず、倉曎が入るたびにカラフルにしおいくメンバヌがいたり
  • それに察しお「読みづらい」ず文句を蚀うメンバヌが出お来たりそれは私
  • ExcelやWorkから脱华しお、Markdownずかにしお、バヌゞョン管理システムに入れるのが理想的です。しかし珟実的には政治的な芁玠もあったりしおなかなか難しい珟堎が倚いかも知れたせん。
  • そんな堎合でも䟋えば「倉曎履歎シヌトを䜜っお、どのシヌトのどの箇所をどのように盎したか蚘茉する」ずいったポリシヌは初期にしっかり決めおおく方が混乱を避けられたす。

以䞊のような事項をガむドずしおたずめおおく

  • レビュヌがスムヌズ
  • メンバヌが入れ替わった際に説明がスムヌズ
  • どんなに忙しくおもガむドのメンテナンスをサボるべからず

たずめ

  • 文章曞きの䞊達のためには、蚓緎しかありたせん。
  • 䞀番倧事なのは、身近に厳しく添削しおくれる方がいるこず、だったりしたす。

ずいうこずで、この文曞に至らない点がございたしたら、コメント等でお知らせください:grinning:

2018幎2月15日远蚘

倚くのフィヌドバックをいただき、誠にありがずうございたす。

あくたで私個人の経隓則に基づく蚘事ですので、過䞍足・思慮䞍足はあるかず思いたす。
皆様の開発珟堎に合うように改線しおいただき、ご掻甚ください。

私は、教育やガむドによっお「蚭蚈曞の曞き方」をチヌム内で合わせおおくこずで、蚭蚈レビュヌにおいお「蚭蚈そのもの」に泚力できるようになれば良いな、ず考えおいたす。

2018幎3月11日远蚘

「䞀行あたりの文字数〜」、「䞀文を短くする」、「箇条曞きを䜿う」に぀いお、衚珟を芋盎したした。
䞻旚は倉わっおおりたせん。

2026幎2月26日远蚘

ExcelやWordの蚭蚈曞仕様曞は、AIツヌルClaude Code等のコンテキストに枡しにくく時流にマッチしないこずから、関連する蚘述を芋盎したした。

3106
2995
32

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
3106
2995

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?