docsディレクトリの作成

[book000]

https://github.com/jaoafa/jaoweb4/issues/136#issuecomment-1596428741

現状ブログにある記事の書き方含め、記述方針とか「執筆者向けの情報」をまとめる場所があっても良さそう。

[book000]

• ファイルの階層構造
• 記事のフォルダ構成
• GitHubそのものの使い方およびリポジトリとしてのルール

[book000]

誤タップしがち

[book000]

mkdocsでビルドしてGitHub Actionsでデプロイする。GitHubのPagesは一覧表示できないのでクソ

[Hiratake]

GitHubのリポジトリのWiki機能あるけど、これを使うのとかはどうなんでしょう。 あんまし使ったことないから使い方とかよくわかってないけども。

[book000]

GitHubのWiki、タイトルイコールファイル名になるから日本語付けにくいんですよ。Gitに乗らずコードに紐付かないから更新も忘れるし、出来ればGit管理下に置きたいんですよね。

[Hiratake]

Git使えるぽいですけど…どんな感じかはわからん。 https://github.com/jaoafa/jaoweb4.wiki.git

[book000]

や、Git管理下というのはjaoafa/jaoweb4そのものってことです。このwiki.gitはWikiのGitになるので、ソースコードとは紐づきません。 つまり、textlintの導入PRと一緒にドキュメント更新するとか、きちんと最新状態への維持をするにあたって分離してるよりは同一下のほうが扱いやすいって考えています

[Hiratake]

ふむ… 技術者以外向けのコンテンツが主となりそうだから、そういった人たちが編集しやすいほうがいいのかなーとか思ったんだけど、何かしら手順に変更があったときに、その変更PRのレビュー時に変更してって指摘できるという意味ではそうかも。（指摘わすれそうだけど）

[book000]

技術者以外向けのコンテンツが主となりそうだから、そういった人たちが編集しやすいほうがいいのかなーとか思った

根本的に、内容的に正直私かヒラタケが書く感じになりそうですけどねえ。どんな記事書くかとか、フロントマターにどんな記述をすればいいかとか、lintってそもそもなんだとか、記事構造はどんな感じで、どのフォルダにはどんな記事を置くのかとかの方向性の話になるので。

編集しやすい云々の話でいくと、そもそも論として記事を書く時点でGitがある程度使えなければならない（少なくともコミットとプッシュとプルリクエストはわかってなければならない）ので、だったら記事内容そのものと同じ環境で編集できるリポジトリ内（ソースコードと同じ場所）のほうが良さそうかなと。 読む人（=編集者またはどんな感じで記事作ってんのか気になる人）はGitHub Pagesにmkdocsかなんか静的ドキュメントジェネレーターの成果物を投げて公開するので、まあ普通のWebサイトとしてべつに読めるんじゃないかなと。mkdocs使うなら https://memo.tomacheese.com とか https://adminwiki.jaoafa.com の設定を流用して調整します。

[book000]

すみません、ありえん長くなりました

[book000]

ちなみに、GitHub Wikiを用いたものとして https://github.com/jaoafa/MyMaid4/wiki があるんですが、これも更新してなくて形骸化してますね。

[Hiratake]

きれいにドキュメント化して GitHub Pages とかにアップするって感じだったら、monorepo化とかして別パッケージとして管理するとかしたほうがいいのかねえ… ウェブサイト本体やらドキュメントやらの設定がごちゃごちゃしそう感はある

[book000]

まあ、考えてたのはこのドキュメント環境はdocsディレクトリ下に全部置くつもりだったので（ワークフローを除いて）docsディレクトリ外にファイル置く必要性はないかなーとは思ってはいるんですけども。環境作らんとわからないですが

[Hiratake]

ふむ？

[Hiratake]

なんかビルドとかするのに package.json に設定とかが追加されたりするのでは、と思ったけどそうでもないのか

[book000]

mkdocsっていう静的ページジェネレータはPythonなので、既存の package.json に影響与えないだろうと判断しています。