ADR を1年間書いてみた感想 - 一休.com Developers Blog
宿泊開発チームでエンジニアをしている @kosuke1012 です。チームで ADR を書き始めて1年くらい経ったので、その感想を書いてみたいと思います。 この記事は 一休.comのカレンダー | Advent Calendar 2023 - Qiita の13日目の記事です。 ADRとは アーキテクチャ・ディシジョン・レコードの略で、アーキテクチャに関する意思決定を軽量なテキストドキュメントで記録していくものです。 出典はこちらで、 Documenting Architecture Decisions わかりやすい和訳は以下の記事が、 アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud アーキテクチャ・デシジョン・レコードの勧め | 豆蔵デベロッパーサイト アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ #設計 -
【roff形式を手書きは無理ゲー】manページをMarkdown + Pandocで作成【with manページお作法】
【roff形式を手書きは無理ゲー】manページをMarkdown + Pandocで作成【with manページお作法】 by nao · 公開済み 2020年12月19日 · 更新済み 2020年12月25日 前書き：manualページは伝統的なドキュメント manページは、UNIX系OSのドキュメントであり、コマンドやシステムコールなどの説明が記載されています。 Unix v7の時代（1979年）から変化が少ないため、2020年現在の視点で見ると表現力に難があります。具体的には以下のような欠点があり、manページを良質なドキュメントとするには文章力を試されます。 画像を挿入できない ハイパーリンク非対応 Terminalからしか参照できない（manページをHTMLに変換して公開しているサイトはあります） 勿論、manページより表現力が高いTexinfo、Docbookなどの代替ドキュメ
納品ドキュメントの作成にMarkdown+Vivliostyleを採用した話 - Qiita
こんにちは、製造業でソフト開発エンジニアをやっているとみー(@tommyecguitar)です。 会社で納品物の説明ドキュメントを作ることがあり、その時にMarkdownでの組版をやってみたので、どう運用したか、困ったところ、いい点、悪い点をまとめてみようと思います。 Vivliostyleで組版したブログはたくさんあるので、見た目がどんな感じにできるかなどはそちらを見ていただくか、Vivliostyleのサイトをご覧ください。 Wordじゃだめなのか。 製造業で何かしら長大なドキュメントを作るとなったら、大抵はWordを複数人数で編集するという運用をしているところが多いと思います。 しかし、Wordにはいろいろと悪いところがあります。 チーム内で共同編集すると、編集したところが消えたり、フォントやデザインがなぜか統一されなかったりする。 セクションごとに担当を分けても、マージが手作業にな
ドキュメントに固執せよ - gfnweb
どうして人間集団はこんなにも知見の共有を円滑にできないのか？ 改善にはドキュメントにまつわる各個人の心構え・制度設計・技術的解決の全部が必要だという話をしたい． ここでテーマにしているのは，著名OSSなど世の中にいくらでも知見が転がっている対象ではなく，特に企業内の十数人のチームでクローズドに開発しているなどして集合知に頼れない状況下でのドキュメントについてである． 非常に乱暴な言い方をするなら，「コードとか大部分は誰でも書けるようになるものなんよ，そんなところにマッチョイズムとか感じなくてええねん，我々の知的体力や組織性が真に試されるのはドキュメントちゃうんか」という気持ちです — 画力・博士号・油田 (@bd_gfngfn) June 3, 2022 ドキュメントに書く内容の必須項目或るシステム（ソフトウェアなど）について，そのシステムのことを全く知らない人を想定読者としたドキュメント
結局UMLとかシーケンス図とかAWSの図とかどれで描くと良いのよ？と思ったときの選択肢 - Qiita
自身のプライオリティによりますが、いくつか。 Markdownで幅広く再利用性を利かせたい、長期的に丁寧に版管理したい 自分自身の操作性、描きやすさと、見た目 俄然手軽に、短期的に、Onlineでいつでもどこでも いずれかという視点で考えると良いのかなと思い、並べてみました。 1. 長期的に: Markdownで幅広く再利用性を利かせたい、丁寧に版管理したいなら Markdownで描くことのメリットは再利用性。 将来的に追記・編集、自分以外の誰かが手を入れる可能性が高い。 現在のドキュメントだけでなく多種説明資料、媒体に転用する可能性がある。 ...という点で差分管理をしたいなら、以下。 VSCodeでPlantUML、Mermaid 上記参考で以下。 Alt+D でプレビュー起動。 Ctrl + Shift + P でコマンドパレットを起動し、出力。 png, svg, eps, pdf
「Docs for Developers」を読んだ - 勘と経験と読経
最近知った興味深いPodcast e34.fm で紹介されていたので興味を持って読んでみた本「Docs for Developers: An Engineer’s Field Guide to Technical Writing」に関するメモ。 2023/3追記：翻訳されたようだ。ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング e34.fmwww.oreilly.com この記事の目次 「Docs for Developers」はどんな本なのか 全般的な感想 各章に関する覚え書き Front Matter Chap 1. Understanding your audience Chap 2. Planning your documentation Chap 3. Drafting documentation Chap 4. Editing docum
仕様書の参考例と、こんな内容を仕様書に最低書くといいというお話｜田辺めぐみ
よく、仕様書を書いていなくて、書いてみたいけど、具体的な仕様書がネット上に落ちてなくってこまってるって相談を受けるので 「仕様書の記載内容のイメージ」を作りました！ ※前提として「現在仕様書を書いていない、自社開発のMVP検証前後のフェーズのスタートアップ向け」に書いています。PMが仕様書、エンジニアがDesign Docを書く分担です。 ついでに、システム開発の基礎である「システム開発のV字モデルをベースにした設計書の紹介」も含めてまとめてみましたー！ 大規模開発に使われたり、古くからあるフレームワークなので、スタートアップの方だと、システム開発のV字モデルの概念やそれにあわせた成果物を知らない人が多いけど、「要件定義書」と「設計書」を全てドキュメント化するとどうなるかを理解した上で、「仕様書」として情報を削る方が、考慮漏れ防止やエンジニアがやっている設計内容の理解につながるので、全体を
プロダクトのドキュメントにプルリクエストを送れる仕組みがすごい - Qiita
Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? これ↓なんですけど、意外と RT や Like が付いてたので、ちゃんと書きますね。 しっかしMicrosoftのドキュメントシステム良く出来てるなー。右のEditボタン押すとGitHubが開いてすぐPR送れる。あちらでマージされれば即サイトに反映される。Contiributorsに自分のアイコンが増えた♪ これはフィードバックするのに「面倒」は理由にできないですぞ。https://t.co/9KhAwhV5PP pic.twitter.com/r46zFUvkEp — あめいぱわーにおまかせろ! (@amay077) 2018年6月1
SCOUTER開発者ブログ
2025-04-09 【初心者でもわかる！】WordPressの基本と使い方を解説 WordPressは無料で商用にも利用できるCMSで、個人ブログから企業のホームページやWebサービスなど幅広く利用されています。 オリエンタルランドやクックパッドもWordPressでサイトを構築しているなど世界中で実績を持つCMSで、業務でも使う機会も多いでしょう。 Webサイトの構築に携わる人であれば必ず知っておくべきWordPressの基本について紹介します。 WordPressでできるこ […] 2025-04-09 プログラミング初心者必見！おすすめのテキストエディタ８選を紹介 プログラミングをするうえで欠かすことができないツールの一つに、テキストエディタがあります。システム開発の現場では、専用のソフトやツールがあったりもしますが、まずはテキストエディタでコードを書く技術者が多いです。 そして、
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本 2023年版
coil/docs/design.md at main · cybozu-go/coil
脱ExcelしたいMarkdownテンプレート目次 - Qiita
DevDocs
Amazon.co.jp: ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]: 伊藤敬彦 (著), 吉村孝広 (著), 208 (その他): 本![Amazon.co.jp: ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]: 伊藤敬彦 (著), 吉村孝広 (著), 208 (その他): 本](https://cdn-ak-scissors.b.st-hatena.com/image/square/b3e159842a1f96e7a6cd3ad60234c73b55fc521d/height=288;version=1;width=512/https%3A%2F%2Fm.media-amazon.com%2Fimages%2FI%2F516v0w26krL._SL500_.jpg)