wsa.connpass.com オンライン開催に参加してきました。 予稿 github.com 発表資料 システムの変化に追従可能でかつ理解し易いドキュメントシステム 発表内容はドキュメントシステム（ドキュメンテーションツール）についてです。 私は、システムを理解するためにかかる時間（いわゆる「オンボーディングまでのコスト」。私は「開発開始までのオーバーヘッド」と呼んでいます）をいかに継続的に削減できるかに興味をもっています。 それはなぜかというと「私がシステムの理解のセンスがないからそれをなんとか技術で解決したい」という個人的欲求に他ならないのですが、「まあオンボーディングのコストが小さくなればそれはエンジニア全員にも良いことだろうな」と勝手に思い込んでいろいろ作ったりしています。 実は今回の発表にいたるまでには過程があって、July Tech Festa 2021 winter では

こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼

メモというのは大事なもので、蓄積されたメモは後々大きな意味をもってきます。そのためにも手軽に、かつ一カ所にまとめて書けるようになっていなければなりません。散在したメモは探すコストが大きく、役に立ちません。 会社であればメモはみんな一カ所に書きためるべきです。それによって知らなかった新しい知識に辿り着けます。それを可能にするのがCrowiです。 Crowiの使い方 まずログインします。 こちらがメモの画面で、ビューワーにあたります。 こちらはプロフィール画面。この画面も編集できます。 右上のアイコンをクリックすると新しいメモが作成できます。 編集画面です。Markdownを使います。画像のアップロードはドラッグ&ドロップでできます。 自動的にURLが変わって、プレビューも更新されます。 更新履歴も表示できます。 Crowiはグループで利用できるWikiエンジンで、ブラケット名も利用できます。

最近、SRE になった @b4b4r07 です。今回は、直近のタスクだった社内アプリを Kubernetes に載せ替えた話をします。 前置き メルカリでは全社的 1 に Crowi という Markdown で書ける Wiki アプリケーションをナレッジベースとして採用しています。 site.crowi.wiki 以前は、プロダクトチームは Qiita:Team、コーポレート系は Google Sites と言った具合に、各部署ごとに異なるドキュメントツールを使っていました。これではよくないと、エンジニアに限らず誰でも書きやすく参照しやすい Wiki のようなサービスが必要とされ、Crowi の採用に至りました。 まずはみんなに使ってもらうために広めていこうと、試験的に導入が始まったため、今回の移行話までは 1 台の EC2 インスタンスにアプリケーションサーバと Nginx、Mongo

MOONGIFTはオープンソース・ソフトウェアを紹介するブログです。2021年07月16日で更新停止しました Webの印刷機能は貧弱です。そのため多くのレポートはHTMLではなくPDFなどに出力されます。日本の業務システムは特に印刷内容の細かい制御が求められるのではないでしょうか（経済合理性はさておき）。 もっと手軽に印刷指定を行いたい、という方はGutenbergを使ってみましょう。モダンな印刷を実現するためのフレームワークです。 Gutenbergの使い方 元ドキュメント。 こちらが印刷時。装飾も容易です。 Web表示ではコードやテーブルも簡素ですが、Gutenbergでは綺麗に表示されます。Gutenbergでは印刷時に表示するもの、しないものを簡単に指定できたり、改ページの指定も簡単にできます。Gutenbergを一緒に使えば複雑な印刷指定も容易になるでしょう。 Gutenberg

MOONGIFTはオープンソース・ソフトウェアを紹介するブログです。2021年07月16日で更新停止しました 強い組織を作るためにはナレッジの共有が欠かせません。個々人のナレッジに留まっていては同じ経験を繰り返すだけですし、何も培われていきません。問題はどこに書き留めるかです。かつてはWikiもありましたが、慣れないと使いこなせませんでした。 今回紹介するオープンソース・ソフトウェアはSharedocs、プログラマが使い慣れているであろうQiitaクローンです。 Sharedocsの使い方 Sharedocsのトップページです。 ログインしました。カラーリングは違いますが、UIはとてもQiitaに似ています。 新規作成画面です。ここのデザインは結構違います。が、プレビューの機能などはついています。 表示例です。記法はMarkdownが使えます。 ユーザページです。投稿数、ストック数などが確

PaperNICはオンラインでドキュメントを管理出来るオープンソースソフトウェアです。マルチユーザー対応で複数人が管理可能であらゆるドキュメントファイルに対応、互換性を気にせずアップロード出来る、との事です。動作デモを見た感じ、個人的に抱いてたイメージと少し違いましたがこれはこれで需要あるのかな。尚、ライセンスの明記はまだありませんので必要なら問い合わせを。開発も含め、今後に期待したいところです。 PaperNIC

7. APIドキュメントは書くことが多い ● Host ● Path ● HTTPメソッド(GET, POST, PUT, DELETE, ...) ● Request Header, Body ● Query Parameter ● Response Status Code ● Respose Header, Body ● Authrozation, Authentication ● etc...

一昔前、「厚い財布」は、お札をどっさり入れて高級店に出入りする「お金持ち」の象徴だった。貨幣と交換でモノやサービスを買う社会では、お財布の厚みによって受け取れるモノやサービスの量が決定されたからだ。 しかし、クレジットカードや電子マネーが普及して高額の現金を持ち歩く必要性がなくなった現在では、厚い財布は「スマートさに欠ける人」を指す表現になっている。大量の現金を持ち歩くのは不用心だし、クレジットカードやポイントカードなどで財布が膨らんでいると「お得」や「特典」といった言葉に踊らされている人だと思われがちだからだ。 情報システムの納品物となるドキュメントも、かつてはその厚みが数億円ものコストを象徴していた。基幹系システムなら、ドキュメント一式でキャビネットが数段占有されるのが当然のことだった。 しかし、いまや紙のドキュメントはお荷物。更新が大変なのでソースコードと乖離しやすいうえ、同時に複数

はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1

最近開発用のドキュメントをどこに配置するか悩んでて、いくつか試して見てる。今回言っている開発用のドキュメントというのは、コードの触り方も含んだサービスの開発に関するもの。例えば 開発環境セットアップ方法 ページに表示している広告をどのように切り替えたりするか(googleの管理やコードの変更も含めた) サービス内の特定の機能の仕組み 内部用HTTP APIドキュメント などを指している。 結構いろいろ考えるところがあるので、思っていることをまとめてみたい。一応先に結論を言っておくと 基本は実装に一番近いところにコメントとしてドキュメント書くのが良いと思う いろんなパーツが絡みあうような大きな機能の場合、導入部分だけ別の場所に書く 出来るだけrepository内に入れておくと探しやすく、更新しやすいと思う あといろいろ悩んでるので事例あったら教えてください。 起きている問題 ドキュメントは

私たちの実践する「納品のない受託開発」では、担当のエンジニアがお客さまの顧問となって仕事をしていきます。（参考：顧問弁護士や顧問税理士のような「顧問プログラマ」という仕事と働きかた） お客さまと長い関係を結べることが会社にとって安定をもたらし、お客さまにとっても安心してもらえるため、担当するエンジニアも長期的な関係を築くことを目指します。 しかし、そうすると、必ず聞かれるのが「その人がいなくなったら、どうするのか？」という課題です。私たちのビジネスは、プロフェッショナルサービスでもあるので、人に依存すること自体を見直す必要はありません。だからといって、リスクに対して何も手を打たない訳にはいきません。 この記事では、私たちがどうやって個人に依存する問題へのリスクヘッジを行っているか、少し専門的な話になりますが、私たちの取り組みとその背景について書きました。 Lonely / vishwaan

私はソフトウェア開発を主体とするエンジニアで、 クラウドサービスの開発・運用 分散処理技術の検証とサービス利用の検討 社内の開発支援環境の開発・運用 などの業務に従事していますが、今回の記事は業務とは直接的な関係は無く、私が会社で勝手自発的に行っている取り組みについて書きたいと思います。 昨今、インターネットは生活に深く浸透し、クラウドサービスを利用することで安く簡単にWebサービスを開発、公開できるようになりました。Web技術の進化や流行の移り変りも非常に激しく、既存サービスの機能追加や新規サービスの開発は頻繁に行われています。それは弊社も例外ではありません。 このような開発の現場では、リーンソフトウェア開発への取り組みなど開発手法の最適化が積極的に行われ、様々なベストプラクティスが生みだされています。それらのベストプラクティスには、 継続的インテグレーション や 継続的デプロイメント

2016年3月9～15日にかけて開かれた、米Google DeepMindの「AlphaGo（アルファ碁）」と、韓国の李世ドル（イ・セドル）九段による囲碁の五番勝負が興味深かった。アルファ碁が世界トップクラスのプロ棋士に4勝した結果にも驚いたが、それ以上に筆者が興味深かったのはアルファ碁の独特の打ち回しである。 プロ棋士が一目で悪手と判断する定石から外れた手が、後になって実は好手だったと判明する事態がしばしば見られたからだ。攻略のアプローチが全く違うため、人間にとっての前提や制約に影響されず、好手が出るのかなと感じた。 人間は一般に、広大な19路盤を隅・辺・中央と“因数分解”して把握・分析しやすくした上で、石を打つ数が少なくて地（領地）を確保しやすい隅から優先的に攻略する。一方、アルファ碁は盤面を19×19ドットの画像と認識して全体的に捉え、どこに石があると勝ちやすいのかを“直観”している

2023 追記 2023 年現在では、以下の文章では採用を見送っている OpenAPI を使えば OK という雰囲気です。 Web APIの設計 作者:Arnaud Lauret翔泳社Amazon TL; DR ドキュメント生成にはkevinrenskers/raml2htmlを使った ドキュメントはRAML - RESTful API modeling languageで書いた RAMLにはJSON SchemaとJSONを記載できる APIで返ってくるJSONはRailsアプリのrequest specでJSON Schemaを使ってテストした JSON Schemaはr7kamura/json_worldで生成した ドキュメントに載せる例示のJSONもJSON Schemaからgin0606/screijiを使って生成した 上記の方法だとリクエストパラメタとドキュメントの整合性を担保

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 {

Python の docstring というのは、モジュールやクラス、関数などにつける説明文のこと。 単純なコメントとの違いは、より仕様に近い内容を記述しておくことで API のドキュメントとして利用できる他、別のドキュメントから内容を読み込んで使ったりすることができる。 今回は docstring の書かれたサンプルコードを元に、REPL からその内容を参照したり、ドキュメンテーションツール Sphinx でその内容を読み込むというのを試してみる。 docstring の書かれたソースコードを用意する 以下が docstring の書かれた Python のソースコード。 内容については FizzBuzz 問題を題材にしている。 モジュールや関数の先頭で “”“ や ‘’‘ を使ってコメントを書いておくと、それが自動的に docstring として扱われることになる。 #!/usr/bi