よく知られているように、ドキュメントには「構造」があります。 WebページではHTMLとCSSにより構造とスタイルを分離するべきとか、Wordでは書式設定をスタイルとして定義して使うことで構造とスタイルを分離するべきとか、ドキュメントの「べき」論で必ず言及される「構造とスタイルの分離」における「構造」です。 昨日までの話ではPDFにもドキュメント構造というのが出てきました。あれは、この「構造とスタイルの分離」というときの「構造」とは別物なので注意してください。 たぶん、PDFのドキュメント構造には、「ドキュメントを表すデータ構造」くらいの意味合いくらいしかありません。 一方、ドキュメントの話において「構造とスタイルの分離」というときの「構造」は、もうちょっとこうなんていうか、セマンティックな話です。 データをどう構成するかではなく、ドキュメントで表したい意味をどう構成するか、という話。 し

power-doctest という doctest風 にコードと評価結果のコメントを並べるとテストとして実行出来るようなNode製のツールを作りました。

この記事はMERPAY TECH OPENNESS MONTHの10日目の記事です。 こんにちは、メルペイのバックエンドエンジニアの柴田（@yoshiki_shibata）です。 メルペイのバックエンドは、Google Cloud Platform上でGoogle Kubernetes Engineを使用して、マイクロサービスアーキテクチャを採用した多数のマイクロサービスから構成されています。モノリシックなサービス実装では複数層のライブラリ（あるいはコンポーネント）から構成されるのに対して、マイクロサービスアーキテクチャでは複数層のマイクロサービスから構成されます。 どちらのアーキテクチャにおいても、偶発的プログラミング（Programming by Coincidence）1を避ける2ために、注意を払って作成する必要があるのが、境界部分のAPI（Application Programmi

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに 時の経つのは早いもので、私がIT業界に身を置いて四半世紀になってしまいました。 その間、膨大な数の「設計書（仕様書）」を書いて来ましたが、未だに悩み・迷いは尽きません。 それでも、亀の甲より年の劫とも申しますので、私なりの経験則を「個人」と「チーム」の両観点でまとめてみました。 本稿のテーマは、「主に設計書を想定した、開発ドキュメントの書き方」です。 本稿で前提とする設計書は、ExcelやWordで書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォータ

こんにちは。会員事業部の丸山@h13i32maruです*1。 ソフトウェアのドキュメント(マニュアル)を書くには色々なツールや方法があります。 JavaScriptの場合はJSDocというドキュメンテーションツールがデファクトスタンダードです。 ですが、JavaScriptの最新仕様であるECMAScript2015(ES2015)がリリースされたことにより、 JSDocの競合として新しいツールが登場したり、JSDoc自体もバージョンアップしたりしています。 本記事ではそうした新しいツールの一つであるESDocを紹介します。 ESDocとは？ ESDocとは私が2015年4月から開発を行っている、JavaScript(ES2015)向けの良いドキュメントを作るためのドキュメンテーションツールです。 https://esdoc.org/ https://github.com/esdoc/es

手順書を作りながら、こう考えた。 難解過ぎては伝わらない。妙に凝りすぎては読み辛い。形式に囚われ過ぎては窮屈だ。 とかくに手順書は作りにくい。 あんまり上手く無かったですね。これからも精進していきたいと思います。AWS事業本部のしろたです。 ▲こちらはいらすとやさんの夏目漱石です。本当あそこ何でもあるな。流石に旧札は無かったです。 さて、今回話したい主題はもうお分かりですね？そう、手順書についてです。 初めて就職したIT企業でも手順書を作成する機会はあったのですが、今回また手順書を作成する機会を頂きまして、実際に自身が作った手順書をレビューして頂いて色々と思うところがありました。 今回はそれをゆるりと、自分の中の思考を整理する意味でも纏めていきたいと思います。 手順書の定義から入ってみる まず、手順書とは何でしょうか。初めて行う作業や、誰かから引き継ぐ事になった作業を一人で行う場合には割と

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

「セキュリティ対策はシステム開発で不可欠だが、設計書でうまく表現できている開発現場はまだ少ない」――。 ラックの永井英徳氏（エンタープライズ・セキュリティサービス事業部セキュリティディレクションサービス部長 兼 第一グループ部長）はこう指摘する。よく見られるのが、「クロスサイトスクリプティングの脅威には、Aフレームワークを利用することで対処する」などと、個別の脅威ごとに対策を記述するケースという。しかしこれでは、「システム全体として必要なセキュリティ対策を網羅できているのか判断しにくい」（永井氏）。 とはいえ、機能に関する設計書に、想定しうるあらゆる脅威の内容と対策を書き込むのも問題だ。記述が膨大になり、読みにくい設計書になってしまう。後工程の開発メンバーの作業ミスを招く恐れがある。セキュリティ要件が変わったときの修正作業の負荷も大きい。 このような問題意識のもと、ラックの永井氏は、セキュ

