ドキュメント タグの記事

設計ドキュメントをGit管理して腐らせないようにがんばってみた話をします

Markdownで設計書を充実させようとすればするほど、設計書間やメンバー間のちょっとした揺れで、本質的なレビューがしにくく感じるようになりました。そこでMarkdownのLintツールを導入するモチベーションが高まりました。

Go 1.18のジェネリクス導入の大規模リリースと比べると比較的小さな1.19ですが、それでもさまざまな変更があります。今回ももちろん、恒例行事になりつつある、このテックブログでリリース連載をやります。まずは、GoDocと、その他ツール周りのアップデートの紹介です。

業務を進める上では日々多くの技術情報を調べる必要がありますが、無策に調べると時間を浪費したりイマイチな解決策を採用してしまう可能性があります。そこで、本稿では普段私がやっている方法を中心に、調べる上でのポイントを紹介します。

ユーザーストーリーマップがあると、全体像の認識をチーム全体で共有できて便利です。ユーザーストーリーマップは視覚的にわかりやすく、特殊な構造もしていないため共通理解しやすいことがポイントです。また、ユーザーストーリーマップはこれから何を作ろうかという要求定義の段階でも有効に感じます。この記事では要求の整理と理解のためにユーザーストーリーマップを使ってみたときの気がついた点や振り返りをまとめました

私のチームでは、「システムの設計情報」や「実装に関わる業務知識」などを、`README.md` に整理して GitHub 管理しています。設計資料や業務系のドキュメントが蓄積され、何度も更新され続けることに伴い、「あれ、この資料のリンクが切れてる。オリジナルのファイルはどこだっけ？」と探す機会が増えてきました。本来ならば PullRequest のレビュー時に気付くべきですが、ファイル名のちょっとしたスペルミスや資料パスの変更などだと、目視でのチェックには限界があります。

新しいプログラミング言語を学ぶときは、まず、情報の取得の仕方を覚えておくと学習効率が上がります。検索して、日本語で誰かが解説している二次情報を探すのもいいのですが、古くなって使えなかったり、人気のある情報に偏ってしまって、ちょっと混み入った話になると情報が見つからなくなったりしがちです。多少素っ気なく感じるかもしれませんが、一次情報を読み解く方法を知っておくと良いでしょう。本家が作ったものではなくても網羅的に、リファレンスとなる心意気で書かれたものもたまにあります。