cocoa-documentation
cocoa-documentation copied to clipboard
openCACAO
FAQ的なサイトテンプレート作成
解説や手順などを公開する為の場所があった方がいいと思ったので テンプレートを作成してみました。 以下の事項についてどの様に使っていくか等を決められればと思います。
https://sumo-sumo.github.io/ （まだ個人repositoryにあります）
１．そもそも必要か？ Wiki等もあるのでそのあたりで代替えできるのかどうか。
２．使うならどんな位置づけにする？ 公式情報のFAQは存在するのでFAQというよりも 「お役立ち情報」的な位置づけとしたほうがいいか。
３．どうやって記載内容を決めていく？ ・主に公式情報で説明不足（画像も欲しい等）を補う内容をまず載せてみる。 ・issueについての概要を記載してissueへのリンクを貼るなどしてみる。 ・単純にissueとして質問が上がったら一般人として回答できそうなものは載せてみる （あまり断定的にならない様に非公式なので。。。）
４．その他決めて置いた方がよさそうな事があれば
FAQサイトのイメージ、拝見しました。
そこで一つ疑問が湧いたのですが、もしこうした形でFAQがサイトとして独立した場合、コンテンツはどのように管理運営されるのでしょうか？
もし可能なら、貼って下さった完成後のサイトイメージの元となるリポジトリを公開して頂ければ、他の皆さんもそのイメージが掴みやすくなると思いますがいかがでしょうか？
以上、よろしくお願いいたします。
そもそも必要か？
記述場所自体は別個の物としては不要かと Wiki にページ追加して行くものかなと。
使うならどんな位置づけにする？
FAQ や Q&A と個別の How To は別の物と思います。 FAQ 等から参照される詳細情報（個別手順）として有った方が良いと思われます
どうやって記載内容を決めていく？
実際に作成してみて、後から整理したり課題・問題が出れば解決して行けば良いものかと思われます。 一つ一つに対してはあくまで手元で作業した事例にしかなり得ません。 実際に試した人からのフィードバックは欲しいですね。
そこで一つ疑問が湧いたのですが、もしこうした形でFAQがサイトとして独立した場合、コンテンツはどのように管理運営されるのでしょうか？ もし可能なら、貼って下さった完成後のサイトイメージの元となるリポジトリを公開して頂ければ、他の皆さんもそのイメージが掴みやすくなると思いますがいかがでしょうか？
サイトのコンテンツとしてはopenCACAOにサイト専用のRepositoryを作成して管理される事になります。 このURLでアクセスをするとhttps://sumo-sumo.github.io/でアクセスすると サイトコンテンツのRepositoryのindex.mdを表示する様になっています。
サイトコンテンツのRepository https://github.com/sumo-sumo/sumo-sumo.github.io
下記を参考にして作成しています。 GitHub Pagesサイトの作成
そもそも必要か？
記述場所自体は別個の物としては不要かと Wiki にページ追加して行くものかなと。
使うならどんな位置づけにする？
FAQ や Q&A と個別の How To は別の物と思います。 FAQ 等から参照される詳細情報（個別手順）として有った方が良いと思われます
ご意見ありがとうございます。 「基本的な公開場所は気軽に書けるWikiにしておいて必要な物だけ作成していく」 というのは作業負荷が軽減されて良さそうですね。
どうやって記載内容を決めていく？
実際に作成してみて、後から整理したり課題・問題が出れば解決して行けば良いものかと思われます。 一つ一つに対してはあくまで手元で作業した事例にしかなり得ません。 実際に試した人からのフィードバックは欲しいですね。
専用のRepositoryを一つ作成する事になるので 記載内容へのフィードバックは専用のRepositoryへissueを登録してもらえばサイトに反映していけそうです。
専用のRepositoryを一つ作成する事になる
これがちょっと分からないところですね。 Github Pages を使って作るからと言う意味でしたら、「その必要はあまり感じ無い」という意味で１は必要ないと言う主張をしています。（ cocoa-documentation リポジトリで別途 Github Pages を作ることも出来ます ）
Wiki では表現しにくい様な複雑な構成のページを作成するのでしょうか？ 念の為ですが、Github の Wiki ページでも画像の貼り付け程度は出来ますよね。
そもそも作成の趣旨を記載していませんでした。すみません。 「GitHubを使い慣れていない人」や「Wikiって何？」という人に向けて 情報を公開する場所があった方がいいのでは？というところから GitHubでサイトが作れてコンテンツのルートパスでアクセスをかけた時に 自動でindexを表示できると知り試しに作成してみました。
GitHubを知らない人にとっては「Wikiを見てください」と言っても 必要な情報にたどり着けない状態になってしまうかなと思っています。
Github Pages を使って作るからと言う意味でしたら、「その必要はあまり感じ無い」という意味で１は必要ないと言う主張をしています。（ cocoa-documentation リポジトリで別途 Github Pages を作ることも出来ます ）
GitHubでサイトを作るのと普通に(?)Github Pagesを作成する違いは ルートパスでアクセスした時にindexを自動で表示できるかどうか。 ということだと思っていました。（違ったらすいません） ※「ユーザ名（Organization名）.github.io」でrepositoryを作成するのが GitHubでサイトを作る上での命名ルールなのかなぐらいの理解です。
私も2重管理やRepositoryがあまり多くなるのはメンテナンスが大変になるのであまりやりたくないです。 もしcocoa-documentationをそのまま使う方法でGitHubでサイトの様に ルートアクセスでindexを自動表示する方法があれば教えていただけると助かります。
Wiki では表現しにくい様な複雑な構成のページを作成するのでしょうか？
構成としてはWikiでも充分に表現できる内容ではあります。
「GitHubを使い慣れていない人」や「Wikiって何？」という人に向けて 情報を公開する場所があった方がいいのでは？という
この場合、Github Wiki+Markdown を利用する場合と HTML+CSS+git を利用する場合の比較になると思います。 少なくともリポジトリ作成時に git は苦手という事を聞いたので Wiki 中心で推しています。 Github 固有の部分は少ないので基本的には Wiki の編集に慣れて欲しいとは思っています。 Markdown 自体に慣れていない場合は補助するEditorの利用も検討してみても良いかなと。
https://ckeditor.com/github-writer/
GitHubを知らない人にとっては「Wikiを見てください」と言っても 必要な情報にたどり着けない状態になってしまうかなと思っています。
見る側にとってWikiで出来ているのかどうかはあまり関係内容に思えますが、どうでしょうね。 ただし、あまり見栄えや見やすさに考慮したもので無い、と言う問題はあります。 Github Actions 等と連携させる必要がありますが、Github Wiki から HTMLサイトを自動生成するツールは複数有ります。 そちらを利用する方が、一つの管理対象から見やすいページを出すことも可能になるはずですから、 まずはその道を検討して頂くのが良いのかなと。
変換プログラムの一例： https://github.com/yakivmospan/github-wikito-converter
※「ユーザ名（Organization名）.github.io」でrepositoryを作成するのが GitHubでサイトを作る上での命名ルールなのかなぐらいの理解です。
そうすることが多く推奨はされることが多いですが、特に制限があるわけでは無いです。 管理権限は必要ですが、任意のリポジトリ・ブランチを Github Pages として指定出来ます。
https://docs.github.com/ja/github/working-with-github-pages/creating-a-github-pages-site#creating-your-site
余談ですが、ルートパス・ルートアクセスと言う語はデザイナーさんから度々耳にしますが、個人的にはよくわからない語という印象が大きく･･････ プログラマー界隈でも使われるのかな。
兎にも角にも、管理対象がばらけることには慎重になる必要があると思います。
いろいろと教えていただきありがとうございます。 管理対象が増えないようにもう少し検討してみます。 初めての事が多いのでどこまで出来るのかは分かりませんが出来そうな範囲でやってみます。
Github 固有の部分は少ないので基本的には Wiki の編集に慣れて欲しいとは思っています。 Markdown 自体に慣れていない場合は補助するEditorの利用も検討してみても良いかなと。 https://ckeditor.com/github-writer/
ツールありがとうございます。 Markdownにも慣れるように努力します。
Github Actions 等と連携させる必要がありますが、Github Wiki から HTMLサイトを自動生成するツールは複数有ります。 そちらを利用する方が、一つの管理対象から見やすいページを出すことも可能になるはずですから、 まずはその道を検討して頂くのが良いのかなと。 https://github.com/yakivmospan/github-wikito-converter
先ずはどんなものなのか理解するところから。
そうすることが多く推奨はされることが多いですが、特に制限があるわけでは無いです。 管理権限は必要ですが、任意のリポジトリ・ブランチを Github Pages として指定出来ます。 https://docs.github.com/ja/github/working-with-github-pages/creating-a-github-pages-site#creating-your-site
この辺りももう少しちゃんと読んでみます。。。
余談ですが、ルートパス・ルートアクセスと言う語はデザイナーさんから度々耳にしますが、 個人的にはよくわからない語という印象が大きく･･････ プログラマー界隈でも使われるのかな。
そうなんですね。。。 ちょっと気を付けよう。。。