Re-imagining Hubitat Documentation

💬 Lounge
1

Hello everyone, my first post! :champagne:

[TLDR] I'm having a go at re-imagining the Hubitat docs

image
image1080×636 82.7 KB
image
image1080×636 121 KB
image
image1080×636 98.8 KB
image
image1080×636 94.3 KB

443534534zxzvczxcv53

I'm a relative newcomer to Hubitat and automation in general but I'm enjoying setting up my automated home on the platform.

However, and I say this with love, I think your documentation is poor.

It varies between:

  • long fairly dense blocks of text
  • bullet point lists lasting entire pages
  • screen after screen showing one click, then another, then anoth...
  • a lot of nuanced information given prominence or mixed in with the basic useful stuff
  • giant sparsely populated lists after giant tocs
  • incomplete or missing in many cases (api, apps, drivers)
  • unversioned or updated prior to releases, but then incorrect for current users.
  • muddled or missing explanations

people have no doubt worked hard on putting them together, you are a small company and there are bugs to fix, communities to moderate, support requests and the never ending list of platform updates to write.

The docs though are most customer's first real interaction with the Hubitat brand and, well for me at least, it's just isn't a good experience.

The poor quality and lack of accessibility to the documentation must in and of itself generate support overhead I would guess.

If you build it, they will come...

I read this from someone in another thread about the docs.

I do apologise for being mean about your docs and I'm not one to lob in complaints and run away so I thought I'd have a go at it.

The site is available for eyeballs @ https://wwwlicious.github.io/hubdoc/

Now it's presumptive of me I know, not to mention still early stages.
I'm still sort of stubbing most of it out as there are a lot of docs to cover but mainly concentrating on fleshing out the developer docs and generating the large lists like capabilities, compat devices for easier maintenance and api docs from data and possibly auto-gen; but I thought I'd post this and perhaps get some general feedback.

Tell me more...

It supports multi-language, doc versioning, searching, mobile-friendly, crowd-sourced corrections and contributions without user account maintenance or ceding any editorial control, templating for generating docs from data files for ease of maintenance and more.

The tech...

  • It's hosted by github as a static GitHub pages site.
  • Built using Material for MkDocs which is very customizable.
  • Deployed via Github Actions.
  • Docs are mainly written in markdown just like posts in this forum,
  • It all built on OSS suitable for commercial use and doesn't cost anything to run either

So...to any hubitat folks reading:

  • If anyone at hubitat is like, yeah, I like this!
    Well you can have it FOC if there is interest. Message me and I can explain how its put together and sort that out.

  • If anyone at hubitat is like, omg, that cheeky sod, copyright infringement, theft, don't want
    That is totally cool too, I'm not trying to crush anyones grapes, I can remove it and just keep it all for myself offline. :wink:

I've left the repository private for now in the event that it's the second option so no one can fork/clone or edit.

If you are a hubitat user, especially someone who writes or wants to write apps or device drivers, perhaps leave a comment, feedback or likes on this post if you agree/disagree with me about the state of the current docs and if you like or don't like what I've built so far and prefer the github / markdown style of maintaining docs.

So in closing. Love the platform. Don't like the docs. Having a go myself at them :laughing:

11 Likes
2

I would be inclined to add to the documentation. See my previous suggestion SUGGESTION

1 Like
3

Thanks! This really needed to be done. I have spent way way too much time searching through the forums looking for various method calls I need. Or examples on how to do things. The SmartThings docs used to be a good reference, but that works less and less these days.

If people from the community are allowed to contribute, that would be awesome.

2 Likes
4

Thanks for the feedback. It’s valuable and appreciated.

The docs are built on Wikimedia today. That’s what we have control over, but are working on major changes right now that will improve accessibility and make the docs more approachable.

There’s much to do, but we hope you’re pleased with the improvements we’ve made when their ready. We agree this is important to improve and look forward to further feedback.

7 Likes
5

I do hope it's more than making the fonts bigger and giving desktop users the mobile version of some pages, which are the changes I've noticed recently. :slight_smile: (I keep thinking I adjusted the zoom in my browser...not trying to be snarky!)

I assume it is, and look forward to whatever those may be!

4 Likes