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...
On Saturday, December 31, 2022 at 2:36:26 PM UTC-8 Tom Keffer wrote:
> 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.
>
>
>
--
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 [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/weewx-development/64f2af75-85ac-423f-a93c-5435356029cbn%40googlegroups.com.
