「わし詳細設計書書くのやだよ」システム開発で細かければ細かいほど仕様変わった時の変更が爆増してメンテコスト爆上がりする。かけるべきコストはそこじゃない話に賛否両論
しのゆー𝕏今や酒ザコエンジニア @shinoyu 法人やってるソフトウェアエンジニア20年生+見習いバーテンダー 兼蒲田のガルバのおねぇさん/ IT、V系 、ロリィタの人 / 鍵アカからのフォローは教義によりブロック mixi.social/invitations/@s… しのゆー𝕏酒クズエンジニア @shinoyu わし詳細設計書書くのやだよ(￣･ω･￣) 細かければ細かいほど仕様変わった時の変更が爆増してメンテコスト爆上がりする。かけるべきコストはそこじゃない。 必要なのは完成に必要要件がまとめられたもの。それを元に受け入れ試験書がつくられる。それクリアすればどう作ってようが構わんわけだ 改修コストを下げるための設計になってることは前提だけどね。 だけど、詳細設計書が必要となる現場はこの設計することはできない。だってそれできてたら詳細設計書いらないわけで… 2024-05-31 0
組織が記憶喪失になるのをどうすれば ～ ryuzee技術顧問にきいてみた - NTT docomo Business Engineers' Blog
何か決定した事実は実装や規則の形で残っているものの、決定までの経緯をチームメンバーが覚えていない――。 この記事では、そうした組織が記憶喪失になることにどう対処していけばよいか、NTT Comの技術顧問である吉羽龍太郎 (@ryuzee) さんにふらっと相談してみたら一瞬で突破口が見つかった＆話に奥行きが出た話を共有します。 目次 目次 軽く自己紹介 事の発端 ryuzeeさんの油セール 実際に聞いてみた 新たなる概念：ADR ADRの実践：その1 何を書くか ADRの実践：その2 どこに書くか ADRの実践：その3 どう書くか 相談を受けて試しに書いてみたADR まとめ 軽く自己紹介 イノベーションセンターの小林 (@ppyv) です。 開発・検証用PCの開発に一段落つけた後、社会人学生としてたっぷり2年間学習を積んでいました。 いまはイノベーションセンターで働く社員のみなさんに、よりよ
結局UMLとかシーケンス図とかAWSの図とかどれで描くと良いのよ？と思ったときの選択肢 - Qiita
自身のプライオリティによりますが、いくつか。 Markdownで幅広く再利用性を利かせたい、長期的に丁寧に版管理したい 自分自身の操作性、描きやすさと、見た目 俄然手軽に、短期的に、Onlineでいつでもどこでも いずれかという視点で考えると良いのかなと思い、並べてみました。 1. 長期的に: Markdownで幅広く再利用性を利かせたい、丁寧に版管理したいなら Markdownで描くことのメリットは再利用性。 将来的に追記・編集、自分以外の誰かが手を入れる可能性が高い。 現在のドキュメントだけでなく多種説明資料、媒体に転用する可能性がある。 ...という点で差分管理をしたいなら、以下。 VSCodeでPlantUML、Mermaid 上記参考で以下。 Alt+D でプレビュー起動。 Ctrl + Shift + P でコマンドパレットを起動し、出力。 png, svg, eps, pdf
How to document software architecture? | TSH.io
How to document software architecture – this is a question you can consider in two ways. Sure, there are some general best practices that you should always follow. Other than that, however, there are various approaches that work better depending on the complexity and type of your software project. In this article, I’m going to show software documentation the way it’s done at The Software House. In
ARCHITECTURE.mdというものを書いてみた - maru source
こんにちは丸山@h13i32maruです。システム全体を簡単な図とテキストでまとめる「ARCHITECTURE.md」というものを最近知りました。これは良さそうと思い、JasperのARCHITECTURE.mdを書いてみました。 jasperapp/jasper/ARCHITECTURE.md ARCHITECTURE.md自体の目的は「プロジェクトへの新規参加者が全体像の把握を効率的に行えるようにする」という感じです。書き方の指針や注意点などは考案者による記事を見てもらうのがよさそうです。また良いサンプルとしてrust-analyzerというOSSのARCHITECTURE.mdが紹介されています。 https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html https://github.com/rust-analyzer/ru
Google、マイクロソフトらが設立、「Open Web Docs」を発表。MDNなど支援、Web技術のドキュメント化を推進
オープンソースやテクノロジーを中心としたコミュニティの維持や発展を支援する組織「Open Collective」は、Web技術のドキュメント化を長期的に支援する取り組みとして「Open Web Docs」を発表しました。 Open Web Docsはおもに既存のコミュニティによるドキュメント、特にMozillaのMDNをまずは優先的に支援するとしています。 We’re happy and proud to announce Open Web Docs, to support a community of technical writers around creation and long-term maintenance of web platform technology documentation that is open and inclusive for all.https://t
プロダクショングレードのコンテナ管理基盤
Kubernetes (K8s)は、デプロイやスケーリングを自動化したり、コンテナ化されたアプリケーションを管理したりするための、オープンソースのシステムです。管理や検出を容易にするため、アプリケーションを論理的な単位に分割し、コンテナをグルーピングします。KubernetesはGoogleでの15年にわたる経験を基に構築されており、コミュニティのアイディアや慣習との最善の組み合わせを取っています。 惑星規模のスケーリングGoogleが週に何十億ものコンテナを実行することを可能としているのと同じ原則に沿ってデザインされているため、Kubernetesは運用チームの人数を増やさずに規模を拡大することができます。 いつまでも使えるローカルのテストであろうとグローバル企業での開発であろうと、Kubernetesの柔軟性はあなたの要求がどれだけ複雑になろうとも問題なく、矛盾無く、簡単にアプリケーシ
AWSの各種サービスやSDKのドキュメントがオープンソースとしてGitHubに公開。誰でもコントリビュートや再利用が可能に
AWSの各種サービスやSDKのドキュメントがオープンソースとしてGitHubに公開。誰でもコントリビュートや再利用が可能に Today we are adding over 138 additional developer and user guides to the organization, and we are looking forward to receiving your requests. You can fix bugs, improve code samples (or submit new ones), add detail, and rewrite sentences and paragraphs in the interest of accuracy or clarity. 今日、私たちは138以上のデベロッパーガイドとユーザーガイドを追加し、みなさんの要望を心待ち
『TagDox』とは？文章解析、自動タグ付けAIでドキュメント管理を自動化！？ | Ledge.ai
サインインした状態で「いいね」を押すと、マイページの 「いいね履歴」に一覧として保存されていくので、 再度読みたくなった時や、あとでじっくり読みたいときに便利です。
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | DevelopersIO
はじめに こんにちは植木和樹＠上越妙高オフィスです。本日は私がここ10年くらい意識している運用手順書を書くときのポイントについてまとめてみました。 対象読者 開発・構築したシステムを別の人に引き継ぐ予定のある人 他の人が作ったシステムを引き継ぐ担当の人 半年後の自分でも分かる手順書の書き方に困っている人 （この記事を読むのにかかる時間の目安：5分） 1. ドキュメントの冒頭に書くこと まず個々の詳細手順の前に、ドキュメント自体について記載してもらいたいことです。 1.1. ドキュメントに書かれていることを3行で書く ドキュメントの最初には、このドキュメントに何が書かれているのかを100文字くらいで書いておくと良いでしょう。 システムが増えれば増えるほど手順書も増えていくものです。見つけたドキュメントに自分の期待するものが書かれているのか、冒頭数行でわかるようになっているとうれしいです。 1
Velocity - The Documentation and Docset Viewer for Windows
Velocity gives your Windows desktop offline access to over 150 API documentation sets (provided by Dash for OS X) Download Buy Now A Huge Documentation Library Over 150+ API documentation sets are available in Velocity covering some of the most popular languages and API frameworks that you use for everyday development. If you've every seen or used Dash on the Mac then you have a good idea of what
Sphinx + blockdiag による非プログラマのための使える図解の紹介 « sojimn.com
はじめに こんにちは。Sphinx Advent Calendar 2012 の4日目のエントリです。@tk0miyaより受け取りました。 Sphinx を使い始めてまだ日が浅いですが実際に仕事で使ってみてすばらしいツールだと今更ながら気づき、Sphinx に特化したエントリというよりも Sphinx + blogckdiag を使って仕事に使えるダイアグラムの表現方法についてご紹介します。 非プログラマでも簡単に作成ができ修正も簡単、イライラしないでサクサクと図が書けます。 ソフトウェア開発プロジェクトで作成されるドキュメント(特にマニュアルで利用)は顧客に説明するための図解を多用します。これまでの経験で Word/Excel の描画ツールをつかってがんばって作った図 調整と編集がとても大変 Visio を使ってわかりやすく綺麗に作成されているが、Word/Excel/PowerPoi
Dash - naoyaのはてなダイアリー
Twitter で知人に紹介したら周囲から「これは便利」という声が結構聞こえてきたので、ブログでも紹介しておこう。Dash というドキュメントビューワー。 iOS や RubyMotion、あるいは node や ruby そのほかのマニュアルをまとめてインクリメンタルサーチして API を調べる、ということができる。メジャーな色んな言語に対応している。 本来 Dash は "Snippet Manager" ということで、コードスニペットを管理するためのアプリケーションのようだけど自分は単なるドキュメントビューワーとしてしか使っていない。RubyMotion の勉強会に行ったときに、これが便利というのを教えてもらってその後愛用しています。主に iOS の開発のときに利用していた。 http://satococoa.github.com/blog/2013/01/22/view-rdoc-
ブロック図生成ツール blockdiag — blockdiag 1.0 ドキュメント
ブロック図生成ツール blockdiag¶ blockdiag シリーズはシンプルなテキストからブロック図などの画像を生成する画像生成ツール群です。 blockdiag を用いると以下のような図が簡単に生成できます。 blockdiag の主な機能: 数種類の図に対応 ブロック図 (blockdiag コマンド) シーケンス図 (seqdiag コマンド) アクティビティ図 (actdiag コマンド) 論理ネットワーク図 (nwdiag コマンド) テキストベースの定義ファイルから画像ファイルを生成 (graphviz 風の文法を採用) 定義にあわせて図の配置を自動的に決定 (自動レイアウト) Sphinx, Trac, Redmine, 各種 Wiki エンジン等、多様なシステムへの画像埋め込みに対応 Enjoy documentation with blockdiag !
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
JetBrains、IntelliJベースのライティングツールWriterSideを発表
ドキュメントを改善するためのはじめの一歩
継続的ドキュメンテーション - コード知識共有への新たなアプローチ
コンパイルとドキュメントの出会い
Yari、新しいMDN Webドキュメントプラットフォーム
Microsoft、.NETドキュメントの統合を発表
