テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 本資料をもとにした書籍も発売中です:https://amzn.asia/d/2hQNEk2 Twitter:https://twit…

わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか? このシステム構成図のわかりにくい点が3つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の3つです。 わかりやすいシステム構成図 これら3つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
社内勉強会向けに作成したコード内コメントとJavadocの書き方についてのスライドを、Speaker DeckとSliDeckで公開しました。 このスライドは概要とメリットについてざっくり説明し理解と学習の動機を作ることを目的としていますが、これは日本ないし中国の大学ではコメントについてそこまで扱わないらしい*1という前提に基づいたものです。 ここに記載のない発展的な内容としては以下が挙げられますが、これらについて学ぶのはまず手を動かした後で良いと考えています。 API Specとは何か、何を書くことが望ましいのか(読み手目線に立った考え方) package-info.java によるパッケージに対するドキュメンテーションコメント Mavenでjavadocを出荷する方法 @Documentedアノテーションとは何で、いつ必要なのか コード内コメント以外のドキュメント(README、コミッ
As presented at Twin Cities Code Camp on April 16, 2016 --------------------- Documentation generated from source code is very popular. Solutions such…
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く