ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
API Documentation & Design Tools for Teams | Swagger
API Development forEveryone Simplify your API development with our open-source and professional tools, built to help you and your team efficiently design and document APIs at scale. Find your toolRead the docs Trusted by Empowering API Development Streamline your workflow with unparalleled API specification support Swagger places API specifications such as OpenAPI, AsyncAPI, and JSON Schema at the
設計書には何を書くべきなのか - terurouメモ
設計とは、 要求（やりたいこと）をヒアリングする 要求を要件（何を満たさないといけないのか）に落とし込む 要件を実現するために考えられる手段を洗い出す 手段の検証を行う 検証結果を元に、どの手段を使うかを選定する 選定した手段を合意する（一部要件を満たさない事項がある場合は、代替策や妥協ラインについても合意する） 合意内容を元に、実装や設定に落とし込む をやることである。画面設計や機能設計のように、3-5の検証/選定が薄くなったり曖昧になったりするものはあるが、一般化するとこの流れになる。 設計書には、上記の設計でやってきたことを順番に書いていけばよい。これを文章構成のテンプレに落としていくと、 要求 要件 方式 対応案（いわゆる比較表で書いていくのが楽） 検証結果 選定・合意結果（合意した代替策や妥協ラインについても記載する） 詳細設計（どういう実装にするとか、パラメーターにするとか、細
「正しい」運用手順書を作る /20181106-ssmjp-operation-procedure - Speaker Deck
ssmjp 201811での発表資料です。 まだ、論点整理中(特にレベル3)な所もあるので、中間アウトプットみたいな位置付けです。 ご意見、コメント歓迎です。 「ネオ手順書友の会」(仮称)での議論によりブラッシュアップされました。 ありがとうございました。 (運用設計ラボ合同会社 波田野裕一)
Excel仕様書とGitbook｜Git｜レバノン13日共同
諸君 私はMarkdownが大好きだ (以下略) Fu*k you Excel仕様書な私としては、MarkdownでREADME.mdを書いてGitbookで作った仕様書のプルリクをレビューしてマージする瞬間が至福なわけで、Excel仕様書が世の中から消えてなくなるための礎になれればということで、Qiitaに幾つか記事を書いた (というか、ほぼmermaid.js万歳だけだけど) mermaid.jsが素晴らしいけどなかなか使ってる人見かけないので実例晒す Gitbook 3でmermaid.jsを使う ソースコード管理(git)の説明資料を作るのに gitgraph.js を使ってみた おかげさまで、一本目のmermaid.jsの紹介記事はすごい反響があって、かなりビビった。 実は、大きなお客さん向けのプロジェクトで実際にGitbookで仕様書を書いて開発＆納品までいった約2年分の運用実
gitbookで設計書を作成したら最高だった話 - フォトシンス エンジニアブログ
こんにちは。Akerunエンジニアの @ishturk です。 Akerun Advent Calendarの記事です。 今日は設計書の話です。 設計書をどんなツールで書くかは、僕らソフトウェアエンジニアの尽きない悩み（楽しみ）ですね。 最近はまったツールが最高に良かったので紹介させてください。 僕のツールに求める要件は以下です。 編集がカジュアルにできる UMLが書ける。あとから編集できる（画像での貼付けは編集できないのでNG） バージョンの管理ができる 好きになれる（重要） 変遷と pros/cons MS Word pros 良くも悪くもスタンダードなツールですね。 だれでも編集できるのが強みです。 Visioと組み合わせれば、UMLも後から編集可能です cons Visioは標準にするには少々値が張ります。 バイナリ形式なのでバージョン管理はしづらいです。 ページが増えたり画像を貼
Sphinxのドキュメント作成を便利にする「sphinx-quickstart-plus」を作りました - Qiita
Welcome to the Sphinx 1.5.1 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: document_path You have two options for placing the build directory for Sphinx output. Either, you use a directory "_build" within the root path, or you
Sphinxを便利にして、みんなに使ってもらいたい - Qiita
Sphinxは非常に素晴らしいドキュメント生成ツールです。 この素晴らしいツールを社内で流行らせようと頑張ったのですが、誰も使ってくれません。 みんながどんなタイミングで、Sphinxを諦めてしまうのか振り返ってみました。 reStructuredTextがわからないし、覚えたくもない デフォルトのテーマが見にくいからやめる sphinx-quickstartの設問が多すぎて途中でやめる ドキュメント作成のたびにconf.pyを編集するのが面倒なので使わなくなる ドキュメント確認のたびにmake htmlが面倒なので使わなくなる 最近はJupyterでドキュメント書くので・・・ こんなところでしょうか。 たぶん、Sphinxがいまいち流行らないのも、ここら辺が理由が大きいんじゃないかと思います。 Markdownを使う 残念ながらマークアップ言語の主流はreStructuredTextでは
概要 — Sphinx 1.4.4 ドキュメント
A project Download 現在のバージョン: 1.4.4 Python Package Indexからソースコードをダウロードするか、以下のコマンドでインストールしてください: pip install -U Sphinx 疑問? 意見? Googleグループのsphinx-users グループへの参加 もしくは、FreeNodeの#sphinx-docチャンネルへどうぞ。 何か気づいたことがあれば、issue trackerを使用して報告することもできます。 Sphinxは知的で美しいドキュメントを簡単に作れるようにするツールです。Georg Brandlによって開発され、BSDライセンスのもとで公開されています。 このツールはもともと、新しいPythonのドキュメントの変換のために作られました。Pythonのプロジェクトのためのすばらしい機能を提供してきましたが、現在ではC/
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
Welcome | GitBook Documentation
How to ZFS · GitBook (Legacy)