[petsc-dev] Developers Documentation and Metadocumentation

[Patrick Sanan]

tl:dr developer docs are now at docs.petsc.org, will be looking for help in
moving the Users Manual

Hi PETSc dev -

I wanted to draw your attention to some work we've been doing with the
documentation.

The new home for developer's documentation is
https://docs.petsc.org/en/latest/developers/index.html

It currently includes all the information from the Developers Manual and
the developers page on the website. The aim is to migrate all the
information from the wiki <https://gitlab.com/petsc/petsc/-/wikis/home>, as
well (issue #596 <https://gitlab.com/petsc/petsc/-/issues/596>).

This is built with Sphinx and ReadTheDocs, which means that it should be
easy to contribute to and edit. Note that ReadTheDocs gives you a handy
menu in the bottom right which lets you navigate directly to the
reStructuredText (simple markup) source on GitLab, which should allow for
quick fixes (label docs-only).

While this is hopefully useful for the developer docs, *the main point is
to use this platform to get the Users Manual in a web-friendly format*.

Towards that aim, what we'll most need is for people to get involved in
porting chapters of the Users Guide. Just moving the existing information
is fine, but better is if an expert can update the information (ideally
making shorter) as they transfer it. A good primer for this is that there
are several chapters from the developers manual
<https://docs.petsc.org/en/latest/developers/design.html>that need
attention: outdated information needs to be removed, formatting for
tables/figures could be improved, and code snippets should include directly
from the PETSc source
<https://docs.petsc.org/en/latest/developers/documentation.html#sphinx-documentation-guidelines>,
instead of duplicating it. We'll try to put together some concrete
instructions on how to do the LaTeX-to-reStructuredText conversion shortly.

Finally, I will take this opportunity to soapbox about how I think we
should approach documentation. I am very taken with the analogy with a
bonsai tree (which I got from here
<https://github.com/google/styleguide/blob/gh-pages/docguide/best_practices.md>).
Docs should be very small, constantly pruned, and on display.

In a lot of ways, documentation is just like code. Don't add it unless it
serves a very clear purpose, realize that maintainability burden scales
with size, don't duplicate things, make it clean and minimal, think about
who your audience/users are, try to predict ways it will break later on,
etc.

One way that's it's very different from code is that it doesn't have to be
100% correct. Breaking the docs (briefly) is not catastrophic and is easily
detected. Thus, there's more room for boldness, quick integration, and
contributions from less-experienced people.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20200409/ecc29d7e/attachment-0001.html>