テクニカルライティングの基本テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023
Web開発・オンボーディング・採用の実例に学ぶ、リモートワークのコミュニケーションと文書術 - エンジニアHub｜Webエンジニアのキャリアを考える！
Web開発・オンボーディング・採用の実例に学ぶ、リモートワークのコミュニケーションと文書術 リモートワークへの注目が高まっていますが、いざ運用すると対面とは異なるコミュニケーションに四苦八苦しているのではないでしょうか。本記事ではリモートワークを長年実践しているYassLab株式会社の安川要平（@yasulab）さんに、具体例を交えながら解説していただきます。 はじめまして！ 2012年に創業し、創業当初からリモートワークで働いているYassLab株式会社の安川（@yasulab）です。弊社では、RailsガイドやRailsチュートリアルといった大型コンテンツを日々更新し、36時間以上ある解説動画や1,400ページ超えの電子書籍などを個人・法人向けに提供しています。 本記事では、8年ほど実践してきたリモートワークの中で、読者の皆さんに役立つ（かもしれない）実例をいくつかご紹介します。日々の
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜Anno Takahiro
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
開発者の開発者による開発者のためのAgileドキュメンテーション - Qiita
開発者であれば避けては通れないドキュメンテーション。 しかし多くの開発者が嫌がっているドキュメンテーション。 今回はアジャイル型開発（以下、アジャイル）のプロジェクト・チーム開発者における最適なドキュメンテーションについて考察したいと思います。 アジャイルとドキュメント ドキュメントは書かなくて良い？ 日本においてアジャイルはゆっくりだが確実に浸透しています。 7年間アジャイルをしていた私としては嬉しく思う反面、世間には誤った認識が広がっているのもまた事実です。以下はアジャイル勘違い集の抜粋です。 Q. ドキュメントを書かない？ もちろんアジャイルプロセスでもドキュメントは書きます。ただ優先順位が異なるだけです。 ... 最小限の文書化で最大限の効果を狙う、必要にして十分なドキュメント。そうしたドキュメントは一朝一夕に書けるものではありません。 ― ドキュメントを書かない？｜アジャイル勘違
我々はいかにシステム開発におけるドキュメント腐る問題と戦えば良いのか
フューチャーアーキテクト Advent Calendar 2017 の2日目です。 システム設計が大好きで大嫌いな皆さん、こんにちは。 突然ですが、皆さんはどのようにシステム設計における ドキュメント腐る問題 に立ち向かっていますか？ … ドキュメント腐る問題とは、設計時に作成した各種ドキュメントがGoogle Driveやファイルサーバ上で陳腐化してしまい、現状の正しい状態を指していないことです。せっかく新規参画者がキャッチアップしようとしてもドキュメントが真実を示していないという怖いやつですよね。 今まで出会った一番辛いドキュメントは、PJ初期に作成したホワイトボードに書かれたラフスケッチの画像しか無かったところですね。まず字が汚いし、内容も最新版と微妙に異なっていました。新規参画者殺しにもほどがあると、ほんのちょっとだけ恨みました。 いやいや、ちゃんとサボらず整合性を取れよって？サボ
プロダクトのドキュメントにプルリクエストを送れる仕組みがすごい - Qiita
これ↓なんですけど、意外と RT や Like が付いてたので、ちゃんと書きますね。 しっかしMicrosoftのドキュメントシステム良く出来てるなー。右のEditボタン押すとGitHubが開いてすぐPR送れる。あちらでマージされれば即サイトに反映される。Contiributorsに自分のアイコンが増えた♪ これはフィードバックするのに「面倒」は理由にできないですぞ。https://t.co/9KhAwhV5PP pic.twitter.com/r46zFUvkEp — あめいぱわーにおまかせろ! (@amay077) 2018年6月12日 このツイは Microsoft の製品やサービスのドキュメントについてなんですが、 Microsoft Docs というポータルがありまして、同社のサービスの多くはここでドキュメント公開されている模様です。 ここで公開されているドキュメント群は、バック
エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita
はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォーターフォール、を前提として読んでいただいた方が、しっくりくると思われます。 ＜ご注意＞ 本稿の内容は執筆者独自の見解であり、所属企業における立場、戦略、意見を代表するものではありません。 個人的に心がけていること 当該文書の作成目的や位置付けを冒頭に記載する
Documentation Driven Contractsについて調べてみた - mookjp.io
Documentation Driven Contractsについて調べてみた May 15, 2017 ( May 15, 2017 更新 ) モチベーション 最近業務で、社内の他のチームに提供するAPIを開発している。 関わっている人が少なければ、みんなで近くに座って都度仕様について相談していけばいい。（感覚的には〜7人くらい？） しかし、会社全体の人数が多く、関わるチームも複数いるため（サービスのモバイルアプリ担当、Webフロント担当、バックエンド担当…など）包括的で都度更新されるドキュメントがないと開発効率が悪い。 とはいえ、API提供チームとしては、実装になるべく多くの時間を使いたい。具体的には以下の条件を満たす手法があればよい: ドキュメント作成にかける時間を短くできる 作成したドキュメントの内容が正確（最新であることが必須） 一番原始的な手法として、ドキュメントをちまちま人手
#テクシオ で「DevOpsとドキュメントデザインパターン」の話をしました＋α - 下町柚子黄昏記 by @yuzutas0
概要 先日、Tech Night @ Shiodome # 4というイベントに参加して、LTをしてきました。 どんなイベントか 「DevOpsと自動化」をテーマに、事例・知見を共有する場でした。 もとはソフトバンク様の社内勉強会で「外部ゲストを呼ぶ → 公開イベントになった」とのことです。 社会にシェアする姿勢が素敵だと思いました。 他の参加者の発表 あたりまえのことをあたりまえにやる難しさ AWS ECS （EC2 Container Service）を用いた AWS へのDocker コンテナデプロイ 自動化におけるコード管理 送信メールサービスをユニットテストしてみた DevOps、本当のところ こちらのConnpassのページに資料が上がっています。 どんな話をしてきたか こちらが当日の発表資料になります。 ざっくり説明すると DevOps（全体最適化）の前に、業務標準化（ドキュメ
[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成 | DevelopersIO
APIを作るとき みなさん、毎日API使ってますか？私は、ワンライナーでAPIをコールすることにハマっています。さて、いつも使っているAPIを作る側になったとき、どのように設計していますでしょうか？また、作ったAPIをどのように使ってもらっていますか？そんな疑問に応えるサービスがApiaryです。 Apiaryとは？ Apiaryは、REST APIをサクッと書けるサービスです。また、APIドキュメントも生成してくれます。モックサーバも提供してくれます。API利用サンプルコードも作ってくれます。うん、使わないって選択肢は無いですねｗ。 無料登録すると早速使えるようになります。チームでプライベートなAPI開発をしたければ有料プランを選択してください。 API開発の流れ API開発の流れは、まずはじめにMarkdown形式でドキュメントを書きます。既にサンプルがあるのでこれを使ってみましょう。
![[Apiary]Markdownで始めるAPI開発とAPIドキュメント作成 | DevelopersIO](https://cdn-ak-scissors.b.st-hatena.com/image/square/60d7120d91185f1739fec5fcbd006f066b98e9f6/height=288;version=1;width=512/https%3A%2F%2Fdevio2023-media.developers.io%2Fwp-content%2Fuploads%2F2015%2F02%2Fapiary-logo.png){kind=logo}
わかりやすいREADME.mdを書く
GitHubなどに自分のツールやライブラリを公開するとき，README.mdは重要な役割を担っている．レポジトリを訪れたユーザが自分のツールを使ってくれるか否かの第一歩はREADME.mdにかかっている，と言っても過言ではない．実際自分が使う側になったときも，まずREADME.mdを読んで判断していると思う． 成功しているプロジェクトを参考にしつつ，自分が実践していることをまとめておく．ここに書いていることはあくまで（自分の中で）最低限的なものである．プロジェクトが成長していくにつれてREADMEはあるべき姿に成長していくべきだと思う． READMEの役割 README.mdには大きく2つの役割がある． プロジェクト，ツールの使い方，インストール方法 プロジェクト，ツールの宣伝 元々READMEは前者の役割しかなかったが，GitHubの仕組み上，後者の役割も徐々に重要になっている． さらに
Rubyで定義したメソッドの使用例をYARD用のドキュメントとして書く方法 - 2013-09-19 - ククログ
はじめに YARDというRuby用のドキュメンテーションツールがあります。APIのドキュメントの記述方法は大きく2種類ありますが、YARDはコードにコメントとしてドキュメントを埋め込む形式を採用しています。専用の記法を使って構造化された読みやすいドキュメントを書けることが類似ツールであるRDocとの大きな違いです。 今回は「Rubyで定義したメソッドの使用例を示す」ドキュメントのYARD流の書き方を紹介します。 なぜ使用例の書き方を説明するかというと、使用例を1つ示すだけで使い方をぐっとわかりやすく説明することができるからです。もちろん、引数や戻り値などメソッドについての情報も必要ですが、それらは断片的な情報なため、そこから全体像をイメージするにはもうひとステップ必要になります。一方、使用例は詳細を示すことには不向きですが、どんな状況で使うのか、どのように準備して使うのかといった前後関係も
軽量JSONパーサー『jq』のドキュメント：『jq Manual』をざっくり日本語訳してみました | DevelopersIO
jq Manual jqで簡単JSON加工 ｜ Developers.IO jqコマンドが実は高性能すぎてビビッた話 - beatsync.net JSONを超絶に読みやすくする jq コマンド - WebAPIバリバリ使うor開発する人必須 CLIでJSONの整形をする - ( ꒪⌓꒪) ゆるよろ日記 JSON形式の情報を様々な条件や書式として成形、フィルタリングツール『jq』。上記関連エントリで私もこのツールの存在を知る事になったのですが、ツールの簡易さ・便利さに感動しながら私もちょくちょく利用させてもらっています。 そこでこのエントリでは、jq公式ページに展開されている利用ガイド・リファレンス的な位置付けの『jq Manual』を写経がてらざっくり日本語訳してみました。ざっくり訳なのでこの部分の訳おかしい・間違ってる等ありましたら御指摘頂けると幸いです。例示されているサンプルコードも
Dash で gem のドキュメントを参照する - satococoa's blog
@satococoa やっぱウェブみにいくんですね、了解です。この辺も Dash とかで見れるようにしたいな— Naoya Itoさん (@naoya_ito) 1月 22, 2013 こんな話から、インストールした gem のドキュメントが見られる風な Docset が Dash にあったのを思い出してちょっと調べてみました。 以下の手順に沿ってちょこちょこっと設定をすると、RDoc で生成された gem のドキュメントが見られました。 設定方法 Preferences… -> Downloads から “Ruby Installed Gems” というdocsetをインストール Preferences… -> Docsets に Ruby Gems という docset があるので、その一番右にあるギヤのボタンからrdocが置かれているパスを設定する。gem env gempath と
Full featured documentation deployment platform
Documentation simplified Build, host, and share documentation, all with a single platform. Sign up now Easy previews and deploys Preview changes on every commit to your pull requests. Release documentation to your users on each merge. Ideal developer experience Write documentation without changing your workflow or your tools using a docs as code approach. Work privately or publicly Easily share wi
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
