Re: Updates: need doc reviews, Docker changes, beta release of 2.3.0

On Sun, May 14, 2023 at 04:09:15PM -0400, John P. Rouillard wrote:

> Speaking of enhanced docs, I have done some restructuring, cleanup and
> re-styling of the docs. There is one more major change to come before
> release:
> 
>    Moving the top of customizing.html to a separate reference.html doc.
> 
> Everything on that page before the Examples section will be moved.  I
> am trying to rework the docs according to the diataxis
> (https://diataxis.fr/) framework. I can use help with this. If anybody
> has friends who are into documentation (tech writers for example) who
> would like to help out I would appreciate it if you mention this to
> them.

Nice!
As far as I understand this, diataxis is a way to structure
documentation for better human consumption, not a framework for
formatting documentation?

> I have also overhauled the styles for the docs.  I have gotten
> feedback from a few of people that the docs are a "wall of text",
> "unusable", and "looks old" which drive away possible users. I hope
> some of the re-design and change to diataxis will help people discover
> the information they need to run Roundup more easily and give them the
> confidence to use it.
> 
> Please provide feedback on the look and feel of the new docs. Compare
> the new look:
> 
>   https://www.roundup-tracker.org/dev_docs/
> 
> to the current:
> 
>   https://www.roundup-tracker.org/
> 
> The goal is to increase use of Roundup by making the docs more
> readable and scanable.
[...]

How about moving to Sphinx sooner or later?
I've just completed the move of pgapack (a genetic algorithm lib I'm
maintaining) to Sphinx -- the project is in C and has a separate python
wrapper, see https://pgapack.readthedocs.io/en/latest/
This used to be documentation in LaTeX (from the 1990s).

Of course there are other style sheets than the one featured by
readthedocs.

Ralf
-- 
Dr. Ralf Schlatterbeck                  Tel:   +43/2243/26465-16
Open Source Consulting                  www:   www.runtux.com
Reichergasse 131, A-3411 Weidling       email: [email protected]