30分でわかる「エンジニアのためのドキュメントライティング」- インフラエンジニアBooks / Docs for Developers within 30 minutesインフラエンジニアBooks 30分でわかる「エンジニアのためのドキュメントライティング」( https://infra-eng-books.connpass.com/event/282031 ) の講演資料です。
技術文書を書くための７つのルール
技術文書を書くための７つのルール¶ さまざまな面から見て、良いドキュメントを書くことは、良いコードを書くよりも簡単です。多くの開発者はドキュメントを書くのはとても難しいことであると考えていますが、いくつかのシンプルなルールに従うだけで、本当に簡単になります。 ここでお話しするのは、ポエムの本を書くための方法ではなく、プログラムの設計やAPI、コードベースを作り上げる上で、必要となるものを理解するための包括的なテキストを書くための方法になります。 全ての開発者はそのようなテキストを書くことができます。本節ではあらゆる場面で適用できる7つのルールを提供します。 ２つのステップで書く: まずはアイディアにフォーカスし、その後レビューを行ってテキストの形を整えます。 読者のターゲットを明確にする: それを読むのはだれですか？ シンプルなスタイルを使用する: 分かり易くシンプルに保ちます。正しい文法
「Docs for Developers」を読んだ - 勘と経験と読経
最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。 2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング e34.fmwww.oreilly.com この記事の目次 「Docs for Developers」はどんな本なのか 全般的な感想 各章に関する覚え書き Front Matter Chap 1. Understanding your audience Chap 2. Planning your documentation Chap 3. Drafting documentation Chap 4. Editing docum
スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ｜Anno Takahiro
ドキュメント文化は健全な組織のスケールのために必要 組織の中でドキュメント/文章を残し活用していくことはとても重要だ。クオリティの高いドキュメントがあることで、組織に情報が流通し、透明性を確保できるようになる。情報を流通させるためにいちいち口頭の説明がいらないから、メンバーの数が増えた時でもスケールしやすくなる。過去の結論にアクセス可能になるので、議論を積み上げていき、意思決定のクオリティを高めることにもつながる。そもそも何かを読むということは何かを聞いて教わるよりも時間あたりの処理量が多いし、非同期に実施できる。良いドキュメントをアセットとして社内に蓄積していくことはスタートアップのみならず、ありとあらゆる組織が成長していく上でとても重要であると言える。 しかしその一方で、良質なドキュメント文化を徹底できている会社は多くないように見える。例えば、社内のドキュメントを蓄積させていく場所とし
目的に沿ったDocumentation as Codeをいかにして実現していくか / PHPerKaigi 2021
https://fortee.jp/phperkaigi-2021/proposal/42ce8b07-6972-42bb-a2ac-96af7249cfa4 あるシステムを理解して開発を開始するとき、必要なのはInfrastructure as Codeを含むソースコードだけでは大抵の場合は不十分です。では挙動がわかるようなテストコードがあれば十分かというとそうでもありません。 いわゆる「オンボーディングの効果的な運用」「開発開始までのオーバヘッドの削減（PHPerKaigi2020で発表）」は継続的な生産性向上のためには考えなければならない要素です。 そして、上記を補完するためにしばしばドキュメントが書かれます。 私はドキュメント運用のアプローチとして「コードによる生成を含んだドキュメント運用」に興味を持っています。 私はこれを「Documentation as Code」と呼んでいま
Kubernetes 専門家として知るべき 47 のこと - 誰かの役に立てばいいブログ
この記事は私が過去 3 年ほど Kubernetes に携わる中で学んだ、ちょっと見つけにくい知識をまとめたものです。 特にカスタムコントローラーを開発するような人に必要となる知識群です。 感想とか指摘とかあれば Twitter までお寄せください。 更新履歴 2021-03-05: "コンテナの resources.limits と resources.requests の違いについて" の項を補足しました (thanks to @superbrothers) API コントローラー実装 プログラムと連携動作 資源管理 ネットワーク モニタリング アクセスコントロール API kube-apiserver が備える拡張機構を列挙しなさい 回答例 Custom resources: OpenAPI スキーマで独自のリソース型を追加できる Aggregation layer: kube-ap
TypeScript Deep Dive 日本語版 | TypeScript Deep Dive 日本語版
出典: https://www.npmtrends.com/typescript TypeScriptはJavaScriptを拡張して作られたプログラミング言語です。トレンドが示すとおり、TypeScriptはJavaScriptに代わって第一に選択される言語になりました。TypeScriptが提供する静的型システムは、コードの保守性と可読性を大幅に向上させます。またブラウザ等の互換性を心配することなく、モダンで便利なJavaScriptの機能を利用できます。 TypeScript DeepDiveは初心者からベテランまで役立つオープンソースのドキュメントです。JavaScriptのモダンな機能からTypeScriptの様々な魔法に至るまで丁寧に説明されています。多くのコードサンプルがあり、具体的なTypeScriptの使い方を簡単に理解できます。TypeScript DeepDive日本
ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ - Qiita
システム開発にドキュメントは欠かせません。ドキュメントが得意になれば活躍の幅が大いに広がりますよね。 この記事では、まず冒頭でドキュメントの作成に求められると思うことを整理した上で、そのスキル獲得に役立つと思われる記事や書籍を集めてみました。もちろん他にもあると思うので、もしお薦めのものがあれば是非コメントで教えて下さい 更新履歴 ・2021/04/16：文章術系にリンクを追加しました。 ・2020/11/28：文章術系にリンクを追加しました。 ・2020/07/24：文章術系にリンクを追加しました。 ・2020/05/24：文章術系にリンクを追加しました。 ・2020/05/14：スライドデザイン系にリンクを追加しました。 ・2020/04/29：スライドデザイン系にリンクを追加しました。 ・2020/04/17：文章術系にリンクを追加しました。 ・2020/04/12：関連するTwit
プロダクトのドキュメントにプルリクエストを送れる仕組みがすごい - Qiita
これ↓なんですけど、意外と RT や Like が付いてたので、ちゃんと書きますね。 しっかしMicrosoftのドキュメントシステム良く出来てるなー。右のEditボタン押すとGitHubが開いてすぐPR送れる。あちらでマージされれば即サイトに反映される。Contiributorsに自分のアイコンが増えた♪ これはフィードバックするのに「面倒」は理由にできないですぞ。https://t.co/9KhAwhV5PP pic.twitter.com/r46zFUvkEp — あめいぱわーにおまかせろ! (@amay077) 2018年6月12日 このツイは Microsoft の製品やサービスのドキュメントについてなんですが、 Microsoft Docs というポータルがありまして、同社のサービスの多くはここでドキュメント公開されている模様です。 ここで公開されているドキュメント群は、バック
無効なURLです
無効なURLです。 プログラム設定の反映待ちである可能性があります。 しばらく時間をおいて再度アクセスをお試しください。
わかりやすいドキュメントを書くには 〜 全体像を把握できることが重要 - Qiita
はじめに エンジニアなら誰でもたくさんのドキュメントを読むことになります。 その中にはわかりにくいドキュメントも少なからずあると思います。 自分はわかりにくいドキュメントは「全体像が掴みにくい」ことが多いと感じています。 そこで、ここではわかりやすいドキュメントを書くための方法を「全体像を把握できるようにする」という視点でまとめてみました。 また、最後に具体例としてQiita APIドキュメントでわかりにくい点の指摘と改善をしてみました。 ここで扱うドキュメントの種類 ここでは仕様書やリファレンスマニュアルといった類のドキュメントを想定しています。 Qiitaの投稿やブログの記事といったものでも共通する部分は多いのですが、これらには他にも重要な要素があると思うので、ここでは扱いません。 わかりにくいドキュメント=全体像が掴めないものが多い 先ず、わかりにくいドキュメントとはどんなものでしょ
ドキュメントの継続的な開発方法 | IIJ Engineers Blog
私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント
Read the Docs(Sphinx)でオープンソースのドキュメントをいい感じに書いてみる
B! 138 0 0 0 最近良くGitHubなんかで公開されてるオープンソースのドキュメントを見ようとすると こんな感じの似たようなフォーマットで書かれているものが多くなっています。 余りに多いので最初GitHubのサービスかな、とか思ったんですが、 これはまた別のRead the Docsという ドキュメント用ホスティングサービスによるものでした。 Read the Docs Read the Docsでドキュメントを公開してみる Sphinxのインストール レポジトリ側の準備 Read the Docsへの登録 ページを作成 Indexページ ページ内容の編集(Markdown to reStructuredText) タイトル ハイパーリンク 画像 リンク付き画像 インラインマークアップ コードブロック リスト テーブル Pythonのモジュール説明 その他reStructured
Sequel READMEの日本語訳というかみじんこ訳 - 岡山県北でがんばるフリーエンジニアのメモ
ruby, sequel※これは Sequel 2.X のものです。最新のSequelでは一部機能がプラグインに切り出されているなど、非互換の部分があります。ご注意下さい。 Sequelを使ってみようかと思いました。 でも、日本語のまとまった情報が見つからないよ(´・ω・｀) 仕方ないので公式を読むことに。 英語が超苦手（中学英語ですでにわかりません。）なので、こんな感じかな？という適当訳。参考にはならないと思う。 少しずつ進めていってます。まだ半分以上残ってます。2008.12.1 ようやくできました。 関連： SequelでMigration http://sequel.rubyforge.org/rdoc/files/README.html Sequel（しーくうぇる）とはRubyのための、軽量なデータベースアクセスライブラリ。スレッドセーフコネクションプーリングクエリとスキームのた
MongoDBの薄い本
2.6対応版 MongoDBの薄い本 The Little MongoDB Book Karl Seguin 著 / 濱野 司 訳 i 目次 目次 i この本について iii ライセンス . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii 著者について . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii 謝辞 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii 最新バージョン . . . . . . . . . . . . . . . . . .
Effective JavaScriptをPDFにしました - renoivのブログ
[twitter:@bleis]さんのつぶやきを見て，ここにあったのか！という驚きでした。 2003年頃の記事ですがJavaScript 1.5 (Mozilla 1) ベースなので，まだ参考になると思います。 Googleドキュメントに置きましたので必要な方はどうぞ！ Effective JavaScript - Dynamic Scripting.pdf Powered by Google ドキュメント HTMLアーカイブもGithubに置きましたので，こちらも必要な方はどうぞ。 https://github.com/renoiv/EffectiveJavaScript 参考 Effective JavaScript - Dynamic Scripting Wikipedia JavaScript バージョンとブラウザの対応表
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
TechCrunch
free-programming-books/free-programming-books-ja.md at master · abdelhai/free-programming-books
gr.jp