サイトデザインとテンプレートの更新

[dynamis]

現在 chirimen.org の更新が難しいという声があるが、その原因はいくつかあるように思います。

既に解消しているものはそう分かるように、解消できないものも緩和する方法があるものはそうしたいのでルールとドキュメントの整理をしたいです。

以下は私が見て思った現状とそれに対する提案です。合意が取れるようであれば How To を README なり /feedback ページなりに記載していきたいと思いますが如何でしょうか？

master を直接編集せずに PR を作らなければならないルール

github の 簡単な編集はどんどん master に直接コミットして事後報告・事後レビューも OK としても良さそうに思います (問題が起きるようなコミットが繰り返されるようであればその時に見直す前提で)。

また、PR を作るにしてもオンラインのブラウザ上で出来るという手順の説明を書いて、少なくとも主要なメンバーが気軽に更新できる雰囲気にしたいです。

jekyll のビルド環境を整えなければプレビューして編集・コミットが出来ない

ビルド環境の VM を作って頂いて大分やりやすくなったと思いますが、カジュアルにブラウザだけで編集出来る方がより望ましいです。大きなテンプレートの改変は開発環境を整えて行った方が良いとしても、比較的簡単なものならプレビューをしたい場合でもブラウザの操作だけで行いたいです。

そのため、Netlify の Deploy Preview 環境をセットアップしました。

• サンプルプルリク: Netlify での deploy preview の動作を確認するための PR #87
• Deploy Preview サイト: https://deploy-preview-87--chirimen-org.netlify.com/
• master のサイト (使ってない) https://chirimen-org.netlify.com/

ブラウザでファイルを編集してコミットするときに master ではなく PR として保存すれば数十秒後には自動でプレビューサイトまで自動で作成され、CHIRIMEN Slack の #github チャンネルに通知されるはずです。

ビルド環境無しでも編集できる How To ページを書いて、これでプレビュー・レビューなども必要に応じてできる体制として進めてはどうでしょうか。

jekyll のテンプレートがやや複雑でぱっと見では何をどう編集すれば良いか分からない

Web 開発者としてはこの程度のテンプレートは理解して編集できるのですが、正直初めてさんが編集するには余り直感的ではなく敷居が高いテンプレートになっている印象です。

md ファイルが各 URL ページに直接対応するデフォルト github pages とテンプレートファイルの組み合わせくらいにシンプルだとやりやすくなる気がします。

例えばチュートリアルサイトはデザインもシンプルすぎですが編集はかなりしやすいものにできたと思っています: https://tutorial.chirimen.org/feedback

現状のサイトが整理されていなくてどう手を付けて良いか分からない

サイトデザインと構成は直さないと手を付けにくいですね。何とかしたいです。

英語の併記が必要

同一ページへの併記をしている限り仕方ないですね。トップページなどは併記しつつも en/ja ディレクトリを分けて en ページの一部では google 翻訳へのリンクを張るという、現在の Tutorial ページのような逃げ方をするのもありかも知れません。

[dynamis]

結構前のミーティングですが、サイトの位置づけ自体については

• CHIRIMEN for Rasi3 etc 専用ではなく、過去のものも何処かしら残すし、プロジェクトのゴールなどには変更は無く、Web API の提案や標準化、それが動くオープン環境を既存ボードでも独自ボードでも動かせるようにすること
• 日本語専用ではなく英語ページも用意するスタンスは変えない

などが確認済みですので、みんなで編集しやすいようにはするが英語情報をなくさないようにするなどは配慮したシステムにしたい。テンプレ自体を他言語対応したものを採用するか、単に併記したり複数ページにするのか少し検討、提案 (というか多分勝手に採用して試験導入など) していきます。

[dynamis]

• 現状のテンプレートでのコードにタグを打つ
  • 既存サイトは単にアーカイブすることに
• ブランチを作ってテンプレ・デザインを更新してみる
  • テーマデザインの候補を挙げる http://jekyllthemes.org/ 等参照
  • SSG は Jekyll のままにしておく。github page や既存の tutorial との親和性というか、コミュニティ内でシステムは統一したいので
• 最低限のコンテンツの以降が終わって問題なければ切り替える

requirements:

