Skip to content

Restructure documentation

Created by: Zaharid

This is a general discussion on documentation, that should be made concrete in subsequent issues.

There are several problems with the documentation as it is.

  • People tend to say that the vp guide often contains the piece of information they need but that they are unable to find it without it being pointed out. However no concrete proposal on how to improve this has been made so far.

  • The validphys guide made some amount of sense when vp2 was a more experimental and separated project. But now it is more integrated with the rest of the code, so it doesn't make sense to have a validphys guide anymore (and indeed it contains e.g. pieces of random trivia on setting c++ development environments with conda). Rather we should have code documentation.

  • We have scattered bits of documentation regarding apfelcomb and the commondata format, some of them in the Edi wiki, where they are hard to find, many in PDF format which is difficult to browse/grep.

  • The examples in vp are hopelessly disorganized, and require some outdated and esoteric resources. This is #52 (closed) (and also #239 (closed)).

  • Many options in nnfit are esoteric and un(der)documentented. There is no resource that discusses them in detail. E.g. how do I do a level-2 closure test fit without fitted charm with a single layer network is a piece of folklore at this point.

  • The help subsistem in reportengine, validphys --help hasn't really kept out with the newer reportegine features such as production rules and collect.

  • The excuses the vp guide makes for not documenting the whole API (it's all very experimental and so on) do not make sense anymore.

As for how to structure the documentation, this essay:

https://www.divio.com/blog/documentation/

makes a lot of sense to me. According to it, one should have 4 different types of documentation:

  • Design-level explanation
  • Reference
  • Tutorials
  • Howtos

Indeed the vp guide contains scattered pieces of the 4 of those, which are often mixed together. The chapter on design considerations is explanations, the plotting format documentation is mostly reference, as is validphys --help, there is a tutorial on implementing a validphys pipeline for analyzing positivity predictions, and the usage chapter is scattered with howtos.

It would make a lot of sense that the guide is separated into collections of these 4 types of documents and that those are integrated with the rest of the documentation, which also would follow the same distinction. In addition it would be good to have more tutorials such as:

  • Fitting pipeline, from installation to vp-comparefits --upload (now mostly contained in the README).
  • Data implementation: from buildmaster/amc@nlo to fit.

As for the code reference, we have some docstrings (both in python and cpp) but we only generate the validphys --help pages at the moment. In addition, sphinx should be used to generate API docs for both python and cpp. The vp2 docs should possibly be integrated it with the existing --help mechanism (which has a limited ability of tracking the dependency graph and so it provides more information than the raw docstring).

I would say the first required step to get this moving is to get Sphinx to run all the manually written documentation we currently have, and also generate API reference for validphys and libnnpdf. Once that is done, we can restructure the documentation in the way outlined above.