CASA Document Repository Use Conventions

Introduction

This page provides suggestions on content, naming conventions and file organization within the CASA SVN document repository.

The development plan for the CASA document repository is outlined on a separate page.

Content Types:

The following are document categories that should typically be placed under change control in the repository:
  • Software Architecture definitions and Application Programming Interfaces between software layers.
  • Requirements documents that provide traceability of the design to its ever-evolving requirements.
  • A CASA Memo-series, describing high-level design, testing, policies, etc.
  • Other high-level design documents that describe the design of major systems or tools within CASA.
  • Cycle planning documents that describe the efforts of the group for a given cycle.
  • User-oriented documents which are generated by the CASA team.

Some document categories that may be explicitly excluded from the repository include:
  • Any 'sensitive' or proprietary information, as the main SVN repository is public.
  • Design implementation documents, since it is favored that detailed design implementation be commented in the code.
  • Accepted process documents describing best practices adopted by the CASA group. Since these should be living documents and frequently updated, these may be better hosted in the wiki.
  • Information of transient value, such as meeting minutes. Such information should be retained in the wiki.

Naming Convention:

  • In an effort to allow for easy navigation of the repository, descriptive file names should be used.
  • In an effort to allow for persistent links from the web front-end to the wiki, persistent document names with no document revision numbers or dates should be used for the PDFs. (e.g., Casa_43_requirements.pdf is an acceptable name, while Casa_43_requirements_rev4a.pdf is not.)

Folder Structure

  • svn.cv.nrao.edu/svn/casa/trunk (keeping docs in trunk ensures we collect "snapshots" of documentation as it was for a given release. Provides an easy mechanism to see doc status, such as a requirements doc, at the time of a given release.)
    • /doc : project-wide documents will reside in folders below this level.
      • /user : Home for user documentation. Existing user-oriented files in the /doc folder will be migrated here as any scripts are updated.
      • /web : For persistent links to PDFs. Files should reside in /web with no sub-folder structure.
      • /development - For document source files (odt, ods, doc, xls, latex, etc.), within one of the sub-folders described below.
        • /design : For high-level documents that describe the design of the CASA code. (Recall that lower-level documents should reside near the code of CASA components to which they relate.)
        • /support : For documents that describe technical work that is not modifying the CASA code, but is required for effective execution of the project.
        • /management : For project management and governance documents.
Note: Any sub-folder structure within /design, /support, and /management may grow as-needed to whatever structure makes sense to the repository contributor. These files can be reorganized at-will with no effect on the pdf web links.

Memo Series

  • The CASA memo series shall reside in: /trunk/doc/development/memos
    • Note: currently under /trunk/code/doc/memos
  • Consistent with the folder structure, PDF copies shall reside in /trunk/doc/web for easy browser access and linking via the wiki.
  • Memos shall be numbered in chronological order as they are produced and added to the folder. If required, an index for issuing memo numbers will be prepared.
  • Naming convention shall be: CASA-Memo-[NNNN]-[Title]
    • [NNNN] represents document number.
    • [Title] represents a descriptive document title.

-- RobSelina - 2014-04-04
Topic revision: r4 - 2014-05-07, RobSelina
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding NRAO Public Wiki? Send feedback