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) | ||
− | + | ||
− | |||
* structure your documentation by... | * 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 | * 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)