便利なマークダウンをひとつ

[hfu]

これは、#33 で @smellman, @yuiseki, @hfu の間の議論から出てきたアイディアです。

イメージ

Smart Maps / UNVT 関係の知識が体系的に得られる一枚の Markdown ファイル。
一つづきの物語として読めるものというよりは、知識のネットワークへのリンク集のようなもの。

類似していると思うもの

• https://github.com/jlevy/the-art-of-command-line/blob/master/README-ja.md 私は、こういったものがあると良いのではないかと思った。
• Awesome * 系の情報のまとめ方もヒントになる。例: https://github.com/maplibre/awesome-maplibre

ドキュメンテーションに関して、過去のあまりうまくいかなかった例

• https://github.com/unvt/pm/issues
• Table of Contents unvt/washi#1

[yuiseki]

先程Meetupでお話した私の考えをメモしておきます：

• GitHub IssuesやGitHub Wikiで長いドキュメントを書く形式だと、同時編集や共同作業や役割分担が難しい印象がある
• GtiHubリポジトリにMarkdownファイルを置いて、Issueを立てて、Pull requestを出していく方式のほうが共同作業がしやすい
• ドキュメントの扱う話題の範囲、対象読者、大雑把な構成は、最初に決める必要がある

[hfu]

ちょうど年末年始を挟むので、ここで継続審議できればと思います。

ドキュメントの扱う話題の範囲

次に例示するような選択肢の中から選ぶことになると思っています。

1. Smart Maps の範囲全体。話題がかなり広がる、というか話題をかなり広げていく感じになると思います。
2. UNVT の範囲。こちらだと、割とクリアです。produce, style, host, optimize を司る UNVT の部分と、それの deployment オプションである UNVT Portable、というのがクラシックな分割法だと思っています。

対象読者

次に例示するような選択肢の中から選ぶことになると思っています。

1. すでにある程度ウェブ地図の運営までやっている人。どちらかというと便利な備忘録というか知識補完のツールとして提供することになります。結果として読者の数が非常に少なくなります。これだと、英語で書いた方が良いかもしれない。
2. 何らか地図に携わるきっかけがある人。これはかなり広い範囲になります。地図が好きな人は、おおよそ、地図の内容やその「分析」について興味が出てくるので、その興味に対して対応しないのか、一定対応するのか、が一つの考えどころとなるでしょう。

大雑把な構成

アプローチは大きく次のように別れるのではないかと思っています。

1. ツールの分野ごとに分類する。このやり方だと、適用範囲が重複するツールをフェアに扱うことができる可能性が高まると思います。結果的に、一通り読んでも「何をどうすればいいかわからない」ということになる傾向があると思います。
2. 一つのストーリーに沿って並べる。このやり方だと、ハンズオンで追いかけてもらう場合に便利ですが、提案するアプローチに多様性を欠くという欠点があります。

[hfu]

これの実現が #64 という理解をしてみます。
状況の整理のため、いったんクローズしてみます。
また議論する場合には、ためらわずリオープンしましょう。