The Future (and the Past) of the Web is Server Side Rendering When servers were in Swiss basements, all they had to serve was static HTML. Maybe, if you were lucky, you got an image. Now, a webpage can be a full-blown app, pulling in data from multiple sources, doing on the fly manipulations, and allowing an end-user full interactivity. This has greatly improved the utility of the web, but at the
概要 AQに入社して2年目、デジタルエンジニアリング部デジタルエンジニアリング1課の松浦です。 本記事は、私が携わったとある案件で利用していたAPIドキュメントを整備した際の記録です。 APIドキュメントの管理に困っている方の参考になればと思います。 導入経緯 もともとスプレッドシートで管理していたのですが、スプレッドシートの管理だと、差分を見るのが大変だったり、他社に利用してもらいにくいなど不便な点がありました。 またOpenAPIの仕様に合わせた記述をしたいという要望があったため、YAML + OpenAPIでの管理へ移行することとなりました。 導入ライブラリの選定基準 OpenAPIへの記述へ移行するに当たり、YAMLで書いた仕様書を何かしらの方法でレンダリングする必要がありました。候補としては、Redoc、Swagger UIが上がり、当初はSwagger UIを導入する予定だった
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
Markdownで記述できるドキュメント生成ツールを探していたところFacebook製のDocusaurusというツールを知りました。導入して試してみましたので紹介します。 こんにちは。サービスグループの武田です。 Markdownで記述できるドキュメント生成ツールを探していたところDocusaurusというツールを知りました。簡単ですが導入して試してみましたので紹介します。 Docusaurusとは DocusaurusはFacebook製のドキュメント生成ツールで、主にOSSのマニュアルやお知らせなどのブログを管理するために使われているようです。次のような特徴があります。 MarkdownおよびJSXを含んだMDXでコンテンツを作成する 生成したドキュメント（サイト）はReactで動作し、カスタマイズも容易 多言語対応（ローカライズ）も可能 ドキュメントのバージョニングが可能で、プロダ
フィードバックを送信 API 設計ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。 変更履歴 はじめに これは、ネットワーク API の一般的な設計ガイドです。2014 年以来 Google 内部で使用され、Cloud API やその他の Google API を設計するときに Google が従うガイドです。この設計ガイドは、外部のデベロッパーへの情報提供と、互いの連携作業の効率化のためにここで共有されています。 Cloud Endpoints のデベロッパーには、このガイドは、gRPC API を設計するときに特に役立つことがあり、そのような場合にはこれらの設計原則を使用することを強くおすすめします。ただし、このガイドの使用は必須ではありません。Cloud Endpoints と gRPC はガイドに従わなくても使用できます。 このガイドは、gR
【API Blueprintの使い方】Web APIの仕様書を書く・読む・実行する できればドキュメント書きたくないなー。はやくAPI実装したい！俺の頭の中に全部仕様入ってるから！俺が仕様だ！ ... その仕様、API Blueprintでドキュメントにおこしませんか？ はじめに デバイスが多様化し、その違いを吸収する統一的なインターフェースが求められる昨今、Web APIはその回答のひとつといえます。弊社でも、モバイルアプリとWeb APIを組み合わせてサービスを構築することがあります。 Web APIが登場する開発では、モバイルアプリ（APIクライアント）メンバーと、APIサーバメンバーのコミュニケーションが不可欠です。開発を円滑に進めるために、APIの仕様書 が必要になります。お互いがAPIの仕様を想像して勝手に開発を進めたのでは、いざ結合したときに悲惨な結果になることが目に見えてい
API Blueprint. A powerful high-level API description language for web APIs. API Blueprint is simple and accessible to everybody involved in the API lifecycle. Its syntax is concise yet expressive. With API Blueprint you can quickly design and prototype APIs to be created or document and test already deployed mission-critical APIs. Tutorial Tools section Focused on Collaboration API Blueprint is bu
RedPen is a proofreading tool to help writers or programmers who write technical documents or manuals that need to adhere to a writing standard. RedPen automates the verifications of input documents written in natural languages — NOT computer languages such as C++ or Java. RedPen はプログラマや記者が規約にしたがって文書（マニュアルやソフトウェアドキュメント）を記述しているか検査します。 RedPen は自然言語で記述された入力文書のチェックを自動化します。 Customizable 柔軟な設定 RedPen is
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く