documentationjs + add-text-to-markdownでREADME.mdのAPIリファレンスを自動更新
documentationjs + add-text-to-markdownでREADME.mdのAPIリファレンスを自動更新 documentationjsはJSDocからドキュメントを生成できるツールで、ES2015以降のコードにも対応しています。 (TypeScriptは対応してないようです) 以前はMarkdownへの出力が難しかったのですが、いつのまにかdocumentation build -f mdでMarkdownでのAPIドキュメントが生成できるようになっていました。 これを使うことで、ライブラリを書いてそのJSDocからドキュメントを生成して、READMEのUsageセキュクションを自動的に更新できるようになっています。 以前もできたのですが、かなりトリッキーなテーマを書いたりしないといけませんでした。(後stdoutへの出力がなかった気がします) –theme for
Treat code like code and prose like prose
Some recent experiences have prompted me to rethink the value of treating docs like code in some respects. I want to return to focusing more on content rather than technical workflows, especially when creating new content. Some of the docs-like-code processes exclude too many people in non-engineer roles who would otherwise contribute to the review and development of the content. “Prose like prose
Architectural Decision Records | adr.github.io
Architectural Decision Records (ADRs) An Architectural Decision (AD) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software and/or hardware system. An Architectural Decision Record (ADR) cap
ドキュメントを書くときの「メンタルモデルの原則」 - クックパッド開発者ブログ
こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼
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
Docz
Powered by GatsbyStarting from v2, Docz is entirely built using GatsbyJS. It's optimised for a lightning fast development experience and speedy build times. This also allows you to leverage GatsbyJS's huge ecosystem of plugins and tools. Zero configNo need to worry about complex configuration settings to build and run your documentation. With Docz you can create customizable sites with a single co
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
