技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
LINE社内テクニカルライティング講座第2弾！1文では説明が終わらない文章を書くコツ
こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。先日、このLINE Engineering Blogで「LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた」というタイトルで、1文を書くときに気をつけていることや手法について紹介しました。 前回の記事を簡単にまとめると「たくさんの文案を書いて、一番良さそうなものを選択することがとても大切です」という話を多くの例文を使って説明しました。まだ読んでいない方はぜひ読んでみてください。 今回の記事は、第2弾です。次のステップとして「1文では説明が終わらない文章をどのように組み立てていくとわかりやすいか」という話を、以下のような文章を例に説明していきます。 ここでは、このくらいの情報量の文章を「トピック」と呼びます。 第2弾を最後まで読む
正確な文章の書き方
このページでは、正確な文章を書くための秘訣をまとめてみようと思います。それほど文章がうまいとはいえない私が、文章の書き方について述べるのですから、むこうみずな行為であることは百も承知です。しかし、数年に渡って探求した正確な文章の書き方が、少しでもみなさんの役に立てばという思いを自分への励ましに代えて筆をとります。 ここでお話するのは、「文章をいかに正確に書くか」や「自分の考えをどうやったら適切に表現できるか」であって、決して「どうやったら人を感動させる名文句が書けるのか」ではありません。 このページを読んだら「科学技術文献」を書くための技術が少しは身に付くのではないかと期待しています。しかし、 人はいさ 心も知らず ふるさとは 花ぞ昔の 香ににほひける (紀貫之) などのような心に残る文章が頭に浮かぶようになるわけではありません。 絵の書き方に例えて言うなら、ここで述べる内容は、色彩や調和
LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた
LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。今日は、私が1文を書くときに気をつけていることや手法についてお話しします。 そして、この書き出しは、6月にmochikoさんが書いた「LINEの社内には「テクニカルライティング」の専門チームがあります」という記事のオマージュになっています。mochikoさんが書いた記事ですごいpvをたたき出したそうなので、人のふんどしで相撲を取ってみようという作戦で始めてみました。 この記事ではLINE社内で私が講師を務めた「LINE社内で大評判のテクニカルライティング講座」に沿って、わかりやすい1文を書くコツを紹介していま
自動改札機の運賃計算プログラムはいかにデバッグされているのか？ 10の40乗という運賃パターンのテスト方法を開発者が解説（前編）
自動改札機の運賃計算プログラムはいかにデバッグされているのか？ 10の40乗という運賃パターンのテスト方法を開発者が解説（前編） ふだん何気なく使っている鉄道。改札を降りるときにICカードを自動改札にかざすと、「ピッ」という音と共に一瞬のうちに運賃を計算してくれます。けれど、複数の路線を乗り継いだり、途中で定期券区間が挟まっていたりと、想像しただけでもそこには膨大な組み合わせがあります。それでも運賃計算プログラムはわずか一瞬で正しい運賃計算が求められ、バグがあったら社会的な一大事にもつながりかねません。 爆発的な計算結果の組み合わせがあるはずの運賃計算プログラムは、どうやってデバッグされ、品質を維持しているのでしょうか？ 9月12日から14日のあいだ、東洋大学 白山キャンパスで開催された日本科学技術連盟主催の「ソフトウェア品質シンポジウム 2012」。オムロンソーシアルソリューションズ 幡
Overview — Sphinx v1.0 (hg) documentation
ダウンロード このドキュメントはバージョン1.0 (hg)のためのものです。まだリリースされていません。 Mercurialリポジトリのコードを利用するか、Python Package Indexにあるリリースバージョンを探してください。 疑問? 意見? Googleグループへの参加: もしくは、FreeNodeの#python-docsチャンネルへどうぞ 何か気づいたことがあれば、issue trackerを使用して通知することもできます。 Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。 このツールはもともと、新しいPythonのドキュメントの変換のために作られました。そして、今までに数々のPythonや、他の言語で開発されているプロジェクトに対して、すばらしいドキュメンテーシ
わかりやすい技術文章の書き方
誰が読むのか。 読み手にどんな感想を持ってもらいたいか。 読み手はどれくらいの予備知識を持っているか。 読み手はどんな目的で、何を期待して読むのか。 読み手が真っ先に知りたいことは何か。 レポート・論文とは何か 問いが与えられ、または自分が問いを提起し、 その問題に対して明確な答えを与え、 その主張を論理的に裏付けるための事実・理論的な根拠を提示して、主張を論証する。 標準的な構成要素とは何か レポート・論文の構成は、 概要 序論 本論 論議 という要素が標準的である。次にそれぞれの要素について簡単に見てみる。 概要 論文全体を結論も含めて、すべて要約する。 序論 本論で取り上げる内容は何か。 その問題をどんな動機で取り上げたのか。 その問題の背景は何か。 その問題についてどんなアプローチを取ったのか。 本論 調査・研究の方法・結論 論議 自己の議論・結論を客観的・第三者的に評価する。 そ
ドキュメント作成に参考になる公開ドキュメント集
Webシステムにてドキュメントを作る際に参考になる公開されているドキュメントを集めてみました。 見た限りはどれも無償で利用可能なようですが、実際に利用される際は規約等をご確認下さい。 発注者ビューガイドライン http://sec.ipa.go.jp/reports/20080710.html 形式：[PDF] IPAが公開しているドキュメント作成ガイドラインです。 発注者とSIerの間で意思疎通を図ることを目的としているので、内容も詳細でかつ分かりやすいです。分量がかなり多いのですが、JavaでおなじみのPet Storeを題材に具体的なドキュメントが載っているので、ざっと見てみるだけでも参考になると思います。 ただ小規模案件だと、このガイドラインどおりに全てのドキュメントを揃えるのはムリがあると思うので、使えそうな部分だけ上手く利用するのが良いでしょう。 関連書籍も出ているようなので、
Xen 3.4ソースコード、構造紹介 | エンタープライズ | マイコミジャーナル
Xen - hypervisor, the powerful open source industry standard for virtualization. Stephen Spector氏がXen 3.4 Source Code Overview - blog.xen.orgにおいて最近リリースされたXen 3.4のソースコードオーバービューファイルXen Source 3.4 Guide (ODT)を公開した。データはODT形式で、閲覧にはOpenOffice.orgなどのアプリケーションが必要。Xen Source 3.4 Guideの内容はその名前のとおり、配布物のディレクトリ構造とファイルがリストアップされ、そのファイルがなにをするものなのかが簡単に説明されている、というものになっている。どのファイルにどの機能が実装されているのかが把握しやすい。 Xen 3.4 Source
アイコン・外観写真ダウンロード
ヤマハのルーターアイコンを用途を問わず、ご自由にダウンロードできます。 印刷用データとしてご利用の方は、EPSデータをご使用ください。 切り抜いて使用したい方は、PNGをご使用ください。 RTXシリーズ
MOONGIFT: » テキストから各種ドキュメントへ変換する「txt2tags」:オープンソースを毎日紹介
開発用のドキュメントと、提出用のドキュメントと二つ書かなければならないことがある。どちらも似たような内容だが体裁が異なる。だがそのためにコストをかけるというのは非効率的だ。 テスト文書 この手のソフトウェアは数多く存在するが、開発ドキュメントの管理にWikiエンジン（DokuWikiなど）を使っているなら、これの利用はありかも知れない。 今回紹介するオープンソース・ソフトウェアはtxt2tags、一つのテキストフォーマットから各種文書形式に変換するソフトウェアだ。 txt2tagsはすでに7年も開発が行われているソフトウェアで、テキスト文書から各種ドキュメントに変換する機能がある。特にWiki（Wikipedia/MediaWiki形式）、gWiki（Google Code向けWiki）、DokuWIki、MoinMoinのWiki系フォーマットに対応しているのが利点だ。 HTMLでの生成
トヨタグループが「パワーポイント」自粛令!?｜News&Analysis｜ダイヤモンド・オンライン
トヨタグループ内で、マイクロソフトの「パワーポイント」使用の自粛ムードが広がっている。事の発端は、コスト削減を求める渡辺社長の発言だった。それにしてもなぜパワーポイント自粛なのか？ 「パワーポイントの使用は控えた方がいい。特にプレゼン資料のカラーコピーは…」 最近、トヨタ自動車社内からだけでなく、系列会社、サプライヤー（部品会社）のあいだからでさえ、こんな会話が聞こえてくるようになった。事の発端は、何を隠そう5月8日の決算発表での渡辺捷昭社長の発言である。 今年度の営業利益は、円高、原材料高、米国市場の不振という“三重苦”の影響をもろに受け、トヨタといえども、3割減という非常に厳しい見通しだ。決算会見の後、周囲を取り囲んだ記者団に対し、渡辺社長は「もう一度、原点に返って原価低減を行う」と一層のコスト削減を強調した。そして、続いて飛び出した次の言葉がその後のパワーポイント自粛ムードにつ
PDF 千夜一夜: 2008年05月23日 アーカイブ
PDFによる情報保存の法的な有効性 (8) — 首相の国会答弁 「電子取引では印紙税は対象外」というのは、既に、行政府が公式に認めていました。 国会では、平成１７年に民主党の桜井氏が質問をされています。 「電子商取引で添付ファイルなどの形で交わされる電子文書については印紙税の課税対象外となっている。同じ契約書などであるにもかかわらず、文書か電子文書かで印紙税の課税・非課税を判断することは税の基本原則に反している。」 http://www.sangiin.go.jp/japanese/joho1/syuisyo/162/syuh/s162009.htm それに対する当時の小泉首相の答弁では、 「事務処理の機械化や電子商取引の進展等により、これまで専ら文書により作成されてきたものが電磁的記録により作成されるいわゆるペーパーレス化が進展しつつあるが、文書課税である印紙税においては、電磁的記録によ
発表、利用、共有が簡単にできるドキュメント共有サイト！ - docune(ドキュン)
This page is used to test the proper operation of the HTTP server after it has been installed. If you can read this page it means that the HTTP server installed at this site is working properly. The fact that you are seeing this page indicates that the website you just visited is either experiencing problems or is undergoing routine maintenance. If you would like to let the administrators of this
各種ドキュメントをFlash化·Print2Flash Free Edition MOONGIFT
ちょっと前までは文書をPDF化するのが便利だった。プリンタドライバとして動作するPDF作成ツールも数多く登場している。PDFを作成するのは決して難しいものではなくなっている。 次の段階はドキュメントのFlash化だ。この利点は何だろう、閲覧は当然としてブラウザ内で見られるのが便利な点だ。 今回紹介するフリーウェアはPrint2Flash Free Edition、プリンタドライバとして動作するFlash生成ソフトウェアだ。 実はPrint2Flash自体はフリー版ではないものを持っている。Memotuneの中で一時的に利用していた。FlashPaper同様にFlashであればOSの垣根を越えて、さらにブラウザ内でインライン表示できるのが便利だ。 Print2Flash Free Editionはそのフリー版であり、個人の非商用に限って無料で利用できる。利用方法は簡単で、プリンタのように印刷
ビジネス文書に才能は不要、余計なことは書かない - ワークスタイル - nikkei BPnet
ビジネス文書に才能は不要、余計なことは書かない （ロブ＠大月＝フリーライター） （前回記事はこちら） 前回に引き続き、『「わかりやすい文章」の技術』（講談社ブルーバックス）の著者、藤沢晃治さんに、分かりやすいビジネス文書の書き方を伝授してもらう。 余計なことは書かない この3つのほかにも、いくつものコツがあります。そのうちの幾つかも紹介しましょう。 まず、余計なことは書かない、です。主要段落や主題文は、文章のなかで相手に伝えたいコアの内容。それ以外の段落や文は主要段落を支援する働きをします。 分かりやすい文章をつくるためには、主要段落もしくは主題文と、支援段落もしくは支援文だけで文章を構成しましょう。それ以外の無駄な文章を含まないようにすることです。 趣旨と無関係な段落や文は、音楽の中のノイズと同じです。趣旨を読み取る邪魔になるので、できるだけ不必要な情報は書かないようにし
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
exerslide
インフラエンジニアの綺麗で優しい手順書の書き方
IPAが国内のクラウド利用の現状と課題を発表
ドキュメント作成に役立つ「日本語スタイルガイド」の紹介
