Documentation and Communication Standards
- 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
Any background that is pertinent to the topic at hand should be explained. Classic examples are the use of GFF -- track names and contents are obvious for someone with an experimental background in C. elegans genetics, but not so for someone with a biology 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-genesis 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)
- 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?)
- communicate fast...
- ...by speaking to people in person
- ...by making use of instant messaging
- ...revert only to email in exceptional circumstances (Output pasting required, tracking formal documentation s.a. a holiday request, announcements)