The nanorc documentation is very informative, but based on my experience testing for dunedaq-v3.1.0 I believe there are ways in which it can be made easier to follow for readers. Before going into details, categories of improvement include:
Fixing typos in command line examples
Updating sections which refer to obsolete transitions, obsolete output, etc.,
Avoiding repetition
Assuming less knowledge of Kubernetes and services on the part of the reader
Chronologically putting "beginner" info before "intermediate user" info
Now, specifics. Stepping through the README.md as is currently found at the head of develop (d3c7ab416408):
In the "Setup" section, it's not really explained why a user would want to use top_level.json. In the example it requires more typing than simply passing the name of the configuration directly to nanorc
The output from the help example is obsolete (old transitions)
The line "and a readout and dataflow application which receives the triggers" sounds like it refers to a single application which combines readout and dataflow
The state diagram is great, but it refers to a non-existent "end_run" transition. I believe "stop_run" was intended?
The section on running nanorc in batch mode refers to nanorc daq_fake ... which should be nanorc fake_daq ...
In the discussion on viewing TriggerRecordHeaders, the obsolete path $DFMODULES_FQ_DIR/dfmodules/bin/hdf5dump/hdf5_dump.py is given in the command line example
Not a showstopper necessarily, but in "More on boot", it might be worth updating examples/mdapp_fake/boot.json to refer to modern daq-buildtools commands, etc.
In the "Requirements" section on "Kubernetes support", an additional sentence or two on how the user can check that the requirements are in fact met - that the configuration service is running, what the expected dunedaq images would be called and where to find them - would be helpful. This, especially given that at this point the np04 cluster isn't always guaranteed to be in perfect shape for Kubernetes running.
In the sentence beginning with "Felix cards and data storage (?) cannot be claimed by more than one
partition.", we should resolve the "(?)" and check that that section is up-to-date
The phrase "control plane" is used; perhaps a brief sentence describing to the user unfamiliar with k8s what that is would be helpful.
We could update the "Tested configurations" section
It may be worth moving the "Debugging" section to after the walkthrough, since "Debugging" is a more advanced action than just trying out the system for the first time
The steps in the "Setup the nightly/release" repeat a good deal of the material from their links.
In "Generate a configuration and upload it on the configuration service", upload_conf should be upload-conf
It may be a good idea to move "you should rename np04docker.cern.ch/dunedaq-local/image-name " earlier otherwise there's a risk that overeager users will literally type nanorc --image np04docker.cern.ch/dunedaq-local/image-name at the command line
The "Caveat list by decreasing order of importance" is a list of one item. Not sure that item adds any info about anti-affinity that hasn't already been mentioned?
Unless I'm misunderstanding, I believe it would be clearer to replace daq_app with daq_application where written
Concerning "NOTE: You need to be on np04-srv-{015,016,026} for this to work": is this up to date? Perhaps users should be told to check the np04-sysadmin channel on Slack for up-to-date news, or some other location?
This will sound vague, but as I recall is the password requirement mentioned in "How to build a daq_app image and distribute it" obsolete?
The drop-down list for "If the instructions after docker login" is a good idea and works fine using GitHub markdown, but MkDocs markdown (used in the official documentation) has trouble displaying it. Until I figure out if this can be dealt with, can we just convert the drop-down into a "normal" section?
plasorak
commented
2 years ago
The nanorc documentation is very informative, but based on my experience testing for dunedaq-v3.1.0 I believe there are ways in which it can be made easier to follow for readers. Before going into details, categories of improvement include:
Now, specifics. Stepping through the
README.mdas is currently found at the head ofdevelop(d3c7ab416408):top_level.json. In the example it requires more typing than simply passing the name of the configuration directly tonanorchelpexample is obsolete (old transitions)nanorcin batch mode refers tonanorc daq_fake ...which should benanorc fake_daq ...TriggerRecordHeaders, the obsolete path$DFMODULES_FQ_DIR/dfmodules/bin/hdf5dump/hdf5_dump.pyis given in the command line exampleexamples/mdapp_fake/boot.jsonto refer to modern daq-buildtools commands, etc.upload_confshould beupload-confnanorc --image np04docker.cern.ch/dunedaq-local/image-nameat the command linedaq_appwithdaq_applicationwhere written