ドキュメント技術とプログラミング言語の相似について - golden-luckyの日記
よく知られているように、ドキュメントには「構造」があります。 WebページではHTMLとCSSにより構造とスタイルを分離するべきとか、Wordでは書式設定をスタイルとして定義して使うことで構造とスタイルを分離するべきとか、ドキュメントの「べき」論で必ず言及される「構造とスタイルの分離」における「構造」です。 昨日までの話ではPDFにもドキュメント構造というのが出てきました。あれは、この「構造とスタイルの分離」というときの「構造」とは別物なので注意してください。 たぶん、PDFのドキュメント構造には、「ドキュメントを表すデータ構造」くらいの意味合いくらいしかありません。 一方、ドキュメントの話において「構造とスタイルの分離」というときの「構造」は、もうちょっとこうなんていうか、セマンティックな話です。 データをどう構成するかではなく、ドキュメントで表したい意味をどう構成するか、という話。 し
技術とは・技術者とは・成長とは・倫理とは・結果を出すために重要な考え方......ハートビーツのエンジニアの倫理規定を公開します
こんにちは。CTOの馬場です。 ハートビーツで社内ドキュメントとして策定した「ハートビーツのエンジニアの倫理規定」を公開します。 技術とは・技術者とは・成長とは・倫理とは・結果を出すために重要な考え方といった内容を含んだ、 CTOとしてのわたしからの・わたしたち中堅/ベテランエンジニアから新規参画者へのメッセージでもあります。 ものごとの考え方やとるべき態度など、属人的な事柄を伝達するための取り組みです。 エンジニアや学生のみなさんには、 ハートビーツとハートビーツのエンジニアの雰囲気を知っていただくきっかけとなれば幸いです。 また各社のCTOやVPoEのみなさんとは、お互いに知見を持ち寄り情報交換・議論したいです。 おそらく似たような悩みを抱え様々な取り組みを実施されているかと思いますので、 情報公開や情報交換、議論などを通じてよりよい業界にしていければと思っています。 ダウンロード:
JavaScriptでdoctestを行う power-doctest を作った
power-doctest という doctest風 にコードと評価結果のコメントを並べるとテストとして実行出来るようなNode製のツールを作りました。
gRPCを用いたマイクロサービスのAPI仕様の記述 - Mercari Engineering Blog
この記事はMERPAY TECH OPENNESS MONTHの10日目の記事です。 こんにちは、メルペイのバックエンドエンジニアの柴田（@yoshiki_shibata）です。 メルペイのバックエンドは、Google Cloud Platform上でGoogle Kubernetes Engineを使用して、マイクロサービスアーキテクチャを採用した多数のマイクロサービスから構成されています。モノリシックなサービス実装では複数層のライブラリ（あるいはコンポーネント）から構成されるのに対して、マイクロサービスアーキテクチャでは複数層のマイクロサービスから構成されます。 どちらのアーキテクチャにおいても、偶発的プログラミング（Programming by Coincidence）1を避ける2ために、注意を払って作成する必要があるのが、境界部分のAPI（Application Programmi
エンジニア歴20数年の私が、設計書を書く際に心がけていること - Qiita
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で書かれた、フォーマルな（≒納品物になりえる）設計文書、です。 したがって、自社サービス開発よりも受託開発、アジャイルよりもウォータ
ESDoc - The Good Documentation For JavaScript - クックパッド開発者ブログ
こんにちは。会員事業部の丸山@h13i32maruです*1。 ソフトウェアのドキュメント(マニュアル)を書くには色々なツールや方法があります。 JavaScriptの場合はJSDocというドキュメンテーションツールがデファクトスタンダードです。 ですが、JavaScriptの最新仕様であるECMAScript2015(ES2015)がリリースされたことにより、 JSDocの競合として新しいツールが登場したり、JSDoc自体もバージョンアップしたりしています。 本記事ではそうした新しいツールの一つであるESDocを紹介します。 ESDocとは？ ESDocとは私が2015年4月から開発を行っている、JavaScript(ES2015)向けの良いドキュメントを作るためのドキュメンテーションツールです。 https://esdoc.org/ https://github.com/esdoc/es
docker run — Docker-docs-ja 24.0 ドキュメント
補足説明¶ docker run コマンドは、まず指定されたイメージ上に書き込み可能なコンテナ・レイヤを create （作成）します。それから、指定されたコマンドを使って start （開始）します。この docker run は、 API の /containers/create の後で /containers/(id)/start を実行するのと同じです。以前に使っていたコンテナは docker start で再起動できます。全てのコンテナを表示するには docker ps -a を使います。 docker run コマンドは、 コンテナの内容を確定するため に、 docker commit コマンドと連携して使えます。 コンテナをネットワークで接続する詳細については、 Docker ネットワーク概要 をご覧ください。 コマンドの使用例は、以下の 使用例のセクション をご覧ください。
AsciiDoc と PlantUML と mermaid.js で素敵なテキストベース仕様書ライフ
以前からテキストベースで仕様書(PDF)などを管理したいと思っていたのですが、ようやくその環境が整い、一度実際に運用してみてかなりいい感じだったので紹介したいと思います。 基本テキストは AsciiDoc で記述する UML は PlantUML で記述する フローチャートとかは必要に応じて mermaid.js も使う つまり基本テキストで表現・管理できるものはテキストで書く 成果物は PDF形式。目次(Table of Contents) はつける。 動作確認環境 macOS Sierra 10.12.3 ruby 2.3.1 Asciidoctor 1.5.5 Asciidoctor PDF 1.5.0.alpha.14 Asciidoctor Diagram 1.5.4 mermaid 7.0.0 AsciiDoc とは AsciiDoc Home Page 軽量マークアップ言語の
手順書作成を通して私が学んだ事〜細やかなポエムを添えて〜 | DevelopersIO
手順書を作りながら、こう考えた。 難解過ぎては伝わらない。妙に凝りすぎては読み辛い。形式に囚われ過ぎては窮屈だ。 とかくに手順書は作りにくい。 あんまり上手く無かったですね。これからも精進していきたいと思います。AWS事業本部のしろたです。 ▲こちらはいらすとやさんの夏目漱石です。本当あそこ何でもあるな。流石に旧札は無かったです。 さて、今回話したい主題はもうお分かりですね？そう、手順書についてです。 初めて就職したIT企業でも手順書を作成する機会はあったのですが、今回また手順書を作成する機会を頂きまして、実際に自身が作った手順書をレビューして頂いて色々と思うところがありました。 今回はそれをゆるりと、自分の中の思考を整理する意味でも纏めていきたいと思います。 手順書の定義から入ってみる まず、手順書とは何でしょうか。初めて行う作業や、誰かから引き継ぐ事になった作業を一人で行う場合には割と
システムに不可欠なセキュリティ対策、漏れを食い止める設計書3点セット
「セキュリティ対策はシステム開発で不可欠だが、設計書でうまく表現できている開発現場はまだ少ない」――。 ラックの永井英徳氏（エンタープライズ・セキュリティサービス事業部セキュリティディレクションサービス部長 兼 第一グループ部長）はこう指摘する。よく見られるのが、「クロスサイトスクリプティングの脅威には、Aフレームワークを利用することで対処する」などと、個別の脅威ごとに対策を記述するケースという。しかしこれでは、「システム全体として必要なセキュリティ対策を網羅できているのか判断しにくい」（永井氏）。 とはいえ、機能に関する設計書に、想定しうるあらゆる脅威の内容と対策を書き込むのも問題だ。記述が膨大になり、読みにくい設計書になってしまう。後工程の開発メンバーの作業ミスを招く恐れがある。セキュリティ要件が変わったときの修正作業の負荷も大きい。 このような問題意識のもと、ラックの永井氏は、セキュ
コードに仕様書パスをコメントで書くのやめようよ - Qiita
（まず追記） 自分たちで新たに作成する仕様書はMarkdownで記述してGitHubで管理しています。 こんなのも書いたくらいだし、そこは犯していないです。GitHubを中心とした開発プロセス ドキュメント管理 この記事内で言う仕様書とは、「エクセルで作られて共有サーバに置いてあるチーム管理外のファイル」を指します。 こーゆーの、良くあるよね？ 見た瞬間「_2.xlsxってなんだよォ...このパス絶対古いんじゃあねェのー？」って思う感じのやつ。 ついでに仕様書のパスが長くって妙なところで改行入ってるおまけ付き。 こんなの見るとイラっとする！ コピペしづらい そのパスに仕様書が実在するかわからん 実在するとして、開くのが面倒 ある1つの仕様書のパスが1箇所にコメントされていたら、あと数カ所はコメントがあると思う でもちょっと手入れされてたりで数箇所のコメントが同じ場所を指していないことが往々
ドキュメント作成時のあるあるアンチパターン20 - Qiita
業務でドキュメントを作成するケースは多々ある 例：仕様書・設計書・提案書・メール・障害票．．． ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。 1. 表記がバイト表示・マイクロ秒表示 プログラムが出した数値をありのままに表示するパターン ファイルサイズが100MB, 1GBあろうと、バイト表示にする 桁数が多い数値に、桁区切り（,）を入れない 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？） 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様） 悪い例 No ファイル名 ファイルサイズ(byte) 処理時間(秒)
押下(おうか)にまつわる話 - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに 私が仕様書を書くようになったのは30歳を過ぎてからと遅く、仕様書の書き方が分からなくて悩んだことがありました。通常は先輩たちが作成した仕様書等を見て書き方を覚えていくのでしょうが、仕様書も無く直接プログラムを組むような体制の仕事をしていたため、SI系に転職してから苦労したのであった。 仕様書を書く際に、ボタンを「Enterキーを押す」か「クリックする」かで考えて「押下」にすれば両方満たすだろうと、それ以来ずっと使用しています。 押下については、コンピューター雑誌やマニュアル等を読んで憶えていた用語で特に気にも止めていなかったの
ASP.NET QuickStart Tutorials
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.
わかりやすいドキュメントを書くには 〜 全体像を把握できることが重要 - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに エンジニアなら誰でもたくさんのドキュメントを読むことになります。 その中にはわかりにくいドキュメントも少なからずあると思います。 自分はわかりにくいドキュメントは「全体像が掴みにくい」ことが多いと感じています。 そこで、ここではわかりやすいドキュメントを書くための方法を「全体像を把握できるようにする」という視点でまとめてみました。 また、最後に具体例としてQiita APIドキュメントでわかりにくい点の指摘と改善をしてみました。 ここで扱うドキュメントの種類 ここでは仕様書やリファレンスマニュアルといった類のドキュメントを想定
読みやすいREADMEを書く | Yakst
いくつかのオープンソースプロジェクトを公開している筆者からの、読みやすくユーザーにやさしいREADMEを書くためのアドバイス。 この記事は、Rowan Manning氏による「Writing a Friendly README」(2016/3/14)を翻訳したものです。 あなたのプロジェクトのREADMEは、かなり重要です。そこはプロジェクトに初めて来た人が大抵最初に見るであろう場所であり、唯一のドキュメントであることもよくあります。あなたのオープンソースプロジェクトにとってのREADMEは、企業にとってのウェブサイトのようなものです。ウェブサイトはユーザーエクスペリエンスの注目を集めるところですが、READMEがユーザー観点で考えられることはほとんどありません。 この記事では、分かりやすいREADMEを書くために役立ち、開発者(ユーザー)の要求に見合い、開発者がプロジェクトを初めて見たの
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
AWS ネットワーク構成図生成ツール「CloudMapper」を試してみた - Qiita
https://www.ossnews.jp/oss_info/article.html?oid=8682
こんなに使える！今どきのAPIドキュメンテーションツール
美しいAPI Documentを作れるReadMe.io - テクスタ
