documentationjs + add-text-to-markdownでREADME.mdのAPIリファレンスを自動更新 documentationjsはJSDocからドキュメントを生成できるツールで、ES2015以降のコードにも対応しています。 (TypeScriptは対応してないようです) 以前はMarkdownへの出力が難しかったのですが、いつのまにかdocumentation build -f mdでMarkdownでのAPIドキュメントが生成できるようになっていました。 これを使うことで、ライブラリを書いてそのJSDocからドキュメントを生成して、READMEのUsageセキュクションを自動的に更新できるようになっています。 以前もできたのですが、かなりトリッキーなテーマを書いたりしないといけませんでした。(後stdoutへの出力がなかった気がします) –theme for

Alminでは元々GitBookを使ったドキュメントサイトをhttps://almin.js.org/で公開していました。 最近、OSS向けのドキュメントサイト作成ツールであるDocusaurusが公開されたのを受けて、GitBookからDocusaurusに移行しました。 Alminのサイト: Almin · Flux/CQRS patterns for JavaScript application. https://github.com/almin/almin DocusaurusはEasy to Maintain Open Source Documentation WebsitesとあるようにOSSのライブラリやプロダクト向けのドキュメントサイトを作る一種の静的サイトジェネレーターです。 Facebookから公開されていることからも分かるように、JestやPrettier(Faceb

こんにちは。Akerunエンジニアの @ishturk です。 Akerun Advent Calendarの記事です。 今日は設計書の話です。 設計書をどんなツールで書くかは、僕らソフトウェアエンジニアの尽きない悩み（楽しみ）ですね。 最近はまったツールが最高に良かったので紹介させてください。 僕のツールに求める要件は以下です。 編集がカジュアルにできる UMLが書ける。あとから編集できる（画像での貼付けは編集できないのでNG） バージョンの管理ができる 好きになれる（重要） 変遷と pros/cons MS Word pros 良くも悪くもスタンダードなツールですね。 だれでも編集できるのが強みです。 Visioと組み合わせれば、UMLも後から編集可能です cons Visioは標準にするには少々値が張ります。 バイナリ形式なのでバージョン管理はしづらいです。 ページが増えたり画像を貼

Documentation Driven Contractsについて調べてみた May 15, 2017 ( May 15, 2017 更新 ) モチベーション 最近業務で、社内の他のチームに提供するAPIを開発している。 関わっている人が少なければ、みんなで近くに座って都度仕様について相談していけばいい。（感覚的には〜7人くらい？） しかし、会社全体の人数が多く、関わるチームも複数いるため（サービスのモバイルアプリ担当、Webフロント担当、バックエンド担当…など）包括的で都度更新されるドキュメントがないと開発効率が悪い。 とはいえ、API提供チームとしては、実装になるべく多くの時間を使いたい。具体的には以下の条件を満たす手法があればよい: ドキュメント作成にかける時間を短くできる 作成したドキュメントの内容が正確（最新であることが必須） 一番原始的な手法として、ドキュメントをちまちま人手

社内の事業部・プロジェクトを跨いで、社員間で技術やノウハウの共有をもっともっと盛んにしたいーそんな社員の声から生まれ、社内で運用中のツールをこの度 OSS にして公開しました。 公開先 GitHub 上に公開しています。 atware/sharedocs README にデモサイトや Heroku ボタンを記載していますので、すぐに試すこともできます。 Sharedocs Markdown で記事が投稿でき、コメントや Like やストックができる、言ってしまうとどこかで聞いたことがある某有名サービスのような情報共有ツールです。 投稿画面 絵文字も入力できますし、さらにはシーケンス図やフローチャートも Markdown で描けます。 レスポンシブにしてあるのでスマホやタブレットでも使えます。 つくるに至った背景など 背景 弊社には以前から、 他のプロジェクトでどんな技術が使われているのかよ

デザイナーの大嶋です。 マネーフォワードでは、普段のコミュニケーションに esa.io を活用しています。 使い方は日報、起案、調査資料など多岐に渡ります。 しかし、200人を超えるメンバーが記事を日々投稿していると、カテゴリーが無作為に作られたり、記事分類の粒度がバラついたり… このカオス状態を解消しようと、年末という気分も相まって esa カテゴリー大掃除を行いました。 既に3万件以上と膨大な数に膨れ上がった記事を、一気に整理整頓するのは大仕事になってしまいます。 そこで、手始めに自分の所属する「デザイン戦略室」の記事に対象範囲を絞って取り掛かることにしました。 (これなら、数百件レベル！) 最初の一歩は「箱（カテゴリー）」を決めること 「 esa 、整理してくださーい！ 」 と安易に呼びかけてしまうと、各自の「使い方ルール」「分類ルール」「想い」の違いから更なる混乱を生みそうだったの

