わかりやすいシステム構成図の書き方 - Qiita
わかりにくいシステム構成図とは こんなシステム構成図を書いてないでしょうか？ このシステム構成図のわかりにくい点が３つあります。それは 製品名は書いてあるが「役割」が書いていない データと処理が区別できない データの流れと制御の流れが区別できない の３つです。 わかりやすいシステム構成図 これら３つのわかりにくい点を改善したわかりやすいシステム構成図が↓です ポイントを解説していきます ポイント1. 製品名称ではなく「役割」を書く システム構成図には製品名称ではなくシステムコンポーネントの「役割」を書きます。 役割とは、例えば〇〇データや〇〇処理といったことであり、それを読むだけでシステムの動きを理解できる文字列です。役割をかかずに製品名称のみを書いてしまうと、その製品を知らない人が見たときに理解できません。例えば「Cloud Pub/Sub」という製品はGCPというパブリッククラウドの分
そもそもnpmからわからない
はじめに やっぱりwebpackがわからない（エピソード1）、エピソード2を公開しているのですが、そもそもnpmからわからない、という人もいると思いますので、今回はnpmに関して説明します。 なお、やっぱりwebpackがわからないではViteに関して触れていますが、Node.jsもDenoという新しいランタイム環境が登場しています。ですが、やはりまだ開発現場で使用するには難しいと思いますので、Node.jsを使用するうえでnpmはちゃんと理解しておいた方がいいです。 npmとは npm とはNode.jsのパッケージを管理するシステム、所謂パッケージ管理システムです。アプリケーションを作成する際、便利なパッケージをそのプロジェクトにインストールして、使用することができます。 ところで、パッケージとは一体何なのでしょうか？ パッケージとは システム開発ではモジュール、パッケージ 、ライブラ
GitHub Actions で簡単にバージョン番号付きリリースとリリースノートを作成する方法
対象読者判定フロー 以下の質問にはいかいいえで答えてください。 Q1: GitHub を使用していますか？ はいの方→次の質問に進んでください。 いいえの方→対象外です。すみません。 Q2: ソースコードなどの変更は全てプルリクエストで行って（＝master/main 直コミットはしていない（多少ならOK））いますか？ はいの方→次の質問に進んでください。 いいえの方→まずはプルリクエストベースの開発に切り替えてみてはいかがでしょう？ その後で続きを読んでください。 Q3: リリースノートをちゃんと書いていますか？ はいの方→基本的に対象外です。継続して書いていって下さい。楽をしたいと思ってる場合は続きを読んでください。 いいえの方→あなたは対象読者です！ この記事を読んで、お手軽自動生成でも良いのでリリースノートを作成しましょう！ はじめに 公開しているソフトウエアにバージョン番号を付け
Writing better release notes
31st January 2022 Release notes are an important part of the open source process. I’ve been thinking about these a lot recently, and I’ve assembled some thoughts on how to do a better job with them. Write release notes. Seriously—if you want people to take advantage of the work you have been doing to improve your projects, you need to tell them about it! Include the date. The date matters a lot, b
「Client と Server があるスマフォゲームを 開発するときに人類が考えておくべき、ほとんど全てのこと」をまとめる構想
「Client と Server があるスマフォゲームを 開発するときに人類が考えておくべき、ほとんど全てのこと」をまとめる構想 これは何 「Client と Server があるスマフォゲームを開発するときに人類が考えておくべき、ほとんど全てのこと」 をドキュメントとしてまとめようと思ったときに、何を書けばいいかをリストアップする場所 （構想を練る目的なので、不完全な内容です） のんびり更新予定 モチベーション 1. 仕事上の実利 職業柄、生きていくために Client / Server 実装があるスマフォゲーム を一定期間をかけてチームで開発することが多い ゲームのチーム開発は要素が多く、先立って考慮しておくべきことも多岐に渡る 「考慮しておくべきことリスト」 を用意しておくことで、考慮漏れによるミスや手戻りを減らす 初心者にとっては抜けていた知識の補完になり、中級者以上にとっても思考
API 設計ガイド | Cloud APIs | Google Cloud
フィードバックを送信 API 設計ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。 変更履歴 はじめに これは、ネットワーク API の一般的な設計ガイドです。2014 年以来 Google 内部で使用され、Cloud API やその他の Google API を設計するときに Google が従うガイドです。この設計ガイドは、外部のデベロッパーへの情報提供と、互いの連携作業の効率化のためにここで共有されています。 Cloud Endpoints のデベロッパーには、このガイドは、gRPC API を設計するときに特に役立つことがあり、そのような場合にはこれらの設計原則を使用することを強くおすすめします。ただし、このガイドの使用は必須ではありません。Cloud Endpoints と gRPC はガイドに従わなくても使用できます。 このガイドは、gR
ドキュメントを書く技術 - blog
READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ
Flow導入して数ヶ月がたった所感 - tomoima525's blog
ReactNativeプロジェクトで、型がないことによるつらいシーンが多くなり(特に変数の解釈に起因するバグ)、Facebook製の静的型解析ツールであるFlowを数ヶ月前に導入しました。導入時の学びと、しばらく運用して感じていることについて個人的な感想を書きました。 Flow選定理由 Javascriptで静的な型付けをするといえばTypeScript(正確にはJavascriptのスーパーセット)がありますが、プロジェクト途中からの導入しやすさの観点からFlowにしました。Flowはお作法(行頭に @flow つける等)さえ押さえれば誰でも使えることから導入障壁はだいぶ低いといえます。導入のメリットについては以下のスライドがとてもわかりやすいです。 speakerdeck.com flow status でプロジェクトに対して静的型解析を走らせることもできますが、 コーディング時にワー
ESDocという(多分)モダンなドキュメンテーションツールの紹介 - maru source
こんにちは丸山@h13i32maruです。 僕は2015年からESDoc*1というJavaScript向けのドキュメンテーションツールを開発しています。 https://esdoc.org https://github.com/esdoc/esdoc Star 最初のリリースから2年、昨日ようやくv1.0をリリースできました🎉 いやー、ここまで長かったです。今ではRxJSやSketchAPIなど、様々なツールで使用されています。 この2年間、ESDocは2つのゴールを目指して開発してきました。 ドキュメントの作成・メンテナンスを快適にする（ドキュメントを書くの楽しい！という状態） ソフトウェアの使い方を簡単に理解できるドキュメントを作成する（ソースコード読まなくても大丈夫！という状態） この2つを満たすためにESDocは色々な機能を提供しています。 今日はそれらの機能の中でも(多分)モダ
Javadoc ドキュメンテーションコメントの書き方 - Qiita
出展: プログラム内のコメントの書き方 | 天才まくまくノート はじめに（モチベーション） こんな話があります。あるソフトウェア企業が一人の技術者の採用を決めました。その決め手となった理由は、「公開しているオープンソースソフトウェアのドキュメントが素晴らしかったから」です。彼らは、作成されたドキュメントを見ただけで、その人には技術力がある、一緒に働いて欲しいと判断したのです。 ある国の言語を学ぶために読み書きの練習が必要であるのと同様に、コーディング技術をつけるには、多くの良質なコードを読み、多くのコードを書くことが必要です。設計ドキュメントを書くのも同じことです。日頃から分かりやすいドキュメントを書く鍛錬を怠らず、長年の経験を積んでいかなければ、良質なドキュメントを書く力は身に付きません。今日からドキュメンテーションコメントをバリバリ書いて、ドキュメンテーション力を付けていきましょう。
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
Next.js の「next start・next dev」挙動差分一覧