<div dir="ltr"><div>A big problem with documentation is that it goes out of date. This quickly takes something that was useful to something which is actually harmful. Showing the user things that don't work exactly as described is worse than showing them nothing.</div><div><br></div><div>So, it's good to aspire to writing docs in as future-proof a way as possible, especially given the broad scope and rapid rate of change in PETSc.<br></div><div><br></div><div>One step in this direction that we use currently is to avoid including explicit code blocks and output [2], but rather excerpt from the src/ tree for both code and the same output used for the test suite.</div><div><br></div><div>An example of where this is done is in the classic "hand-on" tutorials [1]: these used to be part of an HTML page with the output inline, but now the source uses syntax like this:<br></div><div><br></div><div><div style="color:rgb(0,0,0);background-color:rgb(255,255,254);font-family:Menlo,Monaco,"Courier New",monospace;font-weight:normal;font-size:12px;line-height:18px;white-space:pre"><div><span style="color:rgb(0,0,0)">   .. literalinclude:: /../src/ksp/ksp/tutorials/output/</span><span style="color:rgb(88,110,117)">ex50_tut</span><span style="color:rgb(0,0,0)">_3.out</span></div><div><span style="color:rgb(0,0,0)">    :language: none</span></div></div></div><div><br></div><div>This isn't a bulletproof approach yet - the output can still be out of date, but good enough to pass the test suite (though that can at least be bulk-updated with a single command), and the input command is still literally included. Still, it reduces the maintenance burden of documentation and reduces the chance of confusing the reader with stale information.<br></div><div><br></div><div>[1]: <a href="https://petsc.org/release/tutorials/handson/">https://petsc.org/release/tutorials/handson/</a></div><div>[2]: <a href="https://petsc.org/release/developers/documentation/#sphinx-documentation-guidelines">https://petsc.org/release/developers/documentation/#sphinx-documentation-guidelines</a></div><div><br></div></div>