JetBrains、IntelliJベースのライティングツールWriterSideを発表Lily Maraと信頼性の高いKafkaデータ処理パイプラインを構築する 今日の回では、Thomas Betts氏がカリフォルニア州サンマテオにあるOneSignalのエンジニアリングマネージャー、Lily Mara氏に話を聞いた。 彼女は、OneSignalの他のエンジニアリングチームが使用する社内サービスを担当するインフラサービスチームを管理している。信頼性の高いKafkaデータ処理パイプラインの構築方法について議論する。OneSignalは、RustのKafka...
結局UMLとかシーケンス図とかAWSの図とかどれで描くと良いのよ？と思ったときの選択肢 - Qiita
自身のプライオリティによりますが、いくつか。 Markdownで幅広く再利用性を利かせたい、長期的に丁寧に版管理したい 自分自身の操作性、描きやすさと、見た目 俄然手軽に、短期的に、Onlineでいつでもどこでも いずれかという視点で考えると良いのかなと思い、並べてみました。 1. 長期的に: Markdownで幅広く再利用性を利かせたい、丁寧に版管理したいなら Markdownで描くことのメリットは再利用性。 将来的に追記・編集、自分以外の誰かが手を入れる可能性が高い。 現在のドキュメントだけでなく多種説明資料、媒体に転用する可能性がある。 ...という点で差分管理をしたいなら、以下。 VSCodeでPlantUML、Mermaid 上記参考で以下。 Alt+D でプレビュー起動。 Ctrl + Shift + P でコマンドパレットを起動し、出力。 png, svg, eps, pdf
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
【社内資料公開】運用手順書を作る時のポイントについて書いてみた | 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
ブロック図生成ツール blockdiag — blockdiag 1.0 ドキュメント
ブロック図生成ツール blockdiag¶ blockdiag シリーズはシンプルなテキストからブロック図などの画像を生成する画像生成ツール群です。 blockdiag を用いると以下のような図が簡単に生成できます。 blockdiag の主な機能: 数種類の図に対応 ブロック図 (blockdiag コマンド) シーケンス図 (seqdiag コマンド) アクティビティ図 (actdiag コマンド) 論理ネットワーク図 (nwdiag コマンド) テキストベースの定義ファイルから画像ファイルを生成 (graphviz 風の文法を採用) 定義にあわせて図の配置を自動的に決定 (自動レイアウト) Sphinx, Trac, Redmine, 各種 Wiki エンジン等、多様なシステムへの画像埋め込みに対応 Enjoy documentation with blockdiag !
アジャイル開発におけるドキュメンテーションの実際(1) ―― 本当に必要ですか？ そのドキュメント
アジャイル開発におけるドキュメンテーションの実際(1) ―― 本当に必要ですか？ そのドキュメント 細谷 泰夫 要求仕様書や設計書から取り扱い説明書（マニュアル）まで，システム開発ではさまざまなドキュメント（文書）を作成する必要がある．特に，ウォータ・フォール・プロセスによる開発の場合は，各開発工程においてドキュメントを作成し，それを次工程に引き継ぐことになる．それでは，分析 - 設計 - 実装 - テストを繰り返しながらスパイラルに開発を進めるアジャイル開発の場合は，どのようなドキュメントをどのように作成しているのだろうか？ 本連載では，アジャイル開発とウォータ・フォール開発の両方を経験している筆者が，アジャイル開発におけるドキュメントの位置づけや作成方法について解説する．（編集部） 「アジャイル開発注1ではドキュメント（文書）は作らない」と思っておられる方も多いのではないでしょうか．「
ドキュメンテーションを加速するストレスフリーの作図ツール『blockdiag』 jus2011年6月勉強会
システム開発や保守、運用の現場においてドキュメントは必須のものです。 しかし、ドキュメントの作成・維持には多くのパワーがかかるため、ドキュ メントが存在しない、資料が古いままになっているなどといった現状を多く 耳にします。 本勉強会ではこれらのドキュメントでよく利用される「図」にフォーカスし、 みるみるうちに図を作成できる「blockdiag」をご紹介します。 「blockdiag」はシンプルなテキスト記述からブロック図、ネットワーク図などの 画像ファイルを出力可能なオープンソースの画像生成ツールです。書き やすさ、メンテナンスしやすさを中心にデザインされており、図を作るのに 配置や並べ替えに苦労する必要はありません。 blockdiagのサンプルはこちら このような特徴を持つ「blockdiag」と、シンプルな記述でドキュメントを作成 するツール「Sphinx」を組み合わせることによって
Overview — Sphinx v1.0.7 documentation
Sphinx makes it easy to create intelligent and beautiful documentation. Here are some of Sphinx’s major features: Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information Hierarchic
ソフトウェアのマニュアル管理に適したツール? — ありえるえりあ
Recent entries Apache2.4のリリース予定は来年(2011年)初め(あくまで予定) inoue 2010-12-23 Herokuの発音 inoue 2010-12-20 雑誌記事「ソフトウェア・テストPRESS Vol.9」の原稿公開 inoue 2010-12-18 IPA未踏のニュース inoue 2010-12-15 労基法とチキンゲーム inoue 2010-12-06 フロントエンドエンジニア inoue 2010-12-03 ASCII.technologies誌にMapReduceの記事を書きました inoue 2010-11-25 技術評論社パーフェクトシリーズ絶賛発売中 inoue 2010-11-24 雑誌連載「Emacsのトラノマキ」の原稿(part8)公開 inoue 2010-11-22 RESTの当惑 inoue 2010-11-22 「プ
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ドキュメントを改善するためのはじめの一歩
継続的ドキュメンテーション - コード知識共有への新たなアプローチ
コンパイルとドキュメントの出会い
How to document software architecture? | TSH.io
Yari、新しいMDN Webドキュメントプラットフォーム
Sphinx + blockdiag で始めるドキュメント生活 @ yokohama.pm 2011/05 | Webシステム開発／教育ソリューションのタイムインターメディア
ドキュメントを作りたくなってしまう魔法のツールSphinx
http://www.methods.co.nz/asciidoc/