I couldn't figure out how to actually write docbooks stuff. Looks like it's some XML thing, but I don't know if there are (free) apps to write in docbook format. All of the parsers seem to just convert to latex anyway and then to html or whatever, but I guess docbook has some nice features? Not quite sure.

I've never actually used it. I've heard that the Majoranna experiment uses it and likes it. It also seems that a lot of good software projects use it.

I put this to v2.0 (meaning sometime in the far future) because it would be nice to have something a little more professional than a wiki page at some point. But who knows...

You have other suggestions for non-wiki stuff? Or do you think it's good enough?

Google returned a useful looking link

http://wiki.docbook.org/topic/DocBookAuthoringTools

but there seems to be some weird network problem (can see google search but not google cache, nor docbook.org?) causing weirdness.

I'm not convinced latex would be that bad an idea if it can spit out HTML since then people could copy-paste into and from their thesis.

I guess Morteza just decides. We need both HTML (website) and PDF (ship with code or download to laptop).

So I'm looking into release for 0.0.2, and my teeth are clenching around this problem of how we handle documentation. At the moment it's a mess:

• perl script to generate documentation from inline comments on datacards
• materials documentation generated by hand? in 2006? and exported to wiki
• MiceModules documentation generated by hand in open office and exported to html and pdf
• Some user documentation generated by hand in the MAUS wiki
• Some user documentation generated by hand in the G4MICE wiki
• New tracker software manual
• doxygen documentation generated by hand

• data structure
• datacards replacement - "configuration" - stuff

Another requirement - has to be under some version control...

I'm worried too. I think the steps are:

1. document the first 15 minutes of MAUS usage like a tour
2. collect the mess of stuff written and triage then create links
3. docbooks or latex.

With docbooks I had trouble figuring it out honestly. I spent an hour or so and maybe was just being slow, but latex is at least a format everybody needs to know anyways. TTH looks decent at converting latex and so does hyperlatex.

Can MOrteza confirm he sees this?

I think we do latex. It goes in $MAUS_ROOT_DIR/doc/. We have a shell? script that parses it (by calling pdflatex or similar).

• converts to pdf
• converts to html
• can be modular
• can be included in theses/technical notes/etc
• can be generated/edited by scripts

Structure something like:

Documentation -> Tour (~ few pages) + examples
              -> Operations manual (~ few pages)
              -> Reference -> MiceModules -> geometry
                                          -> fields
                                          -> materials

                           -> configuration datacards

                           -> detectors   -> tracker
                                          -> tof
                                          -> Ckov
                                          -> EMR

                           -> data structure

                           -> analysis stuff? x-boa? optics?

Edit to add operations manual

Added wiki page UserDocumentation to record how we do documentation

So I added a documentation latex skeleton. Needs a sconscript. Need to convert mice modules to latex format. Need to start filling in docs...

Is this generally user information? Or are we wanting to use docbooks?

I don't understand the question.

This will be reference user information. Some cross-talk between the code documentation and the user documentation. But I think we need both.

Googling, docbooks looks a bit obscure/poorly documented. Latex is well known and well documented. So I don't want to do docbooks.

I'd just say update the title