Re: Google Season of Docs

From: Cem Bassoy (cem.bassoy_at_[hidden])
Date: 2020-04-23 10:35:51

Am Do., 23. Apr. 2020 um 11:54 Uhr schrieb Alexander Grund via Boost <
boost_at_[hidden]>:

>
> >> maintainers to agree in a single tech to document anything.
> > Definitely.  No chance.
> >
> > Almost every library has 'done their own thing' in various way, either
> by using
> > a different tool, or by using an existing tool differently.
> FWIW: I'd welcome something more standard. Like:
> You want Doxygen: Use this setup (Jamfile/CMakeLists)
> You want Asciidoc: Use that
> BoostBook?: Here you go
>

I guess that this topic would not be the scope of GSoD.
However, I think you will find good examples for each approach in the Boost
libraries.

>
> I know there is no "one size fits all", but maybe a "use this for
> code-heavy and that for template heavy libraries."
>

> Or just any guideline. I was a bit lost when I added the documentation
> for Nowide. I didn't want to install 3 or 4 different tools and go
> through 3 conversions just to get some docu done. Especially not if B2
> magic is involved which can't be easily replicated in (e.g.) CMake
>

This is the crux of the story. If it is so complicated to integrate such a
toolchain or
multiple tools, you are automatically thinking about the "pain" of
using/linking and maintaing them.
Ultimately, the degree of necessity and urgency determines the course of
action -
the willingness to integrate a hard-to-maintain-toolchain.

If I think that Doxygen is not an ultimate necessity for my library and I
am using AsciiDoc,
I might want to postpone Doxygen-usage and the maintainance of a more
complicated toolchain
If it a big necessity for my library, I might want to switch to Sphinx with
exhale/breathe additions including doxygen or
search for or implement an addtional tool that can combine AsciiDoc with
Doxygen.

So, IMO, we do not need a howto for that as the howtos are already there (I
agree sometimes also hard to find).
With different libraries and requirements, time will show a convergence -
maybe with multiple convergence points.
I am not sure if there is a greatest common factor and if we can get
something like a common look for all libraries.

Are their parts of the Boost library documentation which could be
restructured/renewed - not directly affecting the libraries?

>
> Just my experience with current documentation workflow. If I got
> anything wrong: See it as exemplary how confusing it is ;)
>
> Alex
>
>
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>