<div dir="ltr"><div><div>tl:dr developer docs are now at <a href="http://docs.petsc.org">docs.petsc.org</a>, will be looking for help in moving the Users Manual</div><div></div></div><div><br></div>Hi PETSc dev -<div><br></div><div>I wanted to draw your attention to some work we've been doing with the documentation.</div><div><br></div><div>The new home for developer's documentation is</div><div><a href="https://docs.petsc.org/en/latest/developers/index.html">https://docs.petsc.org/en/latest/developers/index.html</a><br></div><div><br></div><div>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 <a href="https://gitlab.com/petsc/petsc/-/wikis/home">wiki</a>, as well (<a href="https://gitlab.com/petsc/petsc/-/issues/596">issue #596</a>).</div><div><br></div><div>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).</div><div><br></div><div>While this is hopefully useful for the developer docs, <b>the main point is to use this platform to get the Users Manual in a web-friendly format</b>. </div><div><br></div><div>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 <a href="https://docs.petsc.org/en/latest/developers/design.html">several chapters from the developers manual </a>that need attention: outdated information needs to be removed, formatting for tables/figures could be improved, and code snippets should <a href="https://docs.petsc.org/en/latest/developers/documentation.html#sphinx-documentation-guidelines">include directly from the PETSc source</a>, instead of duplicating it. We'll try to put together some concrete instructions on how to do the LaTeX-to-reStructuredText conversion shortly.</div><div><br></div><div>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 <a href="https://github.com/google/styleguide/blob/gh-pages/docguide/best_practices.md">here</a>). Docs should be very small, constantly pruned, and on display. </div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div><br></div></div>