第7回 技術を伝えるドキュメンテーション術 | gihyo.jp
本コーナーでは技術へのタッチポイントを増やすことを目標に、各分野で活躍されている方をお迎えします。 今回はテクニカルライティングをテーマに堀越さんにインタビューします。書く技術の一端に触れて仕事や趣味に活かしてみませんか。 【話し手】 堀越 良子（HORIKOSHI Yoshiko）LINE ではたらくテクニカルライター。技術書典で『DNS をはじめよう』などのインフラ入門書を執筆。ねこが好き。 Twitter @mochikoAsTech GitHub mochikoAsTech URL https://mochikoastech.booth.pm/ 書く仕事 日高： 今のドキュメントを書くお仕事とは、どのように出会ったのでしょうか。 堀越： 私のキャリアはPHPエンジニアから始まっています。そのあと広報をやって、今の仕事の前はインフラエンジニアを7年ほどしていました。当時、仕事をしなが
[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita
下記ドキュメントバージョンに関する注意点です。 バージョン番号のルールを定める：バージョン番号は、どのようにつけるかルールを定め、チーム全員が同じ理解で使用するようにする必要があります。たとえば、変更内容によって数字がどのように増えるか（major, minor, patch）、何桁で表現するかなど、具体的に決めておくことが重要です。 変更履歴を明確にする：どのような変更があったのか、それがどのバージョンで実施されたのかを明確にすることが必要です。これにより、何らかの問題が発生した場合に、どのバージョンから問題があるのか特定することができます。 ドキュメントの保存場所を一元化する：ドキュメントのバージョン管理には、ドキュメントを保存する場所を一元化することが重要です。それにより、異なるバージョンのドキュメントが、複数の場所に分散してしまい、誤ったバージョンが使用されることを防ぐことができま
![[Doc] 要件定義書テンプレート・要件定義書の書き方 - Qiita](https://cdn-ak-scissors.b.st-hatena.com/image/square/d7d131e38e26f54466aece3306435a4c09990de8/height=288;version=1;width=512/https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fcdn.qiita.com%252Fassets%252Fpublic%252Farticle-ogp-background-412672c5f0600ab9a64263b751f1bc81.png%3Fixlib%3Drb-4.0.0%26w%3D1200%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZ3PTk3MiZoPTM3OCZ0eHQ9JTVCRG9jJTVEJTIwJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgzJTg2JUUzJTgzJUIzJUUzJTgzJTk3JUUzJTgzJUFDJUUzJTgzJUJDJUUzJTgzJTg4JUUzJTgzJUJCJUU4JUE2JTgxJUU0JUJCJUI2JUU1JUFFJTlBJUU3JUJFJUE5JUU2JTlCJUI4JUUzJTgxJUFFJUU2JTlCJUI4JUUzJTgxJThEJUU2JTk2JUI5JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnR4dC1jb2xvcj0lMjMyMTIxMjEmdHh0LWZvbnQ9SGlyYWdpbm8lMjBTYW5zJTIwVzYmdHh0LXNpemU9NTYmcz01MjE0ZDhhMTY1ZjE1ODIxNGE5NzU4Njc3MTNjOTBmNg%26mark-x%3D142%26mark-y%3D57%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjAuMCZoPTc2Jnc9NzcwJnR4dD0lNDBzeWFudGllbiZ0eHQtY29sb3I9JTIzMjEyMTIxJnR4dC1mb250PUhpcmFnaW5vJTIwU2FucyUyMFc2JnR4dC1zaXplPTM2JnR4dC1hbGlnbj1sZWZ0JTJDdG9wJnM9MTc4MmM0MTlmNzhiYTJjNTk0ODYwZmExZDc0OWYzNjQ%26blend-x%3D142%26blend-y%3D486%26blend-mode%3Dnormal%26s%3Db088349e276a1ebcdb9dcf1e2d753094)
技術文書の書き方
howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
GitHub - hackergrrl/art-of-readme: :love_letter: Things I've learned about writing good READMEs.
The Node ecosystem is powered by its modules. npm is the magic that makes it all go. In the course of a week, Node developers evaluate dozens of modules for inclusion in their projects. This is a great deal of power being churned out on a daily basis, ripe for the plucking, just as fast as one can write npm install. Like any ecosystem that is extremely accessible, the quality bar varies. npm does
政府情報システムにおける 脆弱性診断導入ガイドライン
政府情報システムにおける 脆弱性診断導入ガイドライン 2022（令和 4）年 6 月 30 日 デジタル庁 〔標準ガイドライン群ＩＤ〕 DS-221 〔キーワード〕 セキュリティ、脆弱性、脆弱性診断 〔概要〕 政府情報システムの関係者が脆弱性診断を効果的に導入するための基準及 びガイダンスを提供する。 改定履歴 改定年月日 改定箇所 改定内容 2022年6月30日 - 初版決定 1 目次 １ はじめに ......................................................... 2 １.１ 目的とスコープ .............................................. 2 １.２ 適用対象 .................................................... 3 １.３ 位置づけ ...
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
わかりやすいシステム構成図の書き方 - Qiita
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
結局UMLとかシーケンス図とかAWSの図とかどれで描くと良いのよ？と思ったときの選択肢 - Qiita
自身のプライオリティによりますが、いくつか。 Markdownで幅広く再利用性を利かせたい、長期的に丁寧に版管理したい 自分自身の操作性、描きやすさと、見た目 俄然手軽に、短期的に、Onlineでいつでもどこでも いずれかという視点で考えると良いのかなと思い、並べてみました。 1. 長期的に: Markdownで幅広く再利用性を利かせたい、丁寧に版管理したいなら Markdownで描くことのメリットは再利用性。 将来的に追記・編集、自分以外の誰かが手を入れる可能性が高い。 現在のドキュメントだけでなく多種説明資料、媒体に転用する可能性がある。 ...という点で差分管理をしたいなら、以下。 VSCodeでPlantUML、Mermaid 上記参考で以下。 Alt+D でプレビュー起動。 Ctrl + Shift + P でコマンドパレットを起動し、出力。 png, svg, eps, pdf
1200人以上の全社員がリモートワーク。GitLabが公開する「リモートワークマニフェスト」は何を教えているか？
1200人以上の全社員がリモートワーク。GitLabが公開する「リモートワークマニフェスト」は何を教えているか？ 新型コロナウイルスの影響などでいま、多くの企業がリモートワークの導入を進めており、それによって多くのビジネスマンもリモートワークへの興味を高めているところでしょう。リモートワークは従来の働き方とどう違うのか、リモートワークにおいて組織として生産性を高めるにはどうすればよいのでしょうか。 そのリモートワークを徹底的に突き詰め、そのノウハウを惜しげもなく公開している企業があります。GitLab inc.です。 社員全員がリモートワークで、今年11月には株式公開を予定 同名のソースコードの管理サービス「GitLab」を提供する同社は特定のオフィスを持たず、1200人以上いる全社員がリモートワークで働いています。 タヌキをアイコンとする同社は2011年に創業者の個人プロジェクトとしてス
リモートアジャイル開発のノウハウ集 第2版を公開しました | Agile Studio
Agile Studio プロデューサーの木下です。2020年の3月に公開した『リモートアジャイル開発のノウハウ集（第1版）』に続き、このたび第2版を公開しました。こちらからダウンロードいただけます。...
ついに、Webアプリでの帳票印刷のベストプラクティスを編み出しました
この記事で紹介した手順をライブラリ化して公開しました🎉 こちらの別記事 で使い方など詳しくご紹介していますので、ぜひご参照ください！ はじめに 言い切りタイトルすみません 僕を含む一定数の人にとって現時点でのベストプラクティスとなりうる手法という意味で紹介しています 極めてシビアな帳票出力の世界にいる人から見ると使い物にならない内容かもしれないと思います 帳票印刷の世界では SVF というサービスが有名らしいです。が、こういった外部サービスは使わずに自力で実装するというのがこの記事の前提です 動的に明細行の数が増減する連票はこの記事の解説では考慮していませんが、追加で実装するのはそれほど難しくないということは読んでいただければ分かるかなと思います 結論から 僕が考える現時点でのWebアプリでの帳票印刷のベストプラクティスは、 Adobe XD や Figma で帳票のレイアウトをデザイン
Swaggerを使ったAPIドキュメントの作成と、バックエンドとフロントエンド間の連携
こんにちは。LINE Growth Technology福岡開発室でサーバーサイドエンジニアをしている中村です。 この記事では担当していたプロジェクトで実施した、Swaggerを使ったAPIドキュメントの作成と、BE（バックエンド）とFE（フロントエンド）間の連携について紹介します。 プロジェクトの説明 はじめに、今回LINE Growth Technology福岡開発室（以下「GT」）がシステムの設計開発を担当した、LINE公式アカウント審査ツールのプロジェクトについて説明します。 LINE公式アカウント審査ツールとは、LINE公式アカウントで認証済アカウントが申請された際に、申請内容が適切であるか審査するシステムです。 このシステムは、LINE公式アカウントが利用されている各国に存在する審査パートというチーム（以下「審査チーム」）によって利用され、日本以外の国家も含め、一日あたり平均約
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Qiita
はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a write
GitLab的ドキュメント文化を組織にインストールする（実践編:スタートアップMNTSQの事例）｜Anno Takahiro
会社組織にドキュメント文化をインストールすることの有用性や、GitLabのような企業がどのようにドキュメントを運用しているかを、前回記事で書いた（スケールする組織を支えるドキュメンテーションの技術を”GitLab Handbook”から学ぶ）。今回は、私のいるスタートアップのMNTSQ（モンテスキュー、と読みます）でどのようにそれを実践しているか、実際のところどのような成果が出ているのかについて書いてみたい。 MNTSQでは、当初からドキュメンテーションの重要性を経営メンバー全員で認識しており、社内ドキュメントをGitHub管理でメンテナンスしながら作り上げていくようにしていた。この大枠の仕組みの設計部分は弊社のデザイナーの生谷(@ikutani41)が初期に考案/メンテしたものである。デザイナー視点からこのような仕組みが設計され稼働されることは珍しいと思う。この辺については本人からもどう
フロントエンドエンジニア御用達の MDN web docs を網羅した
このリストは何？ MDN web docs を、あたかも書籍の目次かのごとく整理しなおしたものです。それぞれ MDN web docs の記事へリンクしています。 なぜこれが必要になったかというと、人材市場でフロントエンドエンジニアが少なすぎる現状をどうにかするべく教育体制を整えるところから考え始めたのですが、それならまずは日頃お世話になっている MDN web docs を教材として扱いたいなと思ったからです。慣れてきてもよく参照するし「アレどこだっけなぁ？」を軽減もしやすいかなって。 MDN web docs は内容そのものはかなり充実しているものの、リンクがあらゆる方向に張り巡らせられており ある一定の流れに沿って読む ということが少々難しい側面もあります。特に初学者にとっては、迷子になりやすいかもしれません。 ですので、初学者でも学習しやすいように MDN web docs 全体の
Google エンジニアリング・プラクティス ドキュメント
Google エンジニアリング・プラクティス ドキュメント このページは、Google Engineering Practices Documentation の非公式な日本語翻訳です。元のドキュメントは、クリエイティブ・コモンズの「CC-By 3.0」ライセンスで公開されています。 Google には、あらゆる言語・あらゆるプロジェクトをカバーする一般化されたエンジニアリング・プラクティスが数多く存在します。こうしたドキュメントは、私たちが長年に渡って開発してきたさまざまなベストプラクティスの経験が集結したものとなっています。オープンソース・プロジェクトやその他の組織でも、こうした知識から恩恵を受けられるかもしれません。そのため、私たちは可能な限り、この知識を公開するように努めています。 現在、以下のドキュメントが公開されています。 Google コードレビューガイドライン (Googl
Vue.jsとNuxt.jsを使っていて、どっちのドキュメントを見ればいいんだ？ってなったときのために機能を整理する。
Vue.jsとNuxt.jsを使っていて、どっちのドキュメントを見ればいいんだ？ってなったときのために機能を整理する。 開発に慣れてきたら迷うことはないと思いますが、Vue.jsをさわるのが初めてでNuxt.jsを採用した場合、どっちのドキュメントを見ればよいかわからずに、さまよってしまう事があるかもしれません（自分がそうでした）。そんなときのための、長ったらしいメモです。 この記事を書いている時点では、Vue.jsが2.5、Nuxt.jsが1.2です。 ドキュメントの歩き方 まずはガイドで概要を把握して、細かいことが気になったらAPIをあたります。 Vue.jsでの開発がはじめてであれば、本格的に書き始める前に、スタイルガイドを見ておくと、手戻りが少なくなるかもしれません。 ガイド フレームワークの使い方がわかりやすく書かれています。 はじめにから順に読んでいって、大体こんなことができる
ベイジのweb制作ワークフロー2018（140のタスクと解説） | ベイジの社長ブログ
ベイジで社内のワークフローを整理しだしたのは確か2014年頃です。その頃はまだ4～5人しか社員がいない状態で、タスクの粒度も粗く、いくつかのタスクは各人の能力に委ねたものでした。しかし10人を超えて関わる人が増えたあたりから、仕事の進め方も徐々に変わり、ワークフローの綻びも色々と出始めてきました。そこで今年の春に、全社員参加のもと、これまでの進め方の問題点を話し合ったうえで、ワークフローの大幅な刷新を行いました。本エントリーはそのご紹介です。 刷新にあたって、受注から納品までをサブタスクを含めて約140に分解しました。また、各タスクで用いられるドキュメントもできるだけフォーマット化し、効率よくドキュメントワークができるようにしました。 合わせて、タスク毎の職能の再定義を行いました。プロデューサー、ディレクターといった業務範囲が曖昧な職能は、より厳密な職能の定義を試みました。例えばディレクタ
Docker ドキュメント日本語化プロジェクト — Docker-docs-ja 24.0 ドキュメント
注意 このサイトは Docker 公式ドキュメントを有志で日本語に翻訳しています。各ページの情報が古い可能性があるため、最新のドキュメントは https://docs.docker.com/ をご覧ください。 DISCLAIMER: This site is translating the official Docker documentation into Japanese by volunteers. As the information on each page may be outdated, please refer to the latest documentation at https://docs.docker.com/ . 注意 Docker v24.0.x (current) 向けにドキュメントの改訂作業中です(2023年7月現在)。一部古い場合がありますので、ご注意く
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
C++ 標準ライブラリ - C++ の歩き方 | cppmap