Fermilab


MINOS Offline Documentation
[home] [installing MINOS software] [supported platforms] [package links] [mailing list] [HyperNews] [FAQ] [computing help] [MINOS glossary] [archives]

WebDoc Structure Guidelines



This is a rough draft! Comments are welcome!

WebDocs
All below pages are linked from here. See WebDocs link for WebDocs internal structure. WebDocs.html is the portal page to Web documentation of the MINOS offline software.

Requirements
From here you will find links to a structured list of things we want the off-line software to do. These can be expressed both as
Requirements
Saying what the software will do
e.g. "I want the software to find and fit muon tracks"
Use Cases
How the user interacts to get a job done
e.g. "To fit muons I want to type into a file some numbers that will define how the fitter will work and the name of the input file and then run a job that reads that file and processes the data".


  • Requirements are structured logically into sets by related topics and eventually software packages are developed to satisfy a one or more set.
  • Requirements should be readable by everyone, after all everyone has an interest in ensuring that the off-line software does what they want!

  • PACKAGE-SPECIFIC INFORMATION
    UserManualDoc
    Once a package starts becoming stable, a document describing its logic and use goes in the User Manual. The definition in the Package Glossary can become the opening paragraph in the User Manual.

    PACKRATs
    Each package should have a Package Rational within its <pkg_name>/doc/ directory. The PACKRAT serves to direct the high level development of an individual package. It includes a list of requirements that the package is attempting to satisfy together with some high level design information that helps developers and maintainers of the package.

    PACKRATs tend to be rather technical, look at them if you are really interested in the analysis and design issues that shape the package.

    Package Glossary
    For beginners. Will contain one to three sentence "definitions" of packages so that people using MINOS software can get a quick overview of what packages do.

    Companion
    The Companion has training material suitable for beginners for using C++ and ROOT.

    HyperNews
    Software meetings agendas and minutes are archived here. Old discussions can also be found here. Besides a meeting agendas, minutes, and a very occasional announcement (such as annoucing a new frozen release), most things should be put somewhere else. The HyperNews archive is searchable.

    FAQ
    A distillation of important questions that get addressed on the MINOS software mailing list, MINOS_SOFTWARE_DISCUSSION@fnal.gov.The FAQs are searchable so users can find questions and answer pertaining to a specific topics.

    Glossary
    Contains definitions of MINOS words.

    MINOS Software Mailing List and Archive
    If you have a problem then email it to the MINOS software mailing list, MINOS_SOFTWARE_DISCUSSION@fnal.gov. However this list gets used by everyone to discuss everything! So be prepared to receive a lot of very technical stuff and to learn where the DELETE key is without looking! We have tried and failed in the past to separate technical discussions from user questions, but they overlap too much.


    Last Modified: $Date: 2002/08/13 19:29:51 $
    Contact: minos_software_discussion@fnal.gov
    Page viewed from http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/doc/guidelines.html
    Fermilab
    Security, Privacy, Legal Fermi National Accelerator Laboratory