Up to: New control system 30-m Main Page•Links
Title: Project ProjectDoc: documentation of projects
Master URL: http://www.iram.es/IRAMES/documents/ncs30mProjectDoc/
File Name: projectDoc
Revision: draft, , 1.3
Revision Date: 2001-10-19 [last rev: 2001-04-04]
Authors: W. Brunswig (brunswig@iram.es), A. Sievers (sievers@iram.es)
Contributors: Hans Ungerechts
Audience: technical staff, astronomers
Publisher: IRAM, Granada, Spain
Subject: NCS 30m: Documentation Standard for Projects
Keywords: Project Documents, XML, PDF
Description - about this document: Describe a standard of project documentation. This standard will be used in the development of the IRAM 30m telescope New Control System. This document describes iteration 0 of the project. We consider requirements and design to be done The requirements that are open wil not be implemented in this iteration. The format as described in the DTD file should be fixed now, but the XSL scripts to transform to PDF and HTML are not widely tested yet.

History of document

  • v 1.1, 2001-04-04 wb: describe ideas about project documentation
  • v 1.2, 2001-08-08 wb: review of concepts, note possible extension, modifications
  • v 1.3, 2001-10-17 wb: adapted to agreements in meeting (WB,HU,AS), related to v1.0 of dtd, document iteration 0 of project.

    •

    Pending

    1. work out user guide

    Project Plan

    1. 2001-10-19: distribute documentation of iteration 0 and request comments. (wb)
    2. 2001-10-31: release iteration 0. (wb)
    3. in 2002: review project, based on experience with iteration 0 and produce iteration 1. (wb, ?)

    Introduction

    A project typically goes through a sequence of phases:

    1. first ideas and top-level requirements
    2. detailed specifications
    3. design
    4. implementation
    5. module tests
    6. installation (deployment)
    7. integration tests
    8. maintenance
    9. out-phasing
    The sequence might be iterated several times (except for the last phase). Although the sequence of phases can be found in many areas we here concentrate on software projects. Many software projects at the IRAM, Spain, are of a small scale of a few Man*Weeks. These smaller projects are often not well documented. The scheme presented could be use to document the various development steps.

    This version of this document relates to v1.0 of the projectDoc format. The syntax of projectDoc files is defined in the projectDoc DTD file: the projectDoc DTD file. Its semantic is described below.

    Project documents might not handle all details. For small projects most of the details could be included in the project document (to avoid several small or tiny documents). However, for larger project details should be handled in separate documents.

    Requirements

    sections [done,2001-09-17]: (modified)
    A project documents shall consists of a list of sections:

    1. standard document "meta" information
    2. document history
    3. one chapter for each of the software development phases: requirements, design, implementation, installation
    4. a project plan
    5. a project logbook: lists important events
    6. an operation manual (user guide)

    subSections [done,2001-09-17]: (modified)
    Each section is related to a specific software development phase. It shall contain a list of items ("subsections") describing details, e.g. each requirement shall be written into one requirement subsection.

    identifiers [done,2001-09-17]: (modified)
    Each subsection shall have an identifier. If a specific requirement is covered by just one subsection of the following phases (design, implementation, installation) then those subsection shall have the same identifier.

    format [done,2001-08-08]: (modified)
    The overview document shall be formatted such that different items and concepts are identified by tags.

    Reason: Using tags allows to extract in a systematic way information. E.g. Requirements are enclosed in tags: <req> and </req>. Although project documents will contain chapters on all steps of development, extracting a listing of requirements can easily done by using the tags.

    attributes [done,2001-04-04]:
    Items like requirements or tests shall have attributes that indicate important information. The attributes of the tags depend on the type of tag.

    Example:
    1. Requirement attributes: state (open, accepted,...), implementation (done, started,...)
    2. Implementation attributes: date, platform (host)
    The details shall be defined in the design.

    swConcepts [done,2001-04-04]:
    The language shall include a set of tags for the standard concepts of software: file, host, port, socket, message, error, ... .

    textStructure [done,2001-04-04]:
    The language shall include a set of tags to define the text structure: paragraphs, lists, emphazised text, ... .

    acronyms [open,2001-09-17]: (modified)
    The language shall have a tag to define acronyms. The definition of acronyms can be done in the same file or in different document. The "output" versions of the document shall contain lists of acronyms.
    Not implemented in iteration 0.

    index [open,2001-09-17]: (modified)
    The language shall have a tag to register document positions in an index.
    Not implemented in iteration 0.

    hyperText [done,2001-04-04]:
    The language shall include tags for hypertext references to external documents.

    requirementGroups [open,2001-08-09]: (modified)
    Allow to structure larger sets of requirements by defining groups (subsections) of requirements, e.g., group of requirements related to monitor and control.
    Not implemented in iteration 0.

    template [done,2001-09-17]: (modified)
    Provide a file that contains a template of a project document.

    outputPDF [done,2001-08-08]: (modified)
    The original document shall be transformed to PDF.

    Reason: The original version of the document uses tags and is therefore not "nice" to read. PDF documents produce an acceptable output and have also basic hypertext features.

    outputHTML [done,2001-08-08]: (modified)
    The original document shall be transformed to HTML.

    Reason: As HTML has more advanced hypertext features it might be produced as well if these features are wanted.
    Should we maintain HTML besides PDF? HU: Maybe not in this case, but for "Help"/User Documentation.

    extractUserDoc [open,2001-04-04]:
    A tool shall allow to extract information for a user. This shall consist of sections:
    1. Introduction
    2. Requirements
    3. UserGuide

    Not implemented in iteration 0.

    extractModifications [open,2001-09-17]: (modified)
    A tools shall allow to extract those subsections (or sections) that have been modified since a given date. The standard output versions of the document shall also indicate modifications from the last to the actual version of the document.
    Not implemented in iteration 0.

    emacsSupport [open,2001-04-04]:
    Editing project documents shall be supported by a particular emacs mode.

    verification [done,2001-09-19]: (modified)
    A tool shall be provided that check if a projectDoc document is in conformance with the DTD defining the language syntax.

    Design

    sections [done,2001-09-17]: (modified)
    A project document will have the following sections:

    1. meta: information about the document. It consists of most of the items that are used for standard documents of the IRAM new control system.
    2. pending: important information about pending items (e.g. unfinished installation tests (ok, this should not happen))
    3. history: document history
    4. introduction: project background, basic ideas, etc.
    5. requirements: list project requirements (what shall be done)
    6. specifications: list specifications
    7. design: list design decision (how things will be done)
    8. implementation: information about implementation, links to further documentation (e.g. code documentation) (what has been done)
    9. installation:
      1. can give details on installed requirements (in particular, if not all requirements are implemented/installed at the same time.
      2. describe how to install the software (e.g. which configuration files have to be modified).
      3. list on which systems the software is installed
    10. project log: a logbook of important project events
    11. userGuide: can contain information about
      1. how to use the software or link to an external user manual.
      2. which maintenance is needed.
      3. which health-checks can be done by users
    12. miscellaneous: can contain what does not fit somewhere else, like future ideas and plans.

    format [done,2001-04-04]:
    The language to describe the software and software engineering concepts is based on XML. It defines the tags
    1. to identify software engineering concepts: requirements, design, ... ,
    2. to identify standard software/computer concepts: file, host, ... ,
    3. to reference external documents, and
    4. to do basic text structuring.
    It also defines tag attributes and which type of tags can be "inside" other tags. E.g. tag <requirements> can be followed by a tag <req> but not by a tag <test>. Why use XML ? XML allows to define a structured text-tagging language (give some items a meaning). It is becoming an important standard for web documents and tools are available (many as public-domain). Libraries for many languages exist: Java, C, TCL, Python. We do not know if Fortran utilities exists (besides using C libraries) but some basic routines have been written by ourselves.

    subSections [done,2001-09-18]: (modified)
    Subsections are available for the sections requirements (tag: req), specifications (spec), implementation (impl), installation (inst).

    attributes [done,2001-09-17]: (modified)
    All top-level items (requirements, designs, ...) shall have the following attributes:
    1. id: identifier of requirement, design, ...
    2. state: state of item (open,done).
    3. date: date of last modification: the date shall refer to last modification of requirement or any stage with same identifier
    The state of all items (requirements, design, ...) is described by an attribute state with can take one of these values:
    1. notStarted: work has not yet started
    2. open: work has started, but not yet finished
    3. done: this is the "final" version (of this "iteration")

    Usage of state attribute is different for requirements, see requirementAttributes

    specifications [done,2001-09-17]: (modified)
    The first phase of a project consists in defining the requirements of the project. This normally starts with a list a unprecise requirements. Reviews and discussions between "customer" and "provider" shall lead to a list of precise requirements that both parts agree upon.

    The following steps in the software development can also reveal deficiencies of the list of requirements and thus lead to new and modified requirements.

    We can also distinguish between "user" requirements and those requirements that are derived by an analysis of the "user" requirements. Requirements that result from the analysis of the "user" requirements are also called specifications.
    Note: specifications shall not use identifiers used for a requirement

    requirementAttributes [done,2001-09-17]: (modified)
    For the requirements, we use the state attribute also to indicate the state of the "realization" of a requirement:
    1. notStarted, open: same meaning as above
    2. fixed: the requirement has been fixed (for this "iteration")
    3. ...ing: current state of "realization" (designing, implementing,installing,testing)
    4. ...ed: the state has been finished, next state not yet started (designed,implemented,installed)
    5. done: the requirement has been "realized": designed, implemented, installed, and tested.
    Requirements can have the following additional attribute:
    1. iter: indicate in which software process iteration the requirement shall be implemented.
    2. obsolete="yes": indicate that requirements is not valid anymore, but keep it, possibly with an explanation why it has been dropped.
    3. prio {essential, high, low}: indicate priority of requirement.
      1. essential: requirement has to be implemented in first iteration.
      2. high: requirement shall be implement after all essential requirements have been implemented.
      3. low: requirement is considered to be useful, but implementation shall be done after implementing all requirements with high priority.
    4. from: who made the requirement

    Question: Shall we use different states/dates referring to the requirement itself and any other stage with same identifier ?

    swConcepts [done,2001-09-18]: (modified)
    Tags will be defined for the most common concepts: file, host, process. Other concepts can be specified by a general tag swItem. See DTD for defined attributes.

    output [done,2001-04-04]:
    Document transformation will be developed from projectDoc language (in XML) to HTML and TeX/PDF in the XSL language.

    Reason: Why use XSL ? For the translation several possible standards exist: XSL, DSSSL, CSS. XSL is a standard set up by the www comitee (w3c.org) and is the most powerful language for this purpose. However, support of XSL by web browsers is currently still limited.

    outputPDF [done,2001-09-17]: (modified)
    Project documents will be translated into PDF. This is done by
    1. transform the documents from XML to PDFLaTeX (using XSL), and then
    2. use PDFLaTeX to create a PDF version (using macros developed by HU)

    outputHTML [done,2001-09-17]: (modified)
    A script will be written in XSL to translate the projectDoc language into HML. The generated document will contain:
    1. all sections. for those items that have a date attribute it will be indicated if the item has been modified or added since the last revision of the document
    2. a contents table consisting of sections and subsections
    3. a list of requirements, their attributes and other items with the same identifier (descendants)
    4. a list of references: hyperText and swConcept elements

    tests [done,2001-08-09]: (modified)
    Testing can be done at varous stages of the development. The documentation of those tests depends on the development stage:
    1. module tests are done during the implementation phase. They are described either in the project doc or as part of the source code documentation.
    2. integration tests check the interface of and cooperation between modules. They are described in the implementation section.
    3. system tests check the complete system after installation. They are also described in the installation section.
    4. health check tests and tests to identify errors are described in the user guide.

    verification [done,2001-09-19]: (modified)
    a (pd) tool xmlv check conformance of documents with regard to a DTD. this tools will be provided on gra-lx1.

    Implementation

    format [open,2001-09-18]: (modified)
    The projectDoc language is based on XML. Its syntax is defined by the general XML rules and the specific language defined in : the project Doc DTD file.

    sections [open,2001-09-18]: (modified)
    The required sections are defined in the DTD referenced above.

    subSections [open,2001-09-18]: (modified)
    The required sections are defined in the DTD referenced above.

    attributes [open,2001-09-18]: (modified)
    The required attributes are defined in the DTD referenced above.

    swConcepts [open,2001-09-18]: (modified)
    The required tags are defined in the DTD.

    textStructure [open,2001-09-18]: (modified)
    The required tags (ol, ul, li, p, pre) are defined in the DTD referenced above.

    hyperText [done,2001-09-18]: (modified)
    The projectDoc DTD contains a tag to define references to other documents.

    template [done,2001-09-17]: (modified)
    For a template of the current project "language" look at: template of projectDoc files .

    outputPDF [done,2001-09-17]: (modified)
    A transformation script is defined produce a PDF document. The transformation script is written in XSL.

    outputHTML [done,2001-09-17]: (modified)
    A transformation script is defined produce a PDF document. The transformation script is written in XSL.

    Installation

    hosts [done,2001-10-19]: (modified)
    All tools needed are available on gra-lx1.iram.es.

    requiredSw [done,2001-10-19]: (modified)
    The following sw packages are used:
    1. com.jclark.xml.sax: xml parser (pd: public domain)
    2. com.jclark.xsl.sax: xsl transformer (pd)
    3. pdflatex: LaTeX wit PDF extensions (pd)

    homeMadeSw [done,2001-10-19]: (modified)
    1. LaTeX macros for projectDoc style (hu): in /usr/local/projectDoc
    2. XSL scripts (wb): in /usr/local/projectDoc

    verification [done,2001-09-19]: (modified)
    tools xmlv (xml verification) is available on gra-lx1 in directory /usr/local/bin.

    User Guide

    How to write projectDoc documents:
    1. get a basic understanding of xml type documents: syntax rules, tags, attributes, special characters
    2. copy file template of projectDoc file to your new document
    3. check for allowed attributes in file projectDoc DTD file
    4. set a project.dtd to /usr/local/projectDoc/projectDoc.dtd with command: 
      ln -s /usr/local/projectDoc/projectDoc.dtd projectDoc.dtd
    5. insert file template make file for projectDoc into your make file and edit it.
    Please note also:
    1. if <ref> tags reference external documents giving a relative name are these names are preceeded by the "masterURL" specified with tag <doc:masterURL> .
    2. xml filess can be printed "prettyly" with: 
      a2ps -1 --delegate=no --pretty-print=html your-xml-file

    Miscellaneous

    rdf [,2001-09-18]: (modified)
    xml documents shall have rdf section in the future. rdf is a standard to describe "resources" in the www world. (see also www.w3c.org)

    List of Requirements/Specifications and Descendants

    1. req/spec: sections
      1. req: state=done date=2001-09-17
      2. des: state=done date=2001-09-17
      3. impl: date=2001-09-18 state=open
    2. req/spec: subSections
      1. req: state=done date=2001-09-17
      2. des: state=done date=2001-09-18
      3. impl: date=2001-09-18 state=open
    3. req/spec: identifiers
      1. req: state=done date=2001-09-17
    4. req/spec: format
      1. req: state=done date=2001-08-08
      2. des: state=done date=2001-04-04
      3. impl: date=2001-09-18 state=open
    5. req/spec: attributes
      1. req: state=done date=2001-04-04
      2. des: date=2001-09-17 state=done
      3. impl: date=2001-09-18 state=open
    6. req/spec: swConcepts
      1. req: state=done date=2001-04-04
      2. des: date=2001-09-18 state=done
      3. impl: date=2001-09-18 state=open
    7. req/spec: textStructure
      1. req: state=done date=2001-04-04
      2. impl: date=2001-09-18 state=open
    8. req/spec: acronyms
      1. req: state=open date=2001-09-17 prio=high
    9. req/spec: index
      1. req: state=open date=2001-09-17 prio=low
    10. req/spec: hyperText
      1. req: state=done date=2001-04-04
      2. impl: date=2001-09-18 state=done
    11. req/spec: requirementGroups
      1. req: state=open date=2001-08-09 prio=low
    12. req/spec: template
      1. req: state=done date=2001-09-17
      2. impl: state=done date=2001-09-17
    13. req/spec: outputPDF
      1. req: state=done date=2001-08-08
      2. des: state=done date=2001-09-17
      3. impl: state=done date=2001-09-17
    14. req/spec: outputHTML
      1. req: state=done date=2001-08-08
      2. des: state=done date=2001-09-17
      3. impl: state=done date=2001-09-17
    15. req/spec: extractUserDoc
      1. req: state=open date=2001-04-04 prio=high
    16. req/spec: extractModifications
      1. req: state=open date=2001-09-17 prio=high
    17. req/spec: emacsSupport
      1. req: state=open date=2001-04-04
    18. req/spec: verification
      1. req: state=done date=2001-09-19
      2. des: date=2001-09-19 state=done
      3. inst: date=2001-09-19 state=done

    List of Hypertext refences and swItems

    1. file: name=/usr/local/bin ->
    2. file: name=/usr/local/projectDoc/projectDoc.dtd ->
    3. host: name=gra-lx1 ->
    4. host: name=gra-lx1.iram.es ->
    5. host: name=gra-lx1 ->
    6. ref: href=OTHERS/project.dtd text=the projectDoc DTD file ->
    7. ref: href=OTHERS/project.dtd text=the project Doc DTD file ->
    8. ref: href=OTHERS/template.xml text=template of projectDoc files ->
    9. ref: href=OTHERS/template.xml text=template of projectDoc file ->
    10. ref: href=OTHERS/project.dtd text=projectDoc DTD file ->
    11. ref: href=OTHERS/projectTo.make text=template make file for projectDoc ->
    12. swItem: type=link name=project.dtd ->
    2001-10-19Project ProjectDoc: documentation of projects (W. Brunswig (brunswig@iram.es), A. Sievers (sievers@iram.es))