サービシンクの名村が25年に渡るWeb制作のプロジェクトマネジメントで「テキストで情報を伝える」上で認識齟齬に至る点を洗い出した「誰がどう見てもそうとしか受け取れない文書術」のセミナースライドの2020年3月29日公開版です。 Web制作・システム開発に関わる人以外には事例等が分かりにくいかもしれませんが、日本語の弱点とそれを補うためのコツと答えを記載していますので、何かの参考になれば幸いです。
![誰がどう見てもそうとしか受け取れない文書術(公開版)](https://cdn-ak-scissors.b.st-hatena.com/image/square/fc0576f82075e94b4710b03f44d2754964747af5/height=288;version=1;width=512/https%3A%2F%2Ffiles.speakerdeck.com%2Fpresentations%2F2597129d6a1f4d3d97897804a8a6bffa%2Fslide_0.jpg%3F15218308)
背景 最近は変化し続ける要件に対応するために、システムも柔軟であることが求められています。 そのため、部分的に変更やスケールの可能なシステムを構築し、API経由で連携するマイクロサービス的アーキテクチャが増えてきています。 そういった設計の中で問題になっていくのが、従来のモノリシックなアプリケーションではIDEやコンパイラなどで行っていた、機能間のインターフェイスをどう管理するかという部分です。 Swaggerとは? SwaggerとはRESTful APIのドキュメントや、サーバ、クライアントコード、エディタ、またそれらを扱うための仕様などを提供するフレームワークです。 公式サイトでは、The World's Most Popular Framework for APIsと謳っています。 その理由は、マイクロソフト、Google、IBM、SmartBearなどを大手の企業を含む「Open
役立つコードレビュー(CR)のコツは、学校では習いません。アルゴリズム、データ構造、プログラム言語の基礎は習っても、確実に役に立つフィードバックを返す方法をじっくりと教えてくれる人はいないでしょう。 コードレビューは優れたソフトウェアを作り出すには欠かせないプロセスです。レビューを通したコードは、そうでないコードよりも 質が高く、バグが少ない 傾向があります。健全なコードレビュー文化には、副次的な利点もあります。たとえば、 バス因子 を押しとどめる、新メンバーのトレーニングに最適なツールになる、など。また、コードレビューは優れた知識共有の手段でもあります。 前提 まずは、この記事のポイントの前提を提示する必要があるでしょう。それは以下のとおりです。 信頼のおける環境で作業をしている。あるいは、あなたとチームは、あなたの信頼性を高めることを目指して作業している。 コードではないシナリオでフィ
はじめに この記事は How to write the perfect pull request - GitHub を和訳というか、意訳した記事です。 ご指摘などありましたら大歓迎です! 良いプルリクエストを書くには (原題 : How to write the perfect pull request) 会社が成長していくと、人もプロジェクトも様変わりしていきます。GitHubの中に私達が望む文化を育んでいくためには、我々が何を自覚してコミュニケーションするべきなのか分かってきました。私達のチームが最強であり続けるために、最近以下のようなプルリクエストのガイドラインを導入しました。 プルリクへのコメント (原題 : Approach to writing a Pull Request) プルリクエストには目的を明記しましょう。たとえば… これは〜を調べてみるためのプロトタイプです これは
開発者であれば避けては通れないドキュメンテーション。 しかし多くの開発者が嫌がっているドキュメンテーション。 今回はアジャイル型開発(以下、アジャイル)のプロジェクト・チーム開発者における最適なドキュメンテーションについて考察したいと思います。 アジャイルとドキュメント ドキュメントは書かなくて良い? 日本においてアジャイルはゆっくりだが確実に浸透しています。 7年間アジャイルをしていた私としては嬉しく思う反面、世間には誤った認識が広がっているのもまた事実です。以下はアジャイル勘違い集の抜粋です。 Q. ドキュメントを書かない? もちろんアジャイルプロセスでもドキュメントは書きます。ただ優先順位が異なるだけです。 ... 最小限の文書化で最大限の効果を狙う、必要にして十分なドキュメント。そうしたドキュメントは一朝一夕に書けるものではありません。 ― ドキュメントを書かない?|アジャイル勘違
こんにちは, id:papix です. この記事は, 「はてなエンジニア Advent Calendar 2018」の9日目の記事です. qiita.com 昨日は id:wtatsuru さんによる, 「基盤開発観点からみたはてなのAWS活用のこれまでとこれから」でした. wtatsuru.hatenadiary.com 「手順書」のススメ さて, 早速本題に入っていきましょう. 皆さんは「手順書」を書いていますか? 自分はと言うと, 最近そこそこの規模のオペレーションが必要なタスクを担当する機会が多く, その度に手順書を書いて, レビューしてもらってからオペレーションをするようにしています. 例えば, 今年実施した「はてなが提供するドメインを利用したブログのHTTPS化対応」のリリースの時は, このような手順書を書いていました: この時は, GitHubのIssueに手順書を用意してい
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く