第8回Web System Architecture研究会に参加して「システムの変化に追従可能でかつ理解し易いドキュメントシステムのモデル化」について発表した #wsa研 - Copy/Cut/Paste/Hatena
wsa.connpass.com オンライン開催に参加してきました。 予稿 github.com 発表資料 システムの変化に追従可能でかつ理解し易いドキュメントシステム 発表内容はドキュメントシステム（ドキュメンテーションツール）についてです。 私は、システムを理解するためにかかる時間（いわゆる「オンボーディングまでのコスト」。私は「開発開始までのオーバーヘッド」と呼んでいます）をいかに継続的に削減できるかに興味をもっています。 それはなぜかというと「私がシステムの理解のセンスがないからそれをなんとか技術で解決したい」という個人的欲求に他ならないのですが、「まあオンボーディングのコストが小さくなればそれはエンジニア全員にも良いことだろうな」と勝手に思い込んでいろいろ作ったりしています。 実は今回の発表にいたるまでには過程があって、July Tech Festa 2021 winter では
ドキュメントを書くときの「メンタルモデルの原則」 - クックパッド開発者ブログ
こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼
Crowi - MarkdownとWikiを組み合わせた組織用コミュニケーションツール MOONGIFT
メモというのは大事なもので、蓄積されたメモは後々大きな意味をもってきます。そのためにも手軽に、かつ一カ所にまとめて書けるようになっていなければなりません。散在したメモは探すコストが大きく、役に立ちません。 会社であればメモはみんな一カ所に書きためるべきです。それによって知らなかった新しい知識に辿り着けます。それを可能にするのがCrowiです。 Crowiの使い方 まずログインします。 こちらがメモの画面で、ビューワーにあたります。 こちらはプロフィール画面。この画面も編集できます。 右上のアイコンをクリックすると新しいメモが作成できます。 編集画面です。Markdownを使います。画像のアップロードはドラッグ&ドロップでできます。 自動的にURLが変わって、プレビューも更新されます。 更新履歴も表示できます。 Crowiはグループで利用できるWikiエンジンで、ブラケット名も利用できます。
開発のドキュメントをどこに置くか問題 - $shibayu36->blog;
最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば 開発環境セットアップ方法 ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた) サービス内の特定の機能の仕組み 内部用HTTP APIドキュメント などを指している。 結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う あといろいろ悩んでるので事例あったら教えてください。 起きている問題 ドキュメントは
iodocsで便利なREST APIドキュメントを作成する - Qiita
wikiとかでドキュメントを書くのが面倒で、良いツールを探していたらiodocsというnode製ツールを見つけた。 これを使うとドキュメント作成が楽になるだけじゃなく、 ドキュメント上のformからAPIリクエストを試せて便利っぽい。 普段APIドキュメントを見つつcurlとかでリクエスト送信して試してたのが、全てドキュメント上で完結して良さげ。 使い方 mashery/iodocsからcloneしてアプリを起動すると、FoursquareやLinkedin APIを叩くサンプルをすぐに試せる。redisが必要なのでserver起動を忘れずに。 ~/ $ git clone http://github.com/mashery/iodocs.git ~/iodocs $ npm install ~/iodocs $ redis-server & ~/iodocs $ npm start {
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