• シンプル
• syntax highlight
• 他言語対応 (see 多言語対応してみる #1)

[saxAllan]

templete 候補
-http://jekyllthemes.org/themes/skinny-bones/
-http://jekyllthemes.org/themes/herringcove-theme/

[gurezo]

参考

• GitHub Pages が Jekyll 3.0 になり、ますますブログが書きやすくなった。

[gurezo]

2019.04.19 monthly meeting part19

[gurezo]

templete 候補
https://github.com/alexander-heimbuch/millidocs
https://github.com/blakadder/templates

サンプル
https://gurezo.github.io/

下記内容が良さそうなので、提案(README.mdより抜粋)
Simple documentation theme for Jekyll featuring Milligram CSS framework, PrismJS syntax highlighter and LunrJS search.

GitBook的なデザインも提案する理由

[dynamis]

ミーティングにて合意:

• 既存サイトは archive.chirimen.org に移す
• 新規サイトは既存サイトのことも Jekyll も忘れて作る

イントロ、誘導、Slack、ソーシャル、YouTube などへのリンク

[gurezo]

SNSリンクをトップページに配置

• facebook
• twitter
• github
• slack

[dynamis]

オープンハードウェアの設計情報も:
https://github.com/chirimen-oh/accessories

[gurezo]

素材格納フォルダ（Google Drive）
https://drive.google.com/open?id=0Bz4EqMFPIHqQRzJ3LVRyZExXWlU

上記ドライブの編集権限をほしい方は、 @gurezo までメールアドレスを下さい
※gmailアドレスが望ましいです。

[dynamis]

@gurezo オススメテーマを millidocs を i18n 対応させ markdown を githubpages 互換に設定して cloudinary の設定を入れてなど tutorial 同様の編集が出来るようにした上で Netlify に展開してみた:
https://chirimen-org.netlify.com/

テンプレートの動作的には多分大丈夫そうな気がする。問題があれば対応しつつ進める。コンテンツの用意に移る。

既存 gh-pages サイトのアーカイブ:
https://archive-chirimen-org.netlify.com/

[dynamis]

• millidocs 左上の全文検索は英単語完全一致のみで日本語だったり単語の一部だったりの検索が出来ないダメなやつだったので差し替えるか削除する。

[dynamis]

ちょっと書きかけた状態で様子を見てるがやはり少し寂しすぎる millidocs は partslist 的なものに使うとして、トップページなどは Skinny Bones とかにするといった mix にした方が良い。

https://mmistakes.github.io/jekyll-theme-skinny-bones/
これのトップとか記事一覧のデザインをパクって特定階層下では millidocs テーマのデザインで出すくらいの感じ。ライセンスは両方 MIT なので適当にやって問題なし。

[dynamis]

Raspi の基本的な情報へのリンク集ページも欲しいかも。

• ルールラボの GPIO ピン説明 https://tool-lab.com/make/raspberrypi-startup-22/

スターターキットに GPIO ピンの印刷版を同梱して参照先の URL が欲しくなっているという理由もある。

[dynamis]

サイト構成:

• top
  • about
    • コミュニティの目的、何をしているか、提供しているもの
    • 旧 chirimen.org アーカイブへのリンクなど
  • Raspberry Pi
  • Jetson (nano)
  • micro:bit
  • M5StickC (TBD)
  • TY51822r3
  • node
  • docs
    • Web GPIO/I2C API の簡単な紹介とリンク
    • tutorial サイトの紹介
    • Raspi の基本など外部情報
    • 事例集
      • WebIoT Makers, 慶応, 中央大学
      • 成果のドキュメント
  • partslist (旧 example ページと partslist を整理統合する)
    • LED
      • example コード, jsbin, csb, driver, 購入先、データシート etc...
    • Switch
    • 人感センサー
    • ... (その他 GPIO デバイス毎のページ)
    • ADT7410
    • ADS1015
    • ... (その他 i2c デバイス毎のページ)
    • neopixel driver
    • test board
    • その他 accessories
  • ideas (hacks? articles?)
    • 作品例とか記事とかを画像, URL, タイトルだけで一覧
  • contact (お問い合わせフォーム)
  • slack (link)

2階層目へのリンクはグローバルナビゲーション等に入れるイメージ

パーツリストページデザイン・内容:

例えば https://mmistakes.github.io/jekyll-theme-skinny-bones/articles/ をベースに

https://chirimen.org/chirimen-raspi3/gc/top/examples/
or https://tutorial.chirimen.org/raspi/partslist
のテキストくらいは含んだパーツリストを www.chirimen.org 上に用意する。

obniz の対応パーツリスト https://obniz.io/ja/sdk/parts のようなデザインは画像だけでわかりにくすぎる。サイトの雰囲気的には Johnny Five http://johnny-five.io/api/ http://johnny-five.io/examples/ くらいでも良いかも？

その他のサンプルの公募:

www.chirimen.org トップから誘導される Ideas なり Article なりのナビゲーションを作り、そこにドライバーの使い方だけではないいろんな事例をみんなで追加していく。
画像と URL さえあれば良い。追加申請はサイトへのプルリクか専用の issues を利用する。

[dynamis]

sd image を raspberry pi 公式サイト https://www.raspberrypi.org/downloads/ に掲載してもらえる場合はその案内ページも /raspi/download あたりに用意する
ref: chirimen-oh/chirimen#87

[dynamis]

技術書典で書いた原稿も一部歴史などについては参照・引用してサイトに掲載すると良さそう

@gurezo いいですよね？

[gurezo]

@dynamis 問題ナッシングです。