Last modified 4 years ago Last modified on 10/23/2014 02:10:46 PM

From Software Standards and Policies

Policy on Wiki Usage for DM Documentation

While we want to foster open source development and a wiki is central to this purpose, there are certain caveats on what should and shouldn't be posted to the DM wiki since significant material is open to the public. All DM wiki users should ensure the following:

Review the material you have posted on the DM wiki to be sure there is nothing that is confidential, or that could be embarrassing or used against the project. Confidential material would include (for example) partnering plans or proposals that are confidential or have not yet been realized, financial information, positioning relative to other projects, or comments about strengths or weaknesses relative to other projects.

LSST project-level documents such as the SDP, Security Design, and Fault-tolerance Design that are not yet approved by the LSST CCB, should be labeled as DRAFT and a note should appear in every page footer that indicates no DM wiki documents are approved until they have a Docushare document-ID. When the document-ID is assigned, the wiki version should either provide only a link to the approved document on Docushare or insert the document-ID and change the access to read-only.

The DM System Manager is responsible for oversight ensuring that the DM wiki only has appropriate material. The entire DM team is expected to help with this oversight; if you see something that is suspect, please bring it to the attention of the DM System Manager.

Rationale behind the Policy

A proposal for Wiki / Docushare management of LSST project-wide baselined documents was suggested:

  • a document is created and maintained on the DM wiki;
  • the document is submitted for approval by the LSST CCB;
  • the document is wiki-output to a PDF (or similar output standard) and installed on Docushare.
  • the Docushare document-ID is embedded in the DM wiki version, the DRAFT designation is removed, and then the DM wiki version is read-locked.
  • further modifications to the document may be done on the DM wiki only if the wiki document is relabelled: DRAFT REVISION simultaneously with resetting read/write access permissions;
  • then the cycle restarts from the beginning.

Once an LSST-baselined document is frozen for review and submitted to the LSST configuration control process in Docushare for approval, it is baselined (put in a specific location and locked). At this point the requirement is to have a clear and immutable version that everyone sees that cannot be changed without prior approval. That is the essence of change control. If the corresponding wiki pages are to remain in the DM wiki simultaneously, they must be locked as well.

Note that documents should be subject to very little, and only incremental change after baselining, and only after approval of a formal change request. So, the interactive DM wiki editing process is less useful for these documents. If the document is undergoing significant change, it isn't ready for baselining to begin with, and can continue under edit via the DM wiki (subject to the footer indicating its draft status).