Documentation and Communication Standards

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)

• structure your documentation by...
  • following pre-existing examples
  • providing 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. Consider Appendices for additional detail.
  • * 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?)

• 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)