Re: Things I Hate (Re: New Website)

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2024-04-16 17:52:18

On Tue, Apr 16, 2024 at 10:05 AM Robert Ramey via Boost <
boost_at_[hidden]> wrote:

> Best of all it, it could be expanded so that space for new pages
> can be provide.  Periodically we could argue about how the index should
> be structured while leaving the specific pages to the individuals that
> have the most interest in them.
>

The new site is very close to this. Almost all of the information is
organized into two "manuals":

User Guide: Everything needed for people who want to integrate Boost into
their projects
https://www.boost.io/doc/user-guide/index.html

Contributor's Guide: Everything needed for people who want to contribute to
Boost
https://www.boost.io/doc/contributor-guide/index.html

These are written in Asciidoc which is currently the most popular form of
markdown that has an extraordinarily high level of support in terms of
active development and tooling. You can see for example some of the source
for those manuals here:
https://raw.githubusercontent.com/boostorg/website-v2-docs/develop/user-guide/modules/ROOT/pages/release-process.adoc
https://github.com/boostorg/website-v2-docs/blob/develop/user-guide/modules/ROOT/pages/release-process.adoc

The Table of Contents on the side is generated from the navigation so this
is similar to what you are suggesting in terms of a generated table of
contents.

Probably the most important aspect of these new docs is not the content but
rather, the process. There are dedicated staff members who are responsive
to GitHub issues and continually work to improve the quality of the
information presented. For any current shortcomings, we have a workflow
that guarantees things will be addressed in finite time.

Thanks