テクニカルライティングの基本
テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023
テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023
文章の書き方に正解はない。 ただ、ちょっとした「コツ」みたいなものはあると思う。 僕は会社に入ってから9年間、「週刊文春」と「文藝春秋」の編集部で、文章に携わる仕事をしてきた。 たかだが10年足らずの経歴で何を偉そうに、と思われる方もいるかもしれないが、最近になってようやく、「文章を書くコツみたいなものがあるのではないか？」ということに気がつき始めた。 もちろん一流作家のような芸術的で天才的な文章を書くコツではない。文才の有無は関係なく、誰でもそれなりに整った文章を書くためのコツだ。 noteをやっている人の中には「何かを書きたい、でもどうやったら書けるだろう」と思っている人がいると思う。また、「書きたいんだけど、素人の書いた文章みたいに読まれたら恥ずかしいな」と思って、躊躇している人もいるかもしれない。 さらに、「周りから『何でもいいからとりあえず書いてみたらいい』と勧められるんだけど、
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました！ ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー！ 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
文科省の公用文作成の考え方って資料、めちゃくちゃ役立つから論文書く人とか社会人になって社外にメールを送るのが苦手って人は読むのをおすすめする。
ぎーち(ブレイク兄) @BREAK_BROTHER 小型衛星の電源屋さんでヤンス。趣味でも衛星開発やっとります。衛星に携わってる方はぜひ仲良くしてクレメンス… 東方サークル(ネタタイトル萌えジャケットガチクラシック人工衛星サークル)"Windbreaker"のネタタイトル人工衛星担当です。アイコンはかじつおひま様、ヘッダーは人間猫様に描いていただきました！ twpf.jp/BREAK_BROTHER リンク Yahoo!ニュース お願い「致します」漢字はNG? - Yahoo!ニュース 「よろしくお願いいたします」ビジネスメールでは常套句ともいえる一文に注目が集まっている。きっかけはX上のあるユーザーの投稿。そのユーザーは「よろしくお願いいたします」の「いたします」部分について、ひ 3 users
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
第0部 まずは「分かりづらい説明」を知ろう（p.14～） 第1部 口頭説明編（p.25～） 第2部 資料作成編（p.63～） 第3部 スライド作成編（p.81～） スライドのまとめ（p.115～）
「VS Code Meetup」は、強力かつ軽量なオープンソースのコードエディター「Visual Studio Code」のミートアップです。今年もVS Code Meetup 主催の年次カンファレンス、「VS Code Conference Japan 2021」が開催されました。招待講演では、SF作家の藤井太洋氏が登壇。VS Codeで執筆を支援する機能拡張「novel-writer」の制作について発表しました。 『Hello, World!』で吉川英治文学新人賞を受賞したSF作家 藤井：お時間いただきまして、ありがとうございます。本日、「Visual Studio Codeで小説を書く」というセッションを持たせていただく、SF作家の藤井太洋です。それでは、プレゼンテーションを進めます。 まず簡単な自己紹介から。私は、2012年に『Gene Mapper』というサイバーパンク小説をセル
Excel設計書を抹殺したくて4年前にWiki設計書を導入したら、意外とちゃんと開発回ってた話。 - Qiita
初めましてこんにちは。 最近コードレビューの記事書いたら、Excelベースだったことを理由に Qiitaコメントとはてブで徹底的に燃やされたおじさんです。 いやね、僕だって使いたくて使ってるわけではなくてね、 できることなら使いたくないんですよ。 というわけで名誉挽回のために脱Excelできた話、 それも日本の三大悪三大風習に数えられるExcel設計書を抹殺した話を書きます。 (2/25修正：悪は言いすぎました。訂正します。） Growi 最高。 またの名をExcel方眼紙。 エクセルのセルの縦横を同じくらいの大きさに調整し方眼紙のようにして、 そこに設計書として文字と図と表を記載する方式。 メリット 一つのファイルに文字と図と表がまとめて記載できる テキストでは文字は書けても図と表が書けない Wordでは、文字と図表エリアとを2列表示するのが難しい できなくはないが面倒くさい UMLモデ
手順書フォーマットは千差万別 みなさんは自己流または、組織やプロジェクトで定められた手順書のフォーマットはありますか? 私は自己流の手順書フォーマットがあります。 自己流の手順書フォーマットがあるといっても、かなり扱いがふわふわしているので、備忘やメモの意味合い強めでまとめていきます。 「もっとこうした方がいいよ!!」などフィードバックがあれば、ぜひお願いします! いきなりまとめ 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書はgitで管理する 5W1Hを意識して手順書を書く 基本的にはCLIを使った手順書にする 手順書はExcelやスプレッドシートではなく、Markdownで書く 手順書をExcelやスプレッドシートで書くメリット・デメリット 手順書をExcelやスプレッドシートで書いている方も多いと思いますが、私はMarkdownで書いています。 Exce
自分が良い Design Docs(Software Design Document)を書くために、読んだ/参考になったリソース集 一覧 Design Docs とは Design Docs at Google デザインドック(Design Doc)について デザインドックで学ぶデザインドック 残業も減らせる!? 上級エンジニアになるための Design Doc 超入門 「Design Doc」って何なのか？ What Is A Design Doc In Software Engineering? (full example) What is a Design Doc: Software Engineering Best Practice #1 https://github.com/kaiinui/note/blob/master/Design--Designdoc.md Googleの
mhidakaです。 #技術書典 9も終わって商業出版のお誘いもある出展者さんも多いと思うので今回は著者目線での契約ケーススタディをご紹介します。評判がよかったら追記したりしようかな。 対象としている書籍は技術書です。技術書は発行部数も桁違いに少なく書店でもマイナージャンルです。一般的なコミックや小説、新書はあてはまらないと思います。読み物としてお楽しみください。 誤字脱字、内容のあやまりなどあれば教えて下さい。修正すると思います。 契約とは何かはじめに契約とは契約する甲・乙の両者にメリットがあって成り立つものです。相互のメリットがデメリットを上回るように取り決めて合意に至るという点が肝要です。自由意志に基づくので、どちらかが何かを強要するものではありません。強要されている・デメリットが勝る、そう感じたら契約しないという選択肢を思い出してください。 メリット・デメリットについて著者は把握し
いさけんさん【目指せ令和の紀貫之チャレンジなう】 on Twitter: "塾で教えていて、わりと衝撃的だったことの一つが「国語の教科書以外で、まとまった文章を読んだことがない子」の存在を、リアルに目の当たりにしたときのことだ。当時、その生徒は中学二年生だったが、計算問題以外は壊滅的で、その理由を探していたときに、ふと思い至って本人に確認をしてみた。"
塾で教えていて、わりと衝撃的だったことの一つが「国語の教科書以外で、まとまった文章を読んだことがない子」の存在を、リアルに目の当たりにしたときのことだ。当時、その生徒は中学二年生だったが、計算問題以外は壊滅的で、その理由を探していたときに、ふと思い至って本人に確認をしてみた。
GitBookはMarkdownからドキュメントページや書籍を作成するツールですが、 以前OSSで公開されていたGitBook(legacy)はDeprecatedとなって開発は止まっています。 ⚠️ Deprecation warning: As the efforts of the GitBook team are focused on the GitBook.com platform, the CLI is no longer under active development. All content supported by the CLI are mostly supported by our GitBook.com / GitHub integration. Content hosted on the legacy.gitbook.com will continue worki
自治体の“正規”職員の求人に550倍の応募が殺到。兵庫県宝塚市の話です。人手不足の時代にこんなに働きたい人がいるなんて…。実はこの求人、就職氷河期世代と呼ばれる人たちが対象、この世代の“正社員化”を進めようという動きが相次いでいるんです。 そもそも就職氷河期世代とは？そして、そのように呼ばれる人たちが、当時、どのような困難に直面し、苦しんできたのか。当事者に話を聞くことから取材を始めることにしました。 そう話すのは小林誠さん（41）。新潟県南魚沼市ののどかな町で母親と２人で暮らしています。思いをしっかりと伝えたいと実名で取材に応じてくれました。 小林さんが地方の国立大学を卒業したのは今から18年前の平成13年。就職氷河期はバブル崩壊後の就職難だった平成５年から16年頃を指すので、まさにまっただ中の時期でした。当時、大卒の求人倍率は※1.09倍。来年３月卒の1.83倍と比べると、いかに低かっ
【これでスッキリ】誰でも文章がスラスラ書けるようになるコツ！上阪徹 さん著書の「文章の問題地図」 - イザちゃんの気まぐれ日記 - 仕事も恋愛も頑張る人を応援したい♪
上阪徹 さん著書の「文章の問題地図」を読みました(*^-^*) ブックライターの著者さんが、「文章の問題地図」と題し、 誰でも文章がスラスラ書けるようになるコツを指南してくださる一冊です。 「スラスラ書けない、時間がかかってしょうがない」 「何を書いていいのかわからない」 「支離滅裂だと叱られる」 こうした悩み、あなたに訪れた経験はありますか？ 本書は、文章に対する多くの悩み・問題は、ちょっとした発想の転換で解決すると提起し、 文章を書く仕事を長く続けてきた著者さんによる、シンプルに書けるようになる方法が書かれています。 著者さんは、長年の文書を書く経験を通して、大きく２つのことを発見しました。 ・発見①：立派な文章を目指す必要はない ・発見②：「素材」に目を向ければ、すぐに書けてしまう この２つに気づいて、文章を作成するだけでも、書きやすさは劇的に変わってきます。 著者さん自身は、文章に
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
文才の有無に関係なく、誰でもそれなりに整った文章を書くコツ｜村井 弦｜文藝春秋
仕様書の参考例と、こんな内容を仕様書に最低書くといいというお話｜田辺めぐみ
わかりやすいシステム構成図の書き方 - Qiita
わかりやすい説明のための 10 の鉄則
「Visual Studio Code」で執筆するSF作家 藤井太洋氏が作る物書きのための拡張機能
自己流の手順書フォーマットを公開してみた | DevelopersIO
【メモ】良いDesign Docs(Software Design Document)を書くためのリソース集
著者が出版契約で知るべき7つの項目｜mhidaka
新しい「公用文作成の要領」に向けて（報告） 令和３年３月 12 日 文化審議会国語分科会
GitBookをForkしてHonKitを作りました
News Up 就職氷河期世代の“叫び” | NHKニュース