Updating WebThings Documentation

Now that documentation is formally a module within the WebThings project I think it’s a good time to take a look at the variety of documentation we have and see what we can do to enhance it. At our monthly project meeting back at the end of March I highlighted that idea and pointed to proposal I’ve published on our wiki based on feedback I’d received to that point. I’d like to bring the topic to broader attention here and see what discussion there might be.

As you’ll see in the proposal the intent is to enhance the reader’s experience by unifying the documentation into one volume, streamlining navigation, introducing search, and adding a bit of visual style. Discussion at the monthly meeting was in favor of that generally, though one topic highlighted there merits further discussion here.

The proposal as written suggests combining user and developer documentation into one overall collection. That’s pretty straightforward given the approach and tools identified (e.g., MkDocs). However, it was suggested at the monthly meeting that we might be better served by keeping the user and developer documentation separate, and though something like MkDocs would be fine for the user documentation perhaps developer content should stay in wiki form as that’s more traditional for developer documentation and better suited for contribution from developers active with the project.

From a module ownership perspective I’m fine with either approach. I welcome feedback here, with the idea that we’ll make a decision and I’ll update the proposal on the wiki as needed, then set about the work. Happy to answer other documentation-related questions here too.

1 Like

I agree that clearly separating user docs from developer docs is important to usability.

1 Like