Documentation and Communication Standards

From WormBaseWiki
Revision as of 19:27, 12 December 2013 by Joachim.baran (talk | contribs) (Basic steps to a doc/communication guideline document.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Documentation

  • document by...
    • ...extending or improving existing documentation
    • ...only create new documents when there is no suitable existing document in place (ask you team members)
    • ...ensure that new documents can be reached via a link from the wiki main page (either directly or indirectly through a few more clicks)
    • ...never lecture or explain topics that have been covered by a biology and/or computer science degree
  • structure your documentation by...
    • ...giving a short intro about the documents contents
    • ...have a table of contents, if there are more than half a dozen headings and/or section headings
    • ...sections should be topical and denoting context (e.g., machine changes, different environments s.a. development, staging or production)
  • executable documentation
    • log which command lines you executed (incl. directory, current user, machine)
    • log the output too, if it is not too much (a dozen lines), or otherwise give an excerpt of a successful command execution
    • describe what is being done (ant dump-genes is not helpful; but saying where the data comes from, where it is being stored, and for what this data dump can be used is helpful)

Communication

  • let your senior team members know...
    • ...what you are doing now
    • ...what you are going to do in the next few days
  • let all team members know...
    • ...when you created a new document (Why? Purpose? What are the contents and future directions?)