Policy on DM Wiki Use

Sourced from Jeff Kantor, Nov 2008.

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 wiki users should ensure the following:

  • Review the material you have posted on the 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 Security Design, that are not yet approved by the 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 Project 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 Project Manager.

Rationale

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 filed in Docushare;
  • The Docushare document-ID is embedded in the DM wiki version, the DRAFT designation is removed, and then the version on the wiki is marked as read-only.
  • Further modifications to the document may be done on the DM wiki only if the wiki document is relabelled DRAFT REVISION at the same time as write access is restored;
  • The cycle restarts from the beginning.

Once a 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, 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. 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 editing may continue on the wiki (subject to the footer indicating its draft status).