この記事は CureApp Advent Calendar 2016 18日目の記事です。 今日はドメインモデルのドキュメンテーションの話です。 さて、DDD を実践していくと、成果物としてドメインモデルの定義が上がってきます。最終的には、それをソースコードに落とし込むというのが、DDD の目標ですが、その前に一旦、これこれのドメインモデルが定義された、ということを記録する必要が必ず生じます。 その定義をどうやって保存するかというのはチームによってまちまちなのではないかと思いますが、自分の経験上、どこにどういう形でドメインモデルのドキュメントを残すかはわりと意見が分かれるトピックです。 自分が今までやってきた手段としては、wiki (コンフルーエンス) に残す、Google スプレッドシートに残す、ホワイトボードに手書きしたものを写真でとるなどの手法をやってきましたが、どれも一長一短でした

このエントリは、パッケージソフトウェア開発 Advent Calendar 2014 の 7 日目の記事です。 はじめに 普段、仕事でパッケージソフトウェアを作っています。 具体的には、DataSpider Servista という EAI（Enterprise Application Integration）で、ざっくり数十万～数百万円くらいする、企業向けのソフトウェアです。 パッケージソフトウェアの開発 パッケージソフトウェアの開発というのは、既存ユーザや（特に企業向けソフトの場合）見込みユーザの要望を適宜取り入れながら進めます。 多くのユーザに使ってもらうパッケージなので、単に特定のユーザの要望を満たすだけではだめで、製品の戦略や設計思想、また互換性にも配慮しつつ、仕様を考える必要があります。 使いやすさ、UI/UX のよさというものも忘れるわけにはいきません。*1 Design D

Amazon Aurora バージョンアップについて、改めて理解する ～バージョンアップ手法と文字コードへの影響～

こんにちは丸山@h13i32maruです。 昨日、東京Node学園祭2015というNode.jsについての国内最大のイベントがありました。参加人数は400人くらいで、海外からも有名なゲスト招いており、2トラック同時並行で行われるというイベントでした。運営のみなさん本当にお疲れ様でした。非常に楽しかったです。イベントの内容全般については以下のリンクを見ると良いかと思います。 東京Node学園祭2015を開催します 東京Node学園祭2015で技術文書をソフトウェア開発する話をしてきた 東京node学園祭に関連する18件のまとめ - Togetterまとめ そこで僕も「ESDoc - ES6時代のドキュメンテーションツール -」というタイトルでESDocというES6(ECMAScript2015)向けのドキュメンテーションツールについて発表してきました。 ES6時代のAPIドキュメンテーション

昨日、textlint 4.0をリリースしましたが、textlintはMarkdownなどの文章に対してルールベースでチェックできるツールです。 詳しくは以下の記事を参照してください。 textlintで日本語の文章をチェックする | Web Scratch textlint + prhで表記ゆれを検出する | Web Scratch 今すぐ電子書籍(技術書)を書き始める方法と文章の自動チェック | Web Scratch textlint-rule-preset-jtf-style textlintのプリセット(ルールセット)としてtextlint-rule-preset-jtf-styleを作成しました。 これへ日本翻訳連盟のJTF日本語標準スタイルガイド（翻訳用）をtextlintのルールとして実装したものです。 『JTF日本語標準スタイルガイド（翻訳用）』は、実務翻訳において和訳時

proofread-helper proofread-helperは@vvakameさんが作っている文章の校正補助ツールです。(TechBoosterとかの執筆で使っている?らしいです) 機能としては表記ゆれの辞書を指定して、そのルールに則って文章のチェック、また期待する単語への書き換えを行うことができます。 ものすごくざっくり書くと、期待する単語と表記ゆれを補足する正規表現の組み合わせを持った辞書を作ってチェックするような形です。 仕組み的にはazu/technical-word-rulesと殆ど同じですが、辞書をyaml形式で書けたり、辞書内に期待通りに動いているのかの簡単なテストも書くことができます。 なので、辞書の追加や管理がしやすいと思います。 例えば、以下のように辞書を書くことができます。 version: 1 rules: # expectedのみだと 大文字小文字全角半角の

