Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WoT-JP CG Webページの構成について #42

Closed
endouhhc opened this issue Dec 7, 2021 · 11 comments
Closed

WoT-JP CG Webページの構成について #42

endouhhc opened this issue Dec 7, 2021 · 11 comments
Assignees
@k-toumura
Labels
All CG全体に関係する話題 Deployment サイトと技術資料作成を行う Deployment TF 関連

Comments

@endouhhc
Copy link
Contributor

endouhhc commented Dec 7, 2021

WoT-JP CGのWebページに、様々なコンテンツが充実し始めています
訪問者が意図する内容を見つけやすいようにしていけるといいなと感じています

各ページでわかること・伝えたい内容を見つけやすいようにしたいです

例えばHueサンプルは #28
「既存デバイスの既存APIをWoT化するサンプルである」という旨などが
伝わるようにしたいです

例の構成

サンプルのカテゴライズについて、
用途ベースでの命名なども分かりやすいかと思います

  • WoT対応の環境センサをつくる（Raspberry Pi）
  • 既存のIoTデバイスをWoT化する（Hue 電球）

この際、各サンプルの言語・実装環境、使用ライブラリなどが
一覧できたりするといいかもしれません

サイドバー

細かいところでは、サイドバーのリンクについて、
クリックできるか、アコーディオンになっているか
チュートリアルと例（raspberry pi）の関係

などもアップデートの際に検討に加えていただきたいです
@ashimura ashimura added the Deployment サイトと技術資料作成を行う Deployment TF 関連 label Dec 8, 2021
@ashimura
Copy link
Contributor

ashimura commented Dec 8, 2021

related Issue #41

@k-toumura
Copy link
Contributor

コメントありがとうございます。確かに、「チュートリアル」の「Thingの作成」と、「例」の各種説明の区別がわかりづらいですね。

「例」の方は「チュートリアル」よりはあっさりとした説明となっているので、
「WoTの利用例」などのタイトルにした上で、次の階層はデバイスごとではなく用途ベースの命名として下記のような階層関係にするのはどうでしょうか:

  • WoTの利用例
    • 気圧センサーを作る (Raspberry Pi + BMP280)
    • 温湿度センサを作る (Raspberry Pi + SHT3x)
    • Hue電球をWoT化する (Hueブリッジ + Hue電球ホワイトグラデーション)
    • ロボットを制御する (myCobot 280)

そして、各ページの先頭に統一した書式で材料や言語を記載します。

  • ハードウェア
    • Raspberry Pi 3以降
    • BOSCH 気圧センサー BMP280
    • ジャンパワイヤ、ブレッドボードなど
  • ソフトウェア
    • Node-RED v2.0 以降
    • BME280制御用ノードモジュール (node-red-contrib-bme280)

利用例がサイドバーに入らないほど増えてきたら、今度は利用例をまとめたページを作ってサイドバーからはそのページへのリンクとする必要もありそうです。

@dynamis dynamis mentioned this issue Dec 8, 2021
Closed
@dynamis
Copy link
Collaborator

dynamis commented Dec 8, 2021

ページ名などをどうするか＆サイドバーでどう表記するか以外に

related Issue #41

で書いていたポイントをこちらに書き直します:

サイト構成について

  • トップページ (または案内ページ) をもう少し充実させて、本サイトでは何が何処に書かれているか分かるようにする (ナビゲーションをサイドバーだけに頼らない)
  • 仕様の位置づけであったり仕様の説明であったりするページを追加し、仕様の説明とチュートリアルや example が並ぶような形にする
    • チュートリアルや example に書かれていることは一部仕様説明などに書いて参照するだけにする所もあるかも知れない

サイトデザインについて

docsify デフォルトを今は使っているが、ドキュメントサイト用にもう少ししっかりしたテンプレートなどを採用する。具体的には Docusaurus v2 https://docusaurus.io/ ベースで適当なテンプレを選んで採用すると良いかと思っている (決まりではない、候補を選んで検討)

@k-toumura
Copy link
Contributor

