良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる
ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。 www.writethedocs.org はじめに これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、
質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
生のCSSからスタイルガイド用ドキュメントを自動生成できる「Kalei」:phpspot開発日誌
Kalei Styleguide - CSS Living Style guide 生のCSSからスタイルガイド用ドキュメントを自動生成できる「Kalei」 プログラミングのソースコードからドキュメントを生成するツールなどはよくありますが、CSSからスタイルガイドを生成し、マークアップ記述の際に参照できるという便利そうなツールです。 CSSって書いているとどんどん追加されていくものですし、毎回それをドキュメント化するのは面倒でやらなくなるっていうパターンが多い気がしますが、これで自動化すればCSSさえ編集すればドキュメントが生成されて、開発側もそれを参照すればデザインに困らない、という効率的な開発スタイルがとれそうです。kalei自体はRubyで書かれているっぽいです 関連エントリ Chrome、FF、IE等クロスブラウザで使えるブラウザキャプチャツール「qSnap」 フラットでシンプルさ
VBDOX - Visual Basic Documentation Generator
Overview VBDOX is a simple program that generates technical documentation from source comments. The only requirement is to use specific module and function comments format. Documentation is generated for all types Visual Basic files and also for VBScript and ASP (limited support) The program can be extended to support different documentation comments and reports. Right now the program has three re
スタイルガイドをダウンロード － マイクロソフト | ランゲージ ポータル
すべて Microsoft 製品OfficeWindowsSurfaceXboxお買い得商品サポート ソフトウェアWindows アプリOneDriveOutlookSkypeOneNotePC とデバイスPCs & tabletsアクセサリエンタメXbox とゲームゲームWindows ゲーム映画とテレビ番組法人向けMicrosoft AzureMicrosoft Dynamics 365Microsoft 365エンタープライズ ソリューションデータ プラットフォームDeveloper & IT .NETVisual StudioWindows ServerWindows アプリの開発ドキュメントその他Microsoft StoreMicrosoft Rewards 無料ダウンロード & セキュリティ教育プリペイド カードサイトマップの表示
ASP.NET Web: The Official Microsoft ASP.NET 2.0 Site : Home Page
Free. Cross-platform. Open source. A framework for building web apps and services with .NET and C#. Get started Supported on Windows, Linux, and macOS Interactive web UI with C# Blazor is a feature of ASP.NET for building interactive web UIs using C# instead of JavaScript. Blazor gives you real .NET running in the browser on WebAssembly. Learn about Blazor
ツールを使ったドキュメント作成技法（後編）（1/3） - ＠IT
特集：ツールを使ったドキュメント作成技法（後編） マイクロソフトも実施しているドキュメント作成技法 アバナード株式会社 市川 龍太（Microsoft MVP 2008 for XML） 2008/07/23 前編では、価値のあるドキュメントを作成するためのコツと、効率的にドキュメントを作成するためのツールとして「SandCastle」を解説した。後編では、そのほかのドキュメンテーション支援ツールとして「GhostDoc」と「patterns & practices Documentation Tools」について解説する。 ■柔軟なXMLドキュメント・コメントを生成する「GhostDoc」 GhostDocは、あらかじめ設定した任意の書式にのっとったXMLドキュメント・コメントを生成してくれるVisual Studioアドインであり、MSDNマガジンにて「すべての開発者がダウンロードする
* Dynicity,LLC ** XML Documentation Comments Guide *
A free user's guide to the XML Documentation Comments Current Version: 1.2.0 Last Updated: 10/02/2007 The download is a available in 3 formats: Windows installer Microsfot HTML Help format (CHM) Adobe PDF format (PDF) The Windows installer package contains the XML Documentation Comments Guide in the following formats: Adobe PDF format (PDF) Microsoft HTML Help format (CHM) Microsoft H
初心者がWord代わりにTeXを使うための最低限の設定などをまとめる - ミームの死骸を待ちながら
「必要性がないけど、ちょっと便利かも」というレベルのものを導入する際の最大の関心事は「今出来ることが新しい環境でも出来るかどうか」で、 もっと細かく言うと「新しいメリット」だけでは人を動かすには十分ではなく、「現状のメリットの保証」も必要であると思う。 何の話かというとTeXの話なのだけど、相変わらず大したこと無い話を小難しい話に持って行く奴である。 で。論文を書くのに（今更）本格的にTeXを使い始めてみたんだけどこれがすごい便利で。なんで今までWordを使っていたのか*1。いや導入が面倒くさそうだったからだし、実際面倒くさかったけど、それを補ってあまりある快適環境が出来ている。嬉しい。 改ページや図の挿入位置。自分でいちいち考えたり、追記して全部ごっそりズレたのを一つ一つ直す必要が無く、好き勝手に書いてコンパイルすれば、いい感じの位置に整えてくれる。賢い！加えて本体の.texはテキストな
わかりやすい技術文章の書き方
誰が読むのか。 読み手にどんな感想を持ってもらいたいか。 読み手はどれくらいの予備知識を持っているか。 読み手はどんな目的で、何を期待して読むのか。 読み手が真っ先に知りたいことは何か。 レポート・論文とは何か 問いが与えられ、または自分が問いを提起し、 その問題に対して明確な答えを与え、 その主張を論理的に裏付けるための事実・理論的な根拠を提示して、主張を論証する。 標準的な構成要素とは何か レポート・論文の構成は、 概要 序論 本論 論議 という要素が標準的である。次にそれぞれの要素について簡単に見てみる。 概要 論文全体を結論も含めて、すべて要約する。 序論 本論で取り上げる内容は何か。 その問題をどんな動機で取り上げたのか。 その問題の背景は何か。 その問題についてどんなアプローチを取ったのか。 本論 調査・研究の方法・結論 論議 自己の議論・結論を客観的・第三者的に評価する。 そ
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方
HowToWriteAnEffectiveDesignDocument - 設計文書のうまい書き方 目次 この文書について 設計文書のうまい書き方 なぜ設計文書を書くのか 良い設計とは何か 同僚の開発者に向けて書く 第 1 節に書くこと: プロジェクト/サブシステムの目的を示す 第 2 節に書くこと: 設計に使う高レベルなエンティティを定義する 第 3 節に書くこと: 個々のエンティティに関する低レベルの設計を書く 使い方 設定 モデル 相互作用 第 4 節に書くこと: 利点, 前提, リスク/懸念事項 マネージャ向けに書くこと 最後に 設計文書のうまい書き方 この文書について "How to Write an Effective Design Document" の日本語訳です. http://blog.slickedit.com/?p=43 推敲歓迎: 誤訳, タイポ, 訳語の不統一,
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
https://pldoc.sourceforge.net/maven-site/
RedHat Linux 技術的な質問(Part2) FAQ
セッション資料ダウンロード｜QCon Tokyo 2010 Conference｜QCon 東京 2010 カンファレンス
[Think IT] 第3回：リポジトリを使用したドキュメントの入力支援 (1/3)