コード中にコメントを書くべきでしょうか？　是が非でも避けるべきでしょうか？　それとも控えめに書けばいいでしょうか？　開発者たちはそれぞれ、ソフトウェアを開発する際にどのように、そしてどんな時にコメントを書くかについて、独自の考え方を持っています。この記事では私の意見を述べますが、これが誰にも当てはまるというわけではありません。 なお、関数型プログラミングまたはオブジェクト指向プログラミングの原則に則ってJavaScriptで書かれたソフトウェアに絞った上で、私の意見を述べることにします。 コメントと保守性 この記事では、保守性のあるコードを書く場合について考えます。つまり、以下のようなコードです。 簡単に理解できる 簡単に拡張できる 簡単にデバッグできる 簡単にテストできる 保守性のあるコードには、大量のコメントが必要でしょうか？　明確に書かれたコードであるならば、大量のコメントは不要だと

JSDoc で API ドキュメントを生成する方法と、一部のドキュメンテーションタグの使い方についてメモする。 環境 OS Windows7 64bit Java 1.7.0_51 JSDoc 3.2.2 インストール Java Mozilla Rhino を使った方法でドキュメントを生成するので、 Java が必要。 インストール方法は割愛。 JSDoc 3 GitHub からダウンロードできる。 tags から v3.2.2 を選択して、 zip でダウンロードする。 zip を解凍したら、解凍後のフォルダにパスを通し、コマンドラインからヘルプを表示できることを確認する。 >jsdoc --help OPTIONS: -t, --template <value> The path to the template to use. Default: path/to/jsdoc/templa

MOONGIFTはオープンソース・ソフトウェアを紹介するブログです。2021年07月16日で更新停止しました プロジェクトのドキュメントをどう記述し、どう管理するかは重要な問題です。やってはいけないのは一つのドキュメントにまとめて管理することです。大きな文書は修正しづらく、全体が密に連携するので一つの修正が他に及ぼす影響が分かりづらくなります。 文書はなるべく疎結合に、分割して管理されるべきです。しかもMarkdownフォーマットであればテキストファイルなので更新も検索も用意です。ということでMkDocsを紹介します。 MkDocsの使い方 MkDocsのインストールはpipで行います。 $ pip install mkdocs まずはヘルプを出してみます。 $ mkdocs help MkDocs (version 0.12.2) mkdocs [help|new|build|serve

３行で言うと herokuが作ってる prmd を使って、JSON SchemaからAPIドキュメントを出力したよ！ スキーマ定義から、GoのAPI実装コードも出力するツールを作ったらめっちゃ捗るよ！ Goのバリデーション用のライブラリも作ったよ！ 今回作ったものの概要とサンプルコード 概要 以前から、APIを開発する上で、以下のようなことが課題となっていました。 そもそもドキュメント書くのがつらい それもあって、ドキュメントより先にコードが変わってしまう ドキュメントと実装の状況の違いが把握しづらい また、ロジックがそんなに複雑ではないAPIでは、実装の作業は リクエストデータのバリデーション 出力データの整形 (フィルタリング) の２つの作業が大きな割合を占めます。 APIの定義ファイルからドキュメントと、バリデーションや出力データ整形のコードを自動生成できれば、大幅に効率が上がると思

最近APIのバリデーションを行うのにJSON Schemaを使おうという話をよく聞くのですが じゃあやってみようとすると、単体のJSONのバリデーションを行うことは出来るけれど それが実際の運用に適用できるようにするためには、 それなりに考えなくてはいけないようです。 JSON Schemaって? JSON Schemaは、文字の通りJSONのスキーマ定義を明確にするものです。 2014/09/07現在、IETFにdraft v4が3つに分割されて公開されています。 JSON Schema Core JSON Schema Validation JSON Hyper-Schema それで、単体のJSONファイルの確認ならばCoreだけで十分なのですが WebサービスのAPIを管理しようとなると、 JSON Hyper-Schemaのほうで定義されているlinksを使って、ひとつのURIに対

内部用APIであるか外部の開発者向けのAPIであるかに関わらず、ドキュメントと実装との乖離は極力避けたいものであるが、注意深く開発を進めない限りこの状況は容易に起こり得る。何が乖離を引き起こし、どうすればこの状況を回避できるのか考えながら、JSON Schemaの利用例を紹介する。なおこの投稿では、HTTP経由でデータの通信を行うような狭義のAPIのことをAPIと呼ぶことにする。 同じ情報源を参照する APIドキュメントと実装が同じ情報源を参照するようにすれば、論理的に関連した要素は統一的に変更され、これらの変更は完全に同期が取れたものになる。つまり、変更時に乖離が生じにくくなる。但し情報の見せ方によって乖離が発生する可能性は十分にだろうし、乖離が発生するのは理解しようとする側の認識の問題であるから、論理的に全く起こり得ないということではない。 この参照の形には、両者が別の情報源を参照する

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article?