-
Notifications
You must be signed in to change notification settings - Fork 41
Proposal: Updating WebThings Documentation
As the WebThings project has grown and evolved documentation has been contributed in a variety of locations across the project and in differing formats. In addition to an overall project documentation repository, user and developer oriented information also appears as part of repositories containing related source code, as well as in the project wiki. Using the documentation requires paging through different portions of the project web site and the wiki without benefit of any unified table of contents or search facility. There's also not been any editorial approach to documentation consistency so the structure, format, and styling varies widely.
Documentation is now a formal module within the project, for which David Bryant is module owner. This document briefly describes a proposal to unify WebThings project documentation and improve usability for end-users and developers alike, as an initial effort to treat it as a coherent unit. Achieving this will require moving some documents from their current repositories and, as suggested below, also would move some wiki content into the documentation module proper.
Feedback on this proposal is encouraged and welcomed. This page will be updated so as to reflect the state of the overall plan as well as the progress over time in carrying it out.
- “WebThings User Guide” -- User-oriented intro section of the README.md in the Gateway docs repository, largely a list of available user documents. Published as the top-level documentation page on the WebThings web site along with the Developer Guide (see below).
- “Gateway Getting Started Guide” -- Quick-start setup guide to help users get the Gateway installed and operational in a step-by-step fashion on a Raspberry Pi. Resides in the docs repository. Published as the top-level documentation page on the WebThings web site along with the User Guide (see above).
- “Gateway User Guide” -- More detailed user document for successfully using the Gateway on a Raspberry Pi. The “Gateway Getting Started Guide” refers to this document as a more detailed resource that covers features and functionality not highlighted in the getting started procedure. Resides in the docs repository. Published on the WebThings web site.
- “Getting Started Guide - Docker” -- README.md from the Docker Mozilla WebThings Gateway repository (gateway-docker). Intended to help advanced end users get a Docker-image based Gateway installation operational on ARM-based devices (e.g., Raspberry Pi).
- “Supported Hardware” -- wiki page enumerating devices supported for running the Gateway software itself, and as devices controlled by the Gateway
- “Tips” -- a collection of helpful wiki pages
- “WebThings Developer Guide” -- Developer-oriented intro section of the README.md in the Gateway docs repository. Published as the top-level documentation page on the WebThings web site. Mostly a list of links to available developer documents contained as source in various repositories and published in a range of locations including on the WebThings web site and in the WebThings Wiki. Subsections cover:
- WebThing API -- includes content from a variety of repositories, along with wiki content and specification documents
- WebThings Gateway - architecture, build instructions, translation, testing pre-release OTA updates, releasing an OTA update, and add-ons References info in the gateway repo README, several add-on repos, several example repos and several wiki pages.
- WebThings Framework -- Links to a number of repos for language-specific WebThings libraries provided by the WebThings project, though no documentation other than what’s in the README for those repos. Also links to third party libraries either just as repos or in some cases to documentation in those repos or on third-party websites.
- WebThings Cloud -- References documents in the registration server repo
- Tips -- References a variety of wiki pages
- External Resources -- References a couple of external blogs.
To enable full searchability and achieve consistency in structure and style, gather together a proper collection of user and developer documentation and manage it as such. Together this collection could be edited as a single unit and would be published in one physical location on the WebThings web site. User content and developer content would be separated as if in different volumes of a single encyclopedic work as if adjacent books on a shared shelf. Bringing all the desired information into a single structure would mean moving some content currently shared on wiki pages into the unified document set and onto the project web site (and so no longer in the wiki).
All content described below would be contained in the docs repository.
Happily there are good tools to help create and manage online project documentation. After some experimentation we propose to use MkDocs for WebThings project documentation. MkDocs is a static site generator that can produce an easily navigated, fully searchable web site experience from a hierarchically arranged set of markdown documents. A built-in theme and templating subsystem allows customization of the generated look and feel, and the resulting web-ready documentation can be published on any site.
Use of MkDocs would need to be incorporated into the build and deployment processes for WebThings so that updated documentation can be deployed simultaneously with new releases of project software. Documentation contributors, or at least a core set of managing contributors, would need to be comfortable creating and previewing updated content to be sure it is properly handled by a MkDocs-based build and deployment process. More specific details on these workflows will be provided and reviewed as part of the design phase of the documentation update effort (more below).
- Introduction -- Basic description of Gateway and a list of available user documentation. Replaces current “WebThings User Guide”. Resides in the docs repo. Likely a separate document though would need to decide how it relates to the README in the docs repo.
- Getting Started Guide - Raspberry Pi -- Currently “Gateway Getting Started Guide”, clarifying that it’s for the Raspberry Pi. Resides in the docs repo.
- Getting Started Guide - Docker -- Current “Getting Started Guide - Docker”. Propose moving it from the gateway-docker repo to the docs repo.
- Gateway User Guide -- Current “Gateway User Guide”. Resides in the docs repo.
- Supported Hardware -- Would take the current basic wiki page and turn it into a more user friendly document with photos, etc. An initial attempt at this exists but needs considerable attention.
- Tips -- Created by importing (moving) helpful tips contributed as wiki pages. It will still be possible to contribute tips as pages in the project wiki, some of which may over time also move into the primary documentation collection.
A unified collection of developer documentation with the following chapters:
- WebThings Gateway and Add-ons - Information about the architecture and implementation of Gateway, and useful in contributing to the Gateway as a developer. Proposed to be a new document in the docs repository drawing from the following current resources:
- Gateway architecture -- At the outset, based on the existing Gateway Architecture wiki page through could use a better block diagram such as this one.
- Build instructions -- Extracted from the README in the gateway repository
- Creating a new translation -- Moved from the wiki
- Testing and releasing OTA updates -- Moved from the wiki
- Introduction to add-ons -- Moved from a document (guidelines.md) in the addon_list repository
- Creating an add-on -- Moved from the wiki
- Configuring an add-on -- Moved from the wiki
- Publishing an add-on -- Extracted from the README in the addon_list repository
- Add-on examples -- These examples are currently in three different repos: example-adapter, example_notifier, and example_extension. There’s no real documentation for them there, though there are pointers to some Hacks blog posts about them. Propose creating some documentation about them here in the docs repo and mentioning that in the README in those repos.
- Add-on APIs -- documentation for building add-ons for Node.js (as Typescript) and Python. Separate repos provide reference source (gateway_addon_node and gateway_addon_python) respectively, with explanatory documentation in the form of a Hacks blog post from February 2018. Could extract material from that blog post into a stand-alone document to include in the repo here. Also links to wiki pages on Adapter IPC and the Debug controller, both of which could be extracted and included in the docs repo directly.
- NOTE: Combining various wiki pages, README info, and docs isn’t a bad first start, but this collection of info should get some significant attention to edit and extend it into a more complete overview of the Gateway.
- WebThings Framework -- a collection of libraries useful in creating WebThings in a variety of programming languages and environments, each in a separate repo. Also includes links to third party libraries housed externally. As a starting point it could be what’s available today namely a landing page at https://webthings.io/framework/, which points at a section in the documentation that’s just links to these language-specific WebThings Framework library repos:
- Node.js
- Python
- Java
- Rust
- Arduino
- MicroPython
- WebThings Cloud -- Documentation about the WebThings Registration Server, currently packaged as separate markdown documents in the registration_server repo.
- Tips -- a collection of wiki pages that would be extracted into a unified markdown document and retained in the docs repo.
Initial experimentation combining and adapting existing WebThings documents (as markdown) for MkDocs have been very encouraging. Only modest editing has been necessary to achieve reasonable consistency in appearance and document structure, mostly relating to heading levels and embedded links to other documents or document sections. The built-in search capability generated by MkDocs seems very appealing. Technically there do not seem to be any major obstacles in bringing the identified existing content together into a highly usable unified collection.
The idea of moving documents from other repositories needs to be reviewed with the maintainers of those repositories so the associated overall development workflow isn't adversely impacted and document maintenance and the new MkDocs-based generation process is workable for all involved. Similarly moving existing wiki pages into the docs repository needs to be verified with the users who contributed and maintain those pages today.
It will also be important to describe and test the way in which MkDocs can be incorporated into the formal build, validation, and deployment of WebThings project software, especially the Gateway. A combination of manual and automated efforts are involved today in getting documentation published on the WebThings web site and those efforts will need to change (hopefully for the better).
These considerations motivate a thorough prototyping effort as well as review with module owners and contributors of today's existing documentation. Those results will allow a more detailed plan and project timeline to be produced, which can then appear here as an update to this overall proposal. Feedback and suggestions are welcomed.