テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter:https://twitter.com/naoh_nak 2023年度のアップデート版もあります:https://spe…
はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと(テクニカルライティングとも言います)は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a write
いまこそ「良い仕様書」がチームの生産性の鍵となる。ので、仕様書に含めたい 14 のポイントについてまとめました。 こんにちは、フリッツ です。今回はプロダクトマネージャーの日課とも言える「仕様書」について。自分にとっては PM 業の施策実行フェーズにおいて最も重要な仕事のひとつであり、最も心躍り、最も興奮する瞬間です。 PM になってかなりの時間が経ちましたが、「仕様書」への力の入れようは減るどころか、「もっと気合を入れなければ。」と感じる一方。在宅勤務が(たぶん) IT 業界のニュースタンダードとなっていくいま、なおさら「仕様書」の重要性を訴えたい今日この頃です。 ということで、今回は ・ 良い仕様書がもたらす 5 つの効果 ・ 仕様書の重要性が増していく 2 つの理由 ・ 仕様書に含めたい 14 の項目・実戦編 ・ 仕様書作成時に心に留めたい 3 つのこと ・ 具体的な仕様書サンプル(
Googleでの「Design Docs」とは 2007年の Google Developer Day Tokyo での鵜飼氏のプレゼンによると「Google で必ず書くことになっているドキュメント」であり、「プロジェクト立ち上げ時の 1~2週間をかけて書く」ものです。 今回は Google のソフトウェアエンジニアである @cramforce 氏が自身のブログで「Googleでの Design Docs」について解説している記事を公開されていたため、氏の許可を得て翻訳しています。 原文: www.industrialempathy.com 関連書籍: Googleのソフトウェアエンジニアリング ―持続可能なプログラミングを支える技術、文化、プロセス オライリージャパンAmazon 読了目安:11分 (目次) デザインドキュメント の解剖学 文脈と範囲 目標と非目標 実際のデザイン システ
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました! ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー! 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
更新日: 2020年8月14日 このページの目的 プログラマーは、クライアントから提供されたPDFファイルで、その要求を実現させようとしたとき、PDFのどんなところを見ているのでしょうか。このページでは、ちょっと珍しい視点でPDFファイルを解き明かしていきます。 自分でプログラムを書いてPDFファイルからテキストデータを取り出したいという人も、ぜひご一読ください。 はじめに PDFファイルをクリックすると、あたかも紙に印刷したかのように、どんなマシンでも同じような見た目で文章や画像がディスプレイに表示されます。 この単純な事実は、日常的にPDFファイルを利用していると当たり前に感じられるかもしれません。しかし、よくよく考えると驚くべきことです。 いったい、どのような仕組みがあれば、「過去から現在に至るさまざまな種類のコンピューターで見た目を変えずに同一の紙面を再現する」という目的を達成でき
howto-tech-docs.md 技術文書の書き方 このメモは、私(@ymmt2005)が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
あれっくす@フロントエンド x デジタルマーケティング @MHTcode_Alex 仕事で作業クオリティが低いってコメント来たので話聞いてみると不思議な世界が広がっていた 相手「仕様に書いてないが、普通のエンジニアならできるでしょ」 私「仕様に書いてないならやれません。仕様確認会などあったのでしょうか?」 相手「そんなものない。わからなかったら確認するでしょ」 続 あれっくす@フロントエンド x デジタルマーケティング @MHTcode_Alex 私「わからないところは都度確認してますが、仕様に記載されていないものを作ることはできませんし、確認すらやりようがありません」 相手「テストでいっぱい不具合出てくる」 私「クオリティコントロールの仕組みがないから当たり前では?」 相手「こっちが確認してないのが悪いってこと?」 続 あれっくす@フロントエンド x デジタルマーケティング @MHTco
どうも、レコメンド商品のシステム開発をしている野川と申します。 私は、2021年にモノタロウに新卒入社し、2022年5月からレコメンド商品の開発に関わり始めました。 モノタロウのレコメンド商品は、下の図の①~④の流れでクライアントサイドで表示しています。大部分の処理はJavaScriptで構成しており、UIもそのHTML部分をjQuery(JavaScript)で作成しています。 図:レコメンド商品表の流れ 入社当時私は、ソフトウェアエンジニアとして、「可読性の低いコードは駆逐するべきだ」「読みやすいコードだけが正義である」「理解しやすいシステムだけが皆を幸せにする」と心の底から考えていました。加えて、「なぜ先輩たちは可読性の低いコードを放置して平気なのか?」と疑問を持つこともしばしばありました。 レコメンド商品周りのコードはまさに可読性の低いコードベースとなっていたため、当事者となった私
概要 Design Documentと聞くと何を想像しますか? 一般的にDesign Documentが指すのは設計書であることが多いのではないでしょうか。 設計書、簡単に説明するのであればソフトウェアを「どうやって作るの?」を説明したドキュメントです。 Googleではソフトウェアエンジニアリング文化における重要な要素として、今回お話ししていくDesign Docsと呼ばれるものがあります。 Design Docsとは? Design Docsとは、開発者がコーディングに着手する前にソフトウェアシステムまたはアプリケーションの開発する人が作成するドキュメントです。 => ソフトウェア設計における仕様書や設計書とは別物と捉えた方がよいです。 仕様書、設計書は作成した上でのDesign Docsの作成となるようです。 このドキュメントには、高レベルの実装戦略と主な設計の決定事項がまとめられて
AWS テクニカルサポートを 5 年経験して アノテーションの荒川です。 クラスメソッドメンバーズをご契約いただいているお客様のテクニカルサポート業務を始めて、早 5 年が経過しました。 私が対応したチケット件数をざっくりと調べたところ、本日時点で 1685 件でした。 最近は私がチケット対応する機会は減りまして、チケット対応メンバーの教育(新入社員から各チームへ所属するまでの育成)やチケット相談に使う時間がメインです。 その中で、今まで何となくこうやって対応すると上手くいくと感じていた暗黙知をメモ書きしていたので、今回ブログとして公開します。 回答者側で意識したいこと 技術的なお問い合わせに関するガイドラインを参考にする AWS サポートのガイドラインは、一般的なカスタマーサポートでも使えます。 一文を短くし、適宜改行を挿入する 例: 一行にぎっしり × お客様環境をお調べしたところ、E
オープンソースやテクノロジーを中心としたコミュニティの維持や発展を支援する組織「Open Collective」は、Web技術のドキュメント化を長期的に支援する取り組みとして「Open Web Docs」を発表しました。 Open Web Docsはおもに既存のコミュニティによるドキュメント、特にMozillaのMDNをまずは優先的に支援するとしています。 We’re happy and proud to announce Open Web Docs, to support a community of technical writers around creation and long-term maintenance of web platform technology documentation that is open and inclusive for all.https://t
日本のプログラマでマスを占めてるのは、大規模SIのコーダーじゃん? そんで、そこでのお仕事はExcel方眼紙に書かれた設計書を、ひたすらプログラム言語に翻訳するだけという。 だから翻訳するために最低限の言語仕様だけ知っていれば良くて、あとはまあ上手に立ち回るコミュ力があれば上出来とされるけど、あくまでオプション扱い。 仕事そのものには数学的素養どころか、理系的センスすら全く不要。 つまり、SIにおけるプログラミングは工学でも自然科学でもない。 そんな知識がなくても務まるし、実際備わっていない人が大半。 だからSIにおけるプログラマはどう間違ってもエンジニアではない。 もしエンジニアなどと言ってしまったら、他の分野の「正しい」エンジニアに失礼だろう。 というか、エンジニアと呼べるレベルには程遠いと言い換えてもいい。 まあライン工としては一人前だと思うが。 以上のことから結論づけると、タイトル
前提としての情報 単に「Figmaで要件定義のためのUMLも、外部設計のためのデザインも、内部設計のためのERDも全部つくるよ〜〜」という話をすると、ERD書くならデザインツールなんて使わないで、DBMSから自動生成できるツールとか使った方がいいじゃん、みたいな疑問が出るのは重々承知なので、そもそもこの形式に落ち着いた前提事項を書いておきたいと思います。 ご興味がなければ読み飛ばしてください。 筆者の仕事範囲 さて、冒頭で「事業会社でデザイナーとPMの狭間みたいな仕事をしてます」と書きました。キャリアの背景的には受託のPMっぽい仕事(厳密には違うんですが、本旨ではないので割愛します)→事業会社のインハウスデザイナー→現職という感じで、外渉から手を動かす所まで、必要ならなんでもします。 ざっくりいうと、機能の起案をして、経理などの関連部署に相談して、WBS引いて、UML書いて、画面遷移図書い
この記事について Go言語公式から提供されているThe Go Programming Language Specificationという文章があります。 実際のThe Go Programming Language Specificationのページ画面 この文章、個人的にはじっくり読んでみると結構得るものが大きいな、と感じるものです。本記事では The Go Programming Language Specificationって何が書いてあるの? 読んだら何がわかるの? 読むときにはどういうところに注目したらいいの? 英語難しいから単語教えて! という疑問に答えながら、The Go Programming Language Specification精読の布教を行います。 The Go Programming Language Specification とは? The Go Prog
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く