ashimura
commented
2 years ago related Issue #41
Closed endouhhc closed 2 years ago
ashimura
commented
2 years ago related Issue #41
k-toumura
commented
2 years ago コメントありがとうございます。確かに、「チュートリアル」の「Thingの作成」と、「例」の各種説明の区別がわかりづらいですね。
「例」の方は「チュートリアル」よりはあっさりとした説明となっているので、 「WoTの利用例」などのタイトルにした上で、次の階層はデバイスごとではなく用途ベースの命名として下記のような階層関係にするのはどうでしょうか:
そして、各ページの先頭に統一した書式で材料や言語を記載します。
利用例がサイドバーに入らないほど増えてきたら、今度は利用例をまとめたページを作ってサイドバーからはそのページへのリンクとする必要もありそうです。
dynamis
commented
2 years ago ページ名などをどうするか＆サイドバーでどう表記するか以外に
related Issue #41
で書いていたポイントをこちらに書き直します:
docsify デフォルトを今は使っているが、ドキュメントサイト用にもう少ししっかりしたテンプレートなどを採用する。具体的には Docusaurus v2 https://docusaurus.io/ ベースで適当なテンプレを選んで採用すると良いかと思っている (決まりではない、候補を選んで検討)
k-toumura
commented
2 years ago サイト構成に関して: サイドバーに「ダウンストリーム」とあるのを「トランスレーション」にするのと、「ユースケース」も追加する必要がありますね。こちらも、コンテンツが増えてきたらあまりサイドバーに盛り込みすぎないほうが良いかもしれません。
dynamis
commented
2 years ago 頂いた意見も踏まえて、WoT サイト再編案を書いてみました。
ページのリストを単に書くだけではなく、内容や構成の変更をどうしてそのようにするのかという理由を before/after のコメントとしても記載しています (ちょっと長くなって見にくいのは御容赦を)
構成案の方向性としてはこのような形で宜しいでしょうか (タイトルなどの細かな所は実際追加・更新しながら調整したいと思いますが、この案の時点でも更新後でも随時コメント頂ければ)。問題が無ければ
といった所の追加・更新の執筆を進めつつ、何処かのタイミングで
というサイト全体の構成の変更作業を行うような形で進めようかと思います。如何でしょうか。
dynamis
commented
2 years ago 大事なことを忘れいていました。contributors の掲載ページも必要です
追記: TF のメンバーリスト + コミッターリストでページを作る。以後は活動参加してくださる人がいれば順次追加
dynamis
commented
2 years ago 構成変更方針はある程度オンラインミーティングで説明・確認したのを受けて、具体的な変更作業リストを書いてみる:
例の構成 サンプルのカテゴライズについて、 用途ベースでの命名なども分かりやすいかと思います
WoT対応の環境センサをつくる（Raspberry Pi） 既存のIoTデバイスをWoT化する（Hue 電球） この際、各サンプルの言語・実装環境、使用ライブラリなどが 一覧できたりするといいかもしれません ... チュートリアルと例（raspberry pi）の関係
というところは
- /docs ドキュメント [new]
- 内容: 元「デプロイメント」配下の各ページの内容・位置づけを整理したイントロページとする。仕様については /recs, /recs/td などを参照するようにという誘導も入れる。
- コメント: サイドバーのタイトルだけで内容・対象デバイス・ライブラリなどの位置づけを読み取らせるのは無理があるドキュメント全体の案内ページを、「デプロイメント/アウトリーチ/ダウンストリームといった CG 組織上の理論はサイトの前面には出さず、読む人が知りたい内容・タイトル・構成としたい。
と書いたとおり docs というページで全体を説明して分かり易くすると共に、サイドバーに出てくるナビゲーションメニューのタイトルを変更することで見通しやすくすることを想定。一旦やってみて意図があってるか見やすいかフィードバックを受ける。
dynamis
commented
2 years ago WoT-JP CGのWebページに、様々なコンテンツが充実し始めています 訪問者が意図する内容を見つけやすいようにしていけるといいなと感じています
各ページでわかること・伝えたい内容を見つけやすいようにしたいです
例えばHueサンプルは #28 「既存デバイスの既存APIをWoT化するサンプルである」という旨などが 伝わるようにしたいです
例の構成
サンプルのカテゴライズについて、 用途ベースでの命名なども分かりやすいかと思います
- WoT対応の環境センサをつくる（Raspberry Pi）
- 既存のIoTデバイスをWoT化する（Hue 電球）
この際、各サンプルの言語・実装環境、使用ライブラリなどが 一覧できたりするといいかもしれません
@endouhhc 上記のご提案・ご指摘については https://github.com/w3c/wot-jp-cg/pull/58 にて対応を進めましたが、如何でしょうか？次のデプロイプレビュー拝見頂いて、こちらなり PR 58 なりにコメント頂けると幸いです: https://deploy-preview-58--wot-jp-cg.netlify.app/
endouhhc
commented
2 years ago @dynamis
ありがとうございます！ 上記2項目について、とても分かりやすいです
サイドバーについては継続検討と伺っております、よろしくお願いいたします 細かいところ、2点ご検討お願いします
「実装例」について 当面は「Thing の実装例」としておいた方がそろうかと考えました
サイドバーでの略称定義 「WoTについて」 => 「Web of Things (WoT)について」 などいかがでしょうか？ 冒頭に略称を説明しておきたいです
dynamis
commented
2 years ago @endouhhc 確認＆コメントありがとうございます。
分かり易くなったと満足頂けたようで安心しました。
サイドバーについては継続検討と伺っております、よろしくお願いいたします
こちらはサイドバーに限らずサイト全体のデザインやシステム更新ということで #59 として issue を立てました。
コンテンツ書き換え中にシステム変更は混乱するかもだし、コンテンツを書くことの方が優先順位は上と思いますので、本 issue にてコンテンツの内容整理が一段落した次のステップとして対応をして行ければと考えております (まだ少し先になりますが御容赦ください)。
細かいところ、2点ご検討お願いします
追加のご指摘ありがとうございます。 @hidessy PR 更新にて対応してください。
dynamis
commented
2 years ago サイト全体でのページ構成の変更などの作業は完了済み、個別のページ改善の残件は個別に issue が経っているため続きは必要に応じて各 issue にて
https://github.com/w3c/wot-jp-cg/issues?q=is%3Aissue+is%3Aopen+label%3ADeployment
WoT-JP CGのWebページに、様々なコンテンツが充実し始めています 訪問者が意図する内容を見つけやすいようにしていけるといいなと感じています
各ページでわかること・伝えたい内容を見つけやすいようにしたいです
例えばHueサンプルは https://github.com/w3c/wot-jp-cg/issues/28 「既存デバイスの既存APIをWoT化するサンプルである」という旨などが 伝わるようにしたいです
例の構成
サンプルのカテゴライズについて、 用途ベースでの命名なども分かりやすいかと思います
この際、各サンプルの言語・実装環境、使用ライブラリなどが 一覧できたりするといいかもしれません
サイドバー
細かいところでは、サイドバーのリンクについて、 クリックできるか、アコーディオンになっているか チュートリアルと例（raspberry pi）の関係
などもアップデートの際に検討に加えていただきたいです