jcfreeman2
commented
3 years ago I just discussed ways to update the minidaqapp documentation with Kurt and Carlos, and here's what we came up with.
When the user starts at the homepage of the minidaqapp documentation (https://dune-daq-sw.readthedocs.io/en/latest/packages/minidaqapp/), there should be a paragraph or two providing a conceptual overview of what the minidaqapp package is. Then a diagram describing the layout of a "standard" DAQ system which minidaqapp can set up - for v2.6.0, this might be a readout app, a dataflow app, a trigger app, etc.
Below the diagram, we could have a step-by-step tutorial similar to what Carlos presented in his talk at the DAQ/SC meeting at the end of March, where the user could learn how to recreate what's happening in the diagram at the command line. Included in this tutorial would be information on how users could examine the data they've produced, as well as any monitoring metrics. It may be useful at this point to link to other package's documentation for users to understand in more detail how to understand their output - e.g., what a trigger record is (as described in https://dune-daq-sw.readthedocs.io/en/latest/packages/dataformats/).
Then, the user could be taught about how to control the confgen script(s) by passing arguments to them. For starters, they could just be told to see what the output is when they pass the -h option, since there's good in-terminal material there already. Some of the parameters presented by -h are self-explanatory (like run number), but others may benefit from a sentence or two on the website describing in a little more detail what they are and why they're useful.
Finally, there are advanced actions users can take to configure the DAQ which require manual edits of the JSON files rather than simple argument passing. For some of these more common advanced actions, a description could be supplied about what manual edits would be required to accomplish them.
Two final points:
- A first step before anything else should be to remove minidaqapp-developer-focused documentation from the website (e.g., links to minidaqapp developer meeting notes, etc.)
- Since minidaqapp is in a state of flux as efforts are made toward the v2.6.0 release, care should be taken not to expend effort on detailed documentation of anything that's going to be eliminated or drastically changed. Use of intermediate diagrams, provisional documentation, etc. may be necessary before final decisions are made about the release.
bieryAtFnal
If you can see this Issue, it means that the existing documentation for this package has already been added to the official documentation, https://dune-daq-sw.readthedocs.io/en/latest, via its placement in your repo's
docs/directory. The next step is to make sure that the documentation indocs/tells your package's users (as opposed to developers) everything they need to know about the package. The goal is to get this done for the dunedaq-v2.4.1 release in a couple weeks.For details/hints please see https://dune-daq-sw.readthedocs.io/en/latest/editing_package_documentation/, disregarding any April 6 comment I inserted in there which refers to repos that don't yet have any official documentation.