テクニカルライティングの基本 2023年版テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter：https://twitter.com/naoh_nak 2022年版（初版）：https://speakerdeck.com/naohiro_nakata/technicalwriting
ドキュメント作成時のあるあるアンチパターン20 - Qiita
業務でドキュメントを作成するケースは多々ある 例：仕様書・設計書・提案書・メール・障害票．．． ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。 1. 表記がバイト表示・マイクロ秒表示 プログラムが出した数値をありのままに表示するパターン ファイルサイズが100MB, 1GBあろうと、バイト表示にする 桁数が多い数値に、桁区切り（,）を入れない 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？） 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様） 悪い例 No ファイル名 ファイルサイズ(byte) 処理時間(秒)
読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜Masato Tanaka
こんにちは。壮（@sew_sou19）と申します。 メガベンチャー企業でエンジニアとして働いています。 エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。 リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる — 壮 (@sew_sou19) November 28, 2022 そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2
About this guide | Google developer documentation style guide | Google for Developers
Send feedback About this guide Stay organized with collections Save and categorize content based on your preferences. This style guide provides editorial guidelines for writing clear and consistent Google-related developer documentation. If you're new to the guide and looking for introductory topics about our style, then start with Highlights, Voice and tone, and Text-formatting summary. Otherwise
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
Overview of technical writing courses | Technical Writing | Google for Developers
The pre-class components introduce topics; the in-class components help students integrate and practice those topics. That said, the pre-class work, by itself, provides significant educational value. Google provides all the materials needed to run the in-class sessions at your own organization. If you'd like to facilitate the in-class sessions for your organization, please see Facilitating Technic
Infrastructure as Codeにおける理想のドキュメント管理を目指して #infrastudy | DevelopersIO
インフラをコードで管理するInfrastructure as Codeだからこそ、必要なドキュメントについての考察とそれの管理方法についてLTした様子です。 「なんや、この視聴者数… 震えが来るぜ・・・」 先日開催されたInfra Study Meetup #2「VM時代の開発とCloud Native時代の開発」 - connpassにおいて、「IaCにおける理想のドキュメント管理を目指す」という内容でLTしてきましたので、その内容をお届けします。 当日は、イベント内容も登壇者も超絶豪華で、なんとリアルタイム視聴者数1000人超えということで、さすがに自分も緊張しました。まじで。 青山さんのメインテーマがKubernetesの話であり、前後それに関わるテーマが中心の中、Kubernetesもコンテナも1ミリもでてこない発表にしたのですが、IaCに関わる普遍的な考慮ポイントについて喋れたの
How to Write Good Documentation (And Its Essential Elements)
This post highlights some of the key components of good documentation, and goes through some of the steps you could take to improve the way you document your code. Documentation is one of the most important and under-rated aspects of any library or open-source project. If you are writing code that will be used by someone other than yourself, it needs to be documented. Period. After using many libr
Google、技術文書を公開するようなWebに向けたテンプレート集「Docsy」を公開 | OSDN Magazine
Googleは7月10日、オープンソースプロジェクトのドキュメント公開に向けたWebサイトテーマ「Docsy」を公開した。ドキュメントを公開するサイトを簡単に立ち上げて運用できるという。 Docsyは技術文書を公開するようなWebサイトのためのテーマで、Webサイト構築のためのフレームワーク「Hugo」をベースとする。Googleは2000以上のオープンソースプロジェクトを抱えており、ドキュメンテーション作成と公開のためのツールが必要だったことから構築したとのこと。技術文書向けのテンプレートとガイドを備えており、すでにKubeflow、Knative、Agonesなどのプロジェクトで利用しているという。 ナビゲーション、サイト構造などの機能を提供するほか、多言語にも対応する。ページの追加、ドキュメンテーションの構造化、コミュニティからの貢献などについてもガイドを提供するという。 Docsy
音声入力で文章作成を爆速化する方法｜かおるん
～私が1500字のブログを45分で完成させている方法ぜんぶ晒す～こんにちは。 音声入力では、漢字変換をする必要がなく、またタイピングよりも速く入力することができます。 私は音声入力を始めてから、ブログを更新できる頻度が3倍くらいになりました。 (以前は1日1回がやっとでしたが、今は楽々1日3回くらい更新しています。) 毎日楽しく使っている音声入力のことをお伝えしたくて、 また、いま音声入力を使われている方も、より早く正確に音声を入力することができるようになるために、 私が普段やっていることやコツを全て詰め込みました。 あなたの音声入力ライフに少しでもお役に立てれば幸いです。 尚、このnoteは投げ銭方式です。 最後まで無料でお読みいただけます。 投げ銭してくださった方に、ちょこっとお礼も用意しています。 前提45分間の作業に含まれるもの ○タイトルを決める ○構成を考える ○見出しを決める
技術書を書きたいITエンジニア必見！？「プロを目指す人のためのRuby入門」の舞台裏をお見せします - give IT a try
前回のブログでも書いたとおり、僕は2017年12月6日から10日まで東京に滞在していました。 そこで出会ったRubyプログラマのみなさんからよく聞かれたのは「あの本（＝プロを目指す人のためのRuby入門）って、書くのにどれくらいかかったんですか？」という質問です。 たしかに、Rubyのコードを書く人は多くても、本を書く人はあまりいないと思います。 そこで、このエントリでは執筆の様子がある程度わかるように、「プロを目指す人のためのRuby入門」（チェリー本）の執筆裏話を書いていこうと思います。 プロを目指す人のためのRuby入門 言語仕様からテスト駆動開発・デバッグ技法まで (Software Design plusシリーズ) 作者: 伊藤淳一出版社/メーカー: 技術評論社発売日: 2017/11/25メディア: 大型本この商品を含むブログを見る ちょっと長いので先に目次を載せておきますね。
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
ドキュメントの継続的な開発方法 | IIJ Engineers Blog
私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
ndiag/docs/tutorial.ja.md at main · k1LoW/ndiag
開発効率を上げる！ 攻めのドキュメンテーション
運用ドキュメント2019/20190824-odc-operation-document
手順書＝レシピ - Google スライド
nishio hirokazu on Twitter: "「書く」は大きくて達成条件不明瞭なタスクなので不慣れな人の最初の一歩のタスクとしては難易度が高い。僕は「まずは時間を2分とか5分とか区切って、書きたいものに含まれているとよさそうな言葉や文章、考えの断片を全部書き出してみましょう」… https://t.co/vmf49BlOjk"