WeeWX docs

[Tom Keffer]

Starting a new thread, devoted to the WeeWX docs.

Here's another example of some nice docs done with mkdocs. In particular, what attracted me is the ability to do tabbed displays with a minimum of hassle. https://pdm.fming.dev

By contrast, doing it in HTML is an exercise in masochism.

[Greg Troxel]

I think the big thing is for the tooling to be Free, to not have
nonportable language dependencies (haskell, rust) and to already be
widely packaged. I think this fits the bill - looks like just python
and I built and installed it from pkgsrc with no hassles.

[Vince Skahan]

Some more examples...

• Rocky Linux has quite the elaborate document on how to do slick formatting ala their style guide at https://docs.rockylinux.org/guides/contribute/rockydocs_formatting/ 
• Rocky Linux's left-hand nav column is a little too complicated for my eyes and assume users know too much in order to actually find the answer to your question. 
• Pihole takes a bit simpler approach at https://docs.pi-hole.net but it's a much simpler package than WeeWX
• I liked the PDM look'n'feel that combines the two approaches and adds the nice top menu for frequently used main categories.
• The PDM launch page synopsis ala 'what IS this package anyway' is kinda nice too.

But as somebody said earlier, look'n'feel is easy once the hard part (the writing) is done.

Personally, I find it currently difficult to keep track of what's in the wiki vs. this guide vs. that guide vs. the FAQ vs. that google forum thread, and the existing docs are perhaps a bit too developer-centric for most folks so there're pretty daunting for new users.   The meat of the docs is almost certainly almost all out there already if you can find it.

Perhaps some discussion about what a documentation hierarchy might look like would help as a starter ???

FWIW - I'd start with something like:

• what is it  - a gentle introduction in very layman's terms
• getting your feet wet - how do you install and run it on typical platforms in its default (Simulator) mode
• customizing it - start simple moving up in complexity starting with editing weewx.conf to turn things on/off etc.
• adding to it - find and install existing extensions/skins/etc that are out there already
• extending it - how to 'write' and package your own skins, extensions, services, etc.
• developer notes - all the low-level internals, python data structures, etc. that 99% of the people never need to know
• and of course 'how to report a problem' so others can try to help

So to me it's not that different than what's there now, just with a nice clean rewrite and reorganized cut/paste in a modern mkdocs interface...

• a nice menu structure in the docs
  • quick links in the top menu for download, sources, etc.
  • a relatively simple left-hand column top-level navigation menu
• a brief start-here top-level page
  
  • what is weewx
  • how are these docs organized
  • a page explaining and linking to the google groups
• a short getting started guide
  • what platforms does it work on
  • a brief glossary of skin/extension/service/etc.
  • picking an installation method
  • installing it on typical platforms in Simulator mode
• a somewhat longer user guide with categories ordered to move up in complexity, most typical things first
  • simple things like turning things on/off etc.
  • installing/uninstalling/enabling/disabling skins+extensions
• a not-too-long developers guide
  • how do you write and package a skin/service/extension
• a much longer as needed internals guide or appendix to the developers guide
  • all that detailed threading, architecture, and data structures internals stuff

I'd be willing to mock up a skeleton page or two in mkdocs and post a screenshot if there's interest...

[Tom Keffer]

"Perfect is the enemy of good."

My goal is to finish the V5 documentation, not rewrite the docs. Using mkdocs will speed that process because markdown is so much quicker to write in than raw HTML. If it also gives the docs a nice new facelift for nearly free, so much the better. 

I do agree that the User's and Customization guides are getting pretty long and cumbersome, but they work. Overall, the docs are "good enough." If someone wants to completely reorganize them, I'm open to the idea, but it won't be me! I'd rather go sailing.  :-)

--
You received this message because you are subscribed to the Google Groups "weewx-development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to weewx-developm...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/weewx-development/64f2af75-85ac-423f-a93c-5435356029cbn%40googlegroups.com.

[Doug Jenkins]

I have already rewritten the user guide for v4.9 in markdown today. It is a straight text conversion with markdown to mimic what the docs site looks today.

Will post my branch to Vince's repo later today.

We need to use the versioning of mkdocs instead of splitting the document tree by version. That is the correct way of doing things.

DDJ

To view this discussion on the web visit https://groups.google.com/d/msgid/weewx-development/CAPq0zEAOEmL_13EwF_-ugFioujeEvQ37kQOtvSBCBZknDM9Utg%40mail.gmail.com.