開発ドキュメントを書き終わったら、他の人に読んでもらうよう公開すると思います。このとき何をすればいいのか、何に気をつければいいのかが分からないかもしれません。公開するにあたって、やるべきことは多くないのですが、気をつけること、やった方がいいことはいくつかあります。
この記事に書いてあることは基本的なことですが、実践することによって、より多くの人に読んでもらえるようになったり、公開に伴うリスクを減らすことができると思います。
テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。
開発ドキュメントを公開するときにやること
開発ドキュメントを書き終えて、レビューなどを通してページが完成したとします。あとは公開するだけですが、公開にあたってやることは多くありません。
開発ドキュメントを公開したときは、次の3つを行います。
- 正常に公開されたことを確認する
- 公開したことを共有する
- チケットのステータスを変更する
それぞれについて、簡単に見ていきます。
1. 正常に公開されたことを確認する
まずは何よりも、ページが正しく表示されていることを確認します。このとき余裕があれば、誤字・脱字がないかを軽くチェックするといいと思います。
注意すべき点として、社内のドキュメント共有サービスを利用している場合は、ユーザーごとにアクセス制限がかかっている可能性があります。この場合は、見てほしいユーザーに対して適切な権限があるかどうかを確認します。
2. 公開したことを共有する
ページが問題なく表示できることを確認したら、次はページを読んでほしい人や、「開発ドキュメントを書いてほしい」と依頼してきた人などに共有します。これにより、よりたくさんの人に開発ドキュメントを読んでもらうことができます。TwitterなどのSNSアカウントを運用している場合は、SNS上でも共有します。
このとき、ページを公開するにあたってレビュー等に協力してくれた人には、感謝を伝えるとよいと思います。
3. チケットのステータスを変更する
あとは、開発ドキュメントを変更するために作成されたチケットのステータスを「完了」に変更します。
記事の執筆は、GitHub Issueのようなチケットで管理していることがあると思います。この場合は、チケットのステータスを完了にします。このとき、公開したページのURLといった情報を記録しておくと、後日確認するときなどの参考になります。
まとめ
開発ドキュメントを書き終えて公開するときは、ページが正しく表示されるかを確認して、関連する人に共有し、最後にチケットのステータスを変更します。
これにより、多くの人に記事を読んでもらえたり、公開に伴うリスクを減らすことができます。