（まず追記） 自分たちで新たに作成する仕様書はMarkdownで記述してGitHubで管理しています。 こんなのも書いたくらいだし、そこは犯していないです。GitHubを中心とした開発プロセス ドキュメント管理 この記事内で言う仕様書とは、「エクセルで作られて共有サーバに置いてあるチーム管理外のファイル」を指します。 こーゆーの、良くあるよね？ 見た瞬間「_2.xlsxってなんだよォ...このパス絶対古いんじゃあねェのー？」って思う感じのやつ。 ついでに仕様書のパスが長くって妙なところで改行入ってるおまけ付き。 こんなの見るとイラっとする！ コピペしづらい そのパスに仕様書が実在するかわからん 実在するとして、開くのが面倒 ある1つの仕様書のパスが1箇所にコメントされていたら、あと数カ所はコメントがあると思う でもちょっと手入れされてたりで数箇所のコメントが同じ場所を指していないことが往々

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

業務でドキュメントを作成するケースは多々ある 例：仕様書・設計書・提案書・メール・障害票．．． ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。 1. 表記がバイト表示・マイクロ秒表示 プログラムが出した数値をありのままに表示するパターン ファイルサイズが100MB, 1GBあろうと、バイト表示にする 桁数が多い数値に、桁区切り（,）を入れない 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？） 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様） 悪い例 No ファイル名 ファイルサイズ(byte) 処理時間(秒)

はじめに 私が仕様書を書くようになったのは30歳を過ぎてからと遅く、仕様書の書き方が分からなくて悩んだことがありました。通常は先輩たちが作成した仕様書等を見て書き方を覚えていくのでしょうが、仕様書も無く直接プログラムを組むような体制の仕事をしていたため、SI系に転職してから苦労したのであった。 仕様書を書く際に、ボタンを「Enterキーを押す」か「クリックする」かで考えて「押下」にすれば両方満たすだろうと、それ以来ずっと使用しています。 押下については、コンピューター雑誌やマニュアル等を読んで憶えていた用語で特に気にも止めていなかったのですが、別ブログの仲間が過去に「ボタン押下？」について書いていたことを思い出し、調べてみることにしました。 調べていくと自分は誤用して使っている気がしますw 押下について 読み方 押下は「おうか」と読みます。ちなみに苗字の押下さん(読方：おしした)は全国でお

This browser is no longer supported. Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support. ASP.NET documentation Learn to use ASP.NET Core to create web apps and services that are fast, secure, cross-platform, and cloud-based. Browse tutorials, sample code, fundamentals, API reference and more.

ReadMe.io 簡単な手順で美しいAPI Documentを生成してくれるサービス。 エディタが良く出来ていて、画面に沿ってインタラクティブにAPI Documentが作れるようになっている。 なお、Y CombinatorやSV Angelなどから投資を受けている。 ReadMe.io - Investors | CrunchBase

はじめに エンジニアなら誰でもたくさんのドキュメントを読むことになります。 その中にはわかりにくいドキュメントも少なからずあると思います。 自分はわかりにくいドキュメントは「全体像が掴みにくい」ことが多いと感じています。 そこで、ここではわかりやすいドキュメントを書くための方法を「全体像を把握できるようにする」という視点でまとめてみました。 また、最後に具体例としてQiita APIドキュメントでわかりにくい点の指摘と改善をしてみました。 ここで扱うドキュメントの種類 ここでは仕様書やリファレンスマニュアルといった類のドキュメントを想定しています。 Qiitaの投稿やブログの記事といったものでも共通する部分は多いのですが、これらには他にも重要な要素があると思うので、ここでは扱いません。 わかりにくいドキュメント=全体像が掴めないものが多い 先ず、わかりにくいドキュメントとはどんなものでしょ

いくつかのオープンソースプロジェクトを公開している筆者からの、読みやすくユーザーにやさしいREADMEを書くためのアドバイス。 この記事は、Rowan Manning氏による「Writing a Friendly README」(2016/3/14)を翻訳したものです。 あなたのプロジェクトのREADMEは、かなり重要です。そこはプロジェクトに初めて来た人が大抵最初に見るであろう場所であり、唯一のドキュメントであることもよくあります。あなたのオープンソースプロジェクトにとってのREADMEは、企業にとってのウェブサイトのようなものです。ウェブサイトはユーザーエクスペリエンスの注目を集めるところですが、READMEがユーザー観点で考えられることはほとんどありません。 この記事では、分かりやすいREADMEを書くために役立ち、開発者(ユーザー)の要求に見合い、開発者がプロジェクトを初めて見たの