Docs v2

[benfrancis]

This is a long overdue complete re-write of the WebThings documentation site, using Mkdocs.

I have written a comprehensive user guide for WebThings Gateway, some basic documentation for the WebThings Framework copied from the website, and a basic introduction to the W3C Web of Things (which I'd like to build on).

Mkdocs has a mkdocs gh-deploy command which makes it very easy to push a rendered static HTML version to GitHub Pages, and the "Read the Docs" theme I've used has built-in features like side-bar navigation and search. You can see a rendered copy of my fork here.

There's a lot of content here, so proof-reading is gratefully accepted!

[disquisitioner]

Awesome, @benfrancis -- thank you for doing that! I'll read through everything and leave comments. I appreciate you thinking of me as a reviewer. (Also, thanks for the pointer to the rendered instance of your fork!)

[disquisitioner]

To make steady progress and facilitate discussion I'm starting out just reading the new documents for general content and flow and not testing things step by step (e.g., by doing a clean install following the "First Time Setup" section). Rather than try and do this file by file (as there are a lot of file changes) I'll recap here my comments from having gone through the "WEBTHINGS GATEWAY" first big section of the new docs:

WEBTHINGS GATEWAY
Installation

• Has anyone had a chance to test using the RPi 5? "Supported Hardware" in the Gateway section of the docs links to a list on the wiki which doesn't mention the Raspberry Pi 5 but I'm sure someone is going to ask...
• The Note referring to Raspberry Pi 3 having Wi-Fi and Bluetooth could also mention RPi 4
• I suspect we've not had many folks note this as an issue, but the fact you can only configure a custom subdomain for your gateway at installation feels like something we should call out in the UI as well as in the docs. It's mentioned as a note in Section 2 of "First Time Setup" in the docs and again in "Settings" under "Remote Access" but the first time setup UI itself just says "Skip". If it's worth mentioning twice in the docs...

Settings

• The "Two-factor Authentication" section mentions an "Enable two-factor authentication" checkbox at the bottom of the Edit User screen but the example Edit User screen shown in the docs just above that section doesn't include that checkbox. It does show in a screen shot below the cited text (along with the QR code) but I'm not sure how that fits in with the "Edit User" screen as shown.
• Does the list of available add-ons automatically update as part of the Gateway keeping itself up to date (should you enable that feature)? There is a note saying that add-ons are updated when a new version is submitted, so perhaps that also means completely new add-ons are added to the list shown in the "Add-ons" settings? I wasn't sure...
• The "Updates" section highlights that Gateway updates happen automatically only if you've installed it "...using a Raspberry Pi OS-based image from our website." Perhaps "website" there could be a link to the site?
• I love the "Warning: Here be dragons!" comment in the Developer section of Settings.

I'll go work on the "WEBTHINGS FRAMEWORK" section next. Thanks again for doing this, @benfrancis. Such a lot of work involved in a full update of the entire docs...

[benfrancis]

Hi @disquisitioner, thank you very much for taking the time to review this.

• Has anyone had a chance to test using the RPi 5?

Yes, Tijmen mentioned in the chat that he has made some progress porting Candle (a downstream fork of WebThings) to Raspberry Pi 5. However, it requires Raspberry Pi OS Bookworm as a base operating system and a bunch of other potentially backwards incompatible changes. So until we can figure out a solution Raspberry Pi 5 is not yet supported. I have added a note to the wiki, and to the documentation.

• The Note referring to Raspberry Pi 3 having Wi-Fi and Bluetooth could also mention RPi 4

Done.

• I suspect we've not had many folks note this as an issue, but the fact you can only configure a custom subdomain for your gateway at installation feels like something we should call out in the UI as well as in the docs. It's mentioned as a note in Section 2 of "First Time Setup" in the docs and again in "Settings" under "Remote Access" but the first time setup UI itself just says "Skip". If it's worth mentioning twice in the docs...

I've filed WebThingsIO/gateway#3112

Ideally we would just implement WebThingsIO/gateway#1052 instead.

See also: WebThingsIO/gateway#82 which covers configuring a custom domain.

• The "Two-factor Authentication" section mentions an "Enable two-factor authentication" checkbox at the bottom of the Edit User screen but the example Edit User screen shown in the docs just above that section doesn't include that checkbox. It does show in a screen shot below the cited text (along with the QR code) but I'm not sure how that fits in with the "Edit User" screen as shown.

This is one of the features that was implemented during the brief window that I wasn't involved. For some reason the checkbox actually appears underneath the "Save" button and was off-screen in the screenshot. This is very confusing but I suspect it was designed this way because the checkbox takes effect as soon as you check it, rather than after you click save. This UI could do with some improvement, but in the meantime I've added an additional screenshot which makes it clearer where to find the checkbox.

• Does the list of available add-ons automatically update as part of the Gateway keeping itself up to date (should you enable that feature)? There is a note saying that add-ons are updated when a new version is submitted, so perhaps that also means completely new add-ons are added to the list shown in the "Add-ons" settings? I wasn't sure...

The list of add-ons is dynamically fetched from the internet each time the add add-on screen is loaded. This is independent of any updates to the gateway application and not something you can disable. It's probably not super important to explicitly mention this, but I have tweaked the wording slightly to make it clearer that you will always see the "latest" list of available add-ons.

• The "Updates" section highlights that Gateway updates happen automatically only if you've installed it "...using a Raspberry Pi OS-based image from our website." Perhaps "website" there could be a link to the site?

Done.

I'll go work on the "WEBTHINGS FRAMEWORK" section next.

Thank you. FWIW that section is just directly copied and pasted from the framework page on the website, so there shouldn't be too much to do there. There's a lot of scope to expand this section to be more useful.

The W3C Web of Things section is currently just one page, but I hope to expand that over time and eventually turn it into the MDN of the Web of Things!

[hwine]

Great stuff! My one comment is that there are a few features where screen real estate is critical. It might be useful to mention that at the top of the sections, so folks don't become frustrated.

In my experience, the 2 features needing "tablet or larger" resolution are:

• floorplan
• rule editing

[disquisitioner]

Coming back to this thread after the holidays, I've completed review of the remainder of the new documents. Everything looks good to me, and though I'm not sure what schedule there may be for pushing this documentation update relative to any implementation itself, I don't see why this new documentation shouldn't be deployed as a improvement over and replacement for the current version. I'll approve this PR in case that helps that work move forward but am happy to discuss further if relevant.

Thanks again for doing this work, and for asking for feedback. (It's good to see you felt like keeping the Mkdocs implementation was a reasonable thing to do.)

[disquisitioner]

Thanks for undertaking this update, and for the opportunity to review. I've made a few comments elsewhere, am satisfied with the responses provided, and am pleased to approve this PR.