ドキュメント作成システム構築ガイドを読んだ - プログラマでありたい
気になっていた『ドキュメント作成システム構築ガイド』が、Kindle版になっていたので読みました。最近の私の関心テーマおよび課題とマッチしていたので、なかなか興味深かったです。 本書の内容 本書の概要は、Amazonさんには下記のように公開されています。 アプリケーションの開発手順，製品のユーザマニュアルなど，ドキュメントの多くはエンジニアによって作成されています。ドキュメントの品質が低い場合，読み手が誰であっても内容の理解に時間がかかります。ドキュメントは簡潔で内容を正確に伝えるものでなければなりません。エンジニアにとってドキュメント作成は避けて通れません。いまやドキュメント作成はコーディングと同様にエンジニアに必要な技術なのです。本書は，ソフトウェア開発の技法に基づいてドキュメント作成を支援するシステムを構築します。このシステムではGitを用いたバージョン管理，GitHubによる共同編
SphinxでMarkdown拡張言語のMySTを扱う
ReSTとMySTについて ReSTは表現力の高いマークアップ言語であり、標準的なMarkdownではできない以下のような記述が可能です（ただし、一部のMarkdown方言はサポートしているかもしれません）。 任意の場所への目次 (toctree) の生成 脚注 (footnote) 画像の左寄せ・右寄せ テーブル（表）の結合セル しかし、Markdownを既に習得しているユーザにとっては、ReSTを勉強するのは手間です。そこで、Sphinxにプラグインを追加し、Markdown方言であるMySTで記事を作成できるようにします。 MySTはCommonMarkを拡張した言語（上位セット）です（CommonMarkはMarkdownの仕様を明確にした言語で、2014年に開発されました。以降では、MarkdownはCommonMarkのことを指します）。MySTでは、ReST形式で表現できるこ
【汎用ソフトスキル】ドキュメンテーションの続け方
この記事の目的 最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。 想定読者 今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人 そもそもドキュメントが無い組織に所属していてつらい思いをしている人 「ドキュメントを作れ」という漠然としたタスクを振られて困っている人 想定読者ではない人 メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人 私もまだ模索中なので、いいやり方があれば教えてほしいです👀 顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人 この記事では「社内の情報共有」にスコープを切って話をしています 書いている人のスペック(参考) 歴５年くらいのなんちゃってフルスタックエンジニア 普段は Node.js / React.js or R
GitBook がしれっと HonKit になってた件
HonKit 公式ドキュメント HonKit 製作者によると GitBook -> HonKit への移行の経緯は以下の通りです。 GitBookはMarkdownからドキュメントページや書籍を作成するツールですが、 以前OSSで公開されていたGitBook(legacy)はDeprecatedとなって開発は止まっています。 ⚠️ Deprecation warning: As the efforts of the GitBook team are focused on the GitBook.com platform, the CLI is no longer under active development. All content supported by the CLI are mostly supported by our GitBook.com / GitHub integra
静的サイトジェネレーターの選定時に考えること | himenon.github.io
また、これを拡張機能を使って実現できるジェネレータは個人的には今現在避けています。 デフォルトで動くってやはり素晴らしいです。 環境構築サイトのジェネレータが依存しているパッケージやモジュールが、 自分にとって不親切なもの、わかりにくいものは避けましょう。 本来の目的は文章を書くことです。 ジェネレータの依存関係を解決することではありません。 また、OSSなどでドキュメントを他の人が書き換える場合がある場合、メンテナスしやすいようにコマンド1つで立ち上がるようにしておくべきです。 Cirlcle CIのドキュメント(circleci/circleci-docs)を修正したときはちょっと感動しました。なぜならば、docker-compose upのみで自分の環境に出来上がったからです。 とても小さな修正でしたが、このお陰でスムーズにコントリビュートでき、とても印象的だったのを覚えています。
Sphinx で使える Markdown 方言 'MyST' - Qiita
はじめに 最近 Sphinx から離れてしまって、この記事の内容もまだ検証できていませんが紹介だけ。 Sphinx で使える Markdown といえば CommonMark（recommonmark）がすでにありますが、最近 MyST という別の Markdown 方言（Flavored）に対応したようです。 これで reStructuredText でできることが大体 Markdown でもできるようになったでしょうか。 Sphinx 固有のなじみの少ない書き方もありますが、それらは追々覚えていくとして、これでまたさらに Sphinx への抵抗感が少なくなりました。 reStructuredText との比較 recoomonmark に無くて一番困るのは、クロスリファレンスの :doc: や :ref: ではないでしょうか。単体ファイルではなく、Sphinx ならではの機能なのに、こ
Sphinxを便利にして、みんなに使ってもらいたい - Qiita
Sphinxは非常に素晴らしいドキュメント生成ツールです。 この素晴らしいツールを社内で流行らせようと頑張ったのですが、誰も使ってくれません。 みんながどんなタイミングで、Sphinxを諦めてしまうのか振り返ってみました。 reStructuredTextがわからないし、覚えたくもない デフォルトのテーマが見にくいからやめる sphinx-quickstartの設問が多すぎて途中でやめる ドキュメント作成のたびにconf.pyを編集するのが面倒なので使わなくなる ドキュメント確認のたびにmake htmlが面倒なので使わなくなる 最近はJupyterでドキュメント書くので・・・ こんなところでしょうか。 たぶん、Sphinxがいまいち流行らないのも、ここら辺が理由が大きいんじゃないかと思います。 Markdownを使う 残念ながらマークアップ言語の主流はreStructuredTextでは
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
https://twitter.com/hirax/status/1648278189150728192?s=12&t=NsLvh3oAOfGTLrMgFD0oJw
https://twitter.com/hy_twen/status/1536870727999053824?s=12&t=NsLvh3oAOfGTLrMgFD0oJw
https://twitter.com/hirax/status/1643953287857860608?s=12&t=NsLvh3oAOfGTLrMgFD0oJw
sphinx:ハイパーリンク — 苦労する遊び人の玩具箱 1 ドキュメント