Difference between revisions of "Documentation and Communication Standards"

From WormBaseWiki
Jump to navigationJump to search
(Basic steps to a doc/communication guideline document.)
 
 
(7 intermediate revisions by 3 users not shown)
Line 5: Line 5:
 
** ...only create new documents when there is no suitable existing document in place (ask you team members)
 
** ...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)
 
** ...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...
 
* structure your documentation by...
** ...giving a short intro about the documents contents
+
** following pre-existing examples
** ...have a table of contents, if there are more than half a dozen headings and/or section headings
+
** providing a short intro about the documents contents
** ...sections should be topical ''and'' denoting context (e.g., machine changes, different environments s.a. development, staging or production)
+
** 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
 
* executable documentation
** log which command lines you executed (incl. directory, current user, machine)
+
** * 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
+
** * 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 (<code>ant dump-genes</code> 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)
+
** * describe ''what'' is being done (<code>ant dump-genes</code> 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 ==
 
== Communication ==
Line 25: Line 25:
 
* let all team members know...
 
* let all team members know...
 
** ...when you created a new document (Why? Purpose? What are the contents and future directions?)
 
** ...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)
 +
 +
[[Category: Best Practice (Web Dev)]]
 +
[[Category:Getting Started (Web Dev)]]
 +
[[Category:Communication (Web Dev)]]

Latest revision as of 13:58, 19 June 2014

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)