サイト構成に関して: サイドバーに「ダウンストリーム」とあるのを「トランスレーション」にするのと、「ユースケース」も追加する必要がありますね。こちらも、コンテンツが増えてきたらあまりサイドバーに盛り込みすぎないほうが良いかもしれません。

@dynamis
Copy link
Collaborator

dynamis commented Dec 13, 2021

頂いた意見も踏まえて、WoT サイト再編案を書いてみました。

ページのリストを単に書くだけではなく、内容や構成の変更をどうしてそのようにするのかという理由を before/after のコメントとしても記載しています (ちょっと長くなって見にくいのは御容赦を)

構成案の方向性としてはこのような形で宜しいでしょうか (タイトルなどの細かな所は実際追加・更新しながら調整したいと思いますが、この案の時点でも更新後でも随時コメント頂ければ)。問題が無ければ

  • mycobot の例をマージして入れていく (以下のサイトマップに含めてないですが)
  • TD 概要の説明セクションを /raspithing から抜き出して /recs/td に移動させる
  • TD 仕様全体の説明を /recs をアップデートする形で更新して書いていく
  • switch bot のデバイスを使ったサンプルも追加する

といった所の追加・更新の執筆を進めつつ、何処かのタイミングで

  • トップページ、/about, /aboutcg, /event, /translation あたりの内容を整理・更新する
  • テンプレートシステムなどを変更して見た目やサイドバーの見せ方などを変える

というサイト全体の構成の変更作業を行うような形で進めようかと思います。如何でしょうか。

WoT サイト再編案

Before

  • / トップページ
    • 内容: サイトの簡単な案内文
    • コメント: トップページがもっとサイト全体の案内、何が何処にあるか分かる＆いま宣伝したいことや伝えたいことが記載されたページに変えられるべき。
  • はじめに
    • /about Web of Thingsについて
      • 内容: 作るには、Expose/Consume するには
      • コメント: WoT の意義・役割、多数ある WoT 関連仕様の位置づけ等についての説明がないため、「ホントの初めてさん」や「非エンジニア」はカバーできていない
    • /aboutcg Web of Things Japanese Community Groupについて
      • 内容: 設立経緯と参加申し込みの案内
      • コメント: 経緯は多分重要ではなく、何をしているか、どうやって議論に参加するか (W3C サイトの CG 登録の仕方ではなく github 記載の運営ポリシーと issue で議論することの案内) が書かれていることの方が必要な内容のハズ
  • デプロイメント
  • アウトリーチ
    • /event WoT-JP CG関連イベント
      • 内容: 開催予定/過去のイベントのリンク集
      • コメント: イベント案内はトップページに掲載した方が良い。過去のイベントは /aboutcg ページなどに残しておけば良い。
  • ダウンストリーム
    • /translation WoT韓国の翻訳 (ダウンストリーム活動)
    • 内容: (作成中) だけ
    • コメント: 成果物の翻訳レビュー中のものや TTC 標準のドキュメントへの案内は WoT 入門などの概要からすれば良いし、翻訳に協力する人向けの案内もトップページや /aboutcg に書くべきだろう
  • 関連文書
    • /recs W3C勧告など
      • 内容: リンク集
      • コメント: 現状、折角各仕様の説明コメントは入っているが全体像や位置づけについてまとめられていない。全体像を含めた形で仕様の在り方を説明したページにした上で、リンク集のような余り人が見に来ないところではなく、はじめに配下の WoT とは何かというイントロの中で WoT 仕様がどのようになっているかを説明するページにした方が良いのではないか
    • /misc その他・リンク集

