Re: Recommendations for documentation authors

From: Andrzej Krzemienski (akrzemi1_at_[hidden])
Date: 2024-01-02 15:13:48

wt., 2 sty 2024 o 12:52 Andrey Semashev via Boost <boost_at_[hidden]>
napisał(a):

> On 1/2/24 11:55, Andrzej Krzemienski via Boost wrote:
> > Hi Boost Developers,
> > And a happy New Year (at least for those who recognize the Gregorian
> > calendar).
> >
> > While I consider improving the documentation quality of some Boost
> > libraries, I wonder if there are any tool or workflow recommendations for
> > the library authors regarding the documentation. I know we do not force
> any
> > specific tool or format, so I am only asking about recommendations.
> >
> > I note that page https://www.preview.boost.org has at
> >
> https://www.preview.boost.org/doc/contributor-guide/docs/documentation-guidelines.html
> > the following:
> >
> >> The format for documentation on the new website is AsciiDoc Syntax Quick
> > Reference
> > <https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/>.
> >
> > Should I treat it as a recommendation to use AsciiDoc? I note that quite
> a
> > few new libraries choose it. I also see the advantage: you need no
> special
> > tool for it: a simple web browser knows how to format it.
> >
> > But I found the documentation of libraries that use adoc to be
> > uncomfortable to read. I do not know if this is the tool itself or maybe
> > the correlation between the choice of the tool and the devotion to
> > documentation quality, or maybe something else. It is quite subjective.
> The
> > older libraries' documentation (using BoostDoc) seemed more friendly and
> > easier to navigate. But to write and maintain such documentation is a
> > challenge. Last year something broke in my pipeline (QuickDoc, xstlproc)
> > and to this day I am not able to determine what it is. So, relying on too
> > complex flows, which become obsolete over time, also doesn't seem like a
> > good idea.
> >
> > I wonder if any of you have similar thoughts, and if you can recommend
> > something for writing good quality and user friendly documentation.
>
> To me, QuickBook is the most powerful tool for writing documentation, so
> I'm not going to recommend anything new. As the changelog says, the
> latest version supports direct HTML output, but I haven't tried it. I
> imagine, it should work for simple docs without BoostBook/DocBook
> specific features.
>

So, when you are recommending QuickBook, does this also imply
BoostBook/DocBook, or are you treating them as separate tools?

Regards,
&rzej;

>
> I think, it would be very useful to continue improving QuickBook, in
> particular to support additional output formats, maybe even AsciiDoc. We
> have lots of documentation written in it, and new libraries use it as well.
>
> Perhaps, if you post some details about your problems with QuickBook,
> someone will be able to help.
>
>
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost
>