After

  • / トップページ [updated]
    • 内容/変更点: WoT CG コミュニティサイトであること、サイトに掲載している内容の全体像、イベントなどの宣伝したいものの案内をここに入れる
  • WoT について
    • /about Web of Thingsについて [updated]
      • 内容/変更点: WoT の意義・役割などについて冒頭の説明をもう少し充実した上で、今の「作るには、Expose/Consume するには」のセクションがあり、更に興味を持ったら次の /recs や /recs/td などの仕様概説ページや /basic ページに誘導する形にする
    • /aboutcg Web of Things Japanese Community Groupについて
      • 内容: 設立経緯と参加申し込みの案内
      • コメント: 経緯は多分重要ではなく、何をしているか、どうやって議論に参加するか (W3C サイトの CG 登録の仕方ではなく github 記載の運営ポリシーと issue で議論することの案内) が書かれていることの方が必要な内容のハズ
  • /docs ドキュメント [new]
    • 内容: 元「デプロイメント」配下の各ページの内容・位置づけを整理したイントロページとする。仕様については /recs, /recs/td などを参照するようにという誘導も入れる。
    • コメント: サイドバーのタイトルだけで内容・対象デバイス・ライブラリなどの位置づけを読み取らせるのは無理があるドキュメント全体の案内ページを、「デプロイメント/アウトリーチ/ダウンストリームといった CG 組織上の理論はサイトの前面には出さず、読む人が知りたい内容・タイトル・構成としたい。
    • WoT 入門
    • チュートリアル
      • Thing の作成
      • Thing の利用
      • コメント: 仕様などの堅い説明を /docs/xxxxx でチュートリアルは /tutorial/xxxx という階層に入れるドキュメントサイトも多いが、ページ数もそう多くないので全部 /docs 配下で良いかな...
  • 実装例
  • /recs WoT 仕様の全体像 [updated]
    • 内容/変更点: 旧 recs の仕様リストリンクを元に、先日検討会内部での勉強会で色々な WoT 仕様の関連性や位置づけを説明したような、仕様全体の役割分担・ステータスなどを書いたページにする。そのうち重要な仕様については順次個別案内ページを追加していく
    • /recs/td WoT Thing Description とは [new]
      • 現状 TD はチュートリアル「RaspberryPiでThingを作る」ページの一部としてThing Descriptionの記述 に簡単に説明があるが、これを抜き出し独立させた上でもう少し仕様全体の説明を追加・充実させる。
      • TD とは何かというのはチュートリアルを読む/試す人だけが知りたいことではなく、皆が WoT とは何かを知ろうとする流れで読むべきなのでここに抜き出すということ
  • 関連リンク
    • /misc その他・リンク集
      • 内容/変更点: ここは既存の上記構成内で紹介しきれない外部サイトをとにかく全部入れていく。文書とも限らないので「関連文書」ではなく「関連リンク」くらいでしょうか。

@dynamis
Copy link
Collaborator

dynamis commented Dec 15, 2021 •
edited

大事なことを忘れいていました。contributors の掲載ページも必要です

  • /aboutcg/contributors [new]
    • 内容: 単純に各 TF のメンバーリストを集約したものにするか、本 Web サイトのコミッターリストにするか、内容をどうするかは要検討だが、CG 貢献者のリストはちゃんと掲載すべき。

追記: TF のメンバーリスト + コミッターリストでページを作る。以後は活動参加してくださる人がいれば順次追加

@dynamis dynamis added the All CG全体に関係する話題 label Dec 24, 2021
@hidessy hidessy mentioned this issue Jan 11, 2022
Merged
@dynamis
Copy link
Collaborator

dynamis commented Jan 18, 2022 •
edited

構成変更方針はある程度オンラインミーティングで説明・確認したのを受けて、具体的な変更作業リストを書いてみる:

例の構成
サンプルのカテゴライズについて、
用途ベースでの命名なども分かりやすいかと思います

WoT対応の環境センサをつくる（Raspberry Pi）
既存のIoTデバイスをWoT化する（Hue 電球）
この際、各サンプルの言語・実装環境、使用ライブラリなどが
一覧できたりするといいかもしれません
...
チュートリアルと例（raspberry pi）の関係

というところは

  • /docs ドキュメント [new]
    • 内容: 元「デプロイメント」配下の各ページの内容・位置づけを整理したイントロページとする。仕様については /recs, /recs/td などを参照するようにという誘導も入れる。
    • コメント: サイドバーのタイトルだけで内容・対象デバイス・ライブラリなどの位置づけを読み取らせるのは無理があるドキュメント全体の案内ページを、「デプロイメント/アウトリーチ/ダウンストリームといった CG 組織上の理論はサイトの前面には出さず、読む人が知りたい内容・タイトル・構成としたい。

と書いたとおり docs というページで全体を説明して分かり易くすると共に、サイドバーに出てくるナビゲーションメニューのタイトルを変更することで見通しやすくすることを想定。一旦やってみて意図があってるか見やすいかフィードバックを受ける。

@dynamis dynamis mentioned this issue Jan 20, 2022
Closed
This was referenced Feb 5, 2022
Merged
Merged
@dynamis
Copy link
Collaborator

dynamis commented Feb 14, 2022

WoT-JP CGのWebページに、様々なコンテンツが充実し始めています 訪問者が意図する内容を見つけやすいようにしていけるといいなと感じています

各ページでわかること・伝えたい内容を見つけやすいようにしたいです

例えばHueサンプルは #28 「既存デバイスの既存APIをWoT化するサンプルである」という旨などが 伝わるようにしたいです

例の構成

サンプルのカテゴライズについて、 用途ベースでの命名なども分かりやすいかと思います

  • WoT対応の環境センサをつくる（Raspberry Pi）
  • 既存のIoTデバイスをWoT化する（Hue 電球）

この際、各サンプルの言語・実装環境、使用ライブラリなどが 一覧できたりするといいかもしれません

@endouhhc 上記のご提案・ご指摘については #58 にて対応を進めましたが、如何でしょうか？次のデプロイプレビュー拝見頂いて、こちらなり PR 58 なりにコメント頂けると幸いです:
https://deploy-preview-58--wot-jp-cg.netlify.app/

@endouhhc
Copy link
Contributor Author

@dynamis

ありがとうございます！
上記2項目について、とても分かりやすいです

サイドバーについては継続検討と伺っております、よろしくお願いいたします
細かいところ、2点ご検討お願いします

  • 「実装例」について
    当面は「Thing の実装例」としておいた方がそろうかと考えました

  • サイドバーでの略称定義
    「WoTについて」 => 「Web of Things (WoT)について」
    などいかがでしょうか？
    冒頭に略称を説明しておきたいです

@dynamis dynamis mentioned this issue Feb 15, 2022
Closed
@dynamis
Copy link
Collaborator

dynamis commented Feb 15, 2022

@endouhhc 確認＆コメントありがとうございます。

分かり易くなったと満足頂けたようで安心しました。

サイドバーについては継続検討と伺っております、よろしくお願いいたします

こちらはサイドバーに限らずサイト全体のデザインやシステム更新ということで #59 として issue を立てました。

コンテンツ書き換え中にシステム変更は混乱するかもだし、コンテンツを書くことの方が優先順位は上と思いますので、本 issue にてコンテンツの内容整理が一段落した次のステップとして対応をして行ければと考えております (まだ少し先になりますが御容赦ください)。

細かいところ、2点ご検討お願いします

追加のご指摘ありがとうございます。
@hidessy PR 更新にて対応してください。

@dynamis dynamis mentioned this issue Feb 22, 2022
Open
@hidessy hidessy mentioned this issue Feb 25, 2022
Merged
@dynamis
Copy link
Collaborator

dynamis commented Jun 28, 2022

サイト全体でのページ構成の変更などの作業は完了済み、個別のページ改善の残件は個別に issue が経っているため続きは必要に応じて各 issue にて

https://github.com/w3c/wot-jp-cg/issues?q=is%3Aissue+is%3Aopen+label%3ADeployment

@dynamis dynamis closed this as completed Jun 28, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@k-toumura k-toumura

Labels
All CG全体に関係する話題 Deployment サイトと技術資料作成を行う Deployment TF 関連
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@dynamis @ashimura @k-toumura @endouhhc