What Is And How To Write CT2 Spec
From UG
(→How to write a good spec) |
|||
| (9 intermediate revisions not shown) | |||
| Line 1: | Line 1: | ||
| - | [[Category: | + | [[Category:Documentation]] |
== What Is It == | == What Is It == | ||
CT2 Spec is a "portal" for specific [[CT2 component]] that contains documented requirements/design/etc. It is a part of [[CT2 Wiki]]. | CT2 Spec is a "portal" for specific [[CT2 component]] that contains documented requirements/design/etc. It is a part of [[CT2 Wiki]]. | ||
| + | |||
| + | == How to write a good spec == | ||
| + | |||
| + | === Three C of good spec === | ||
| + | |||
| + | For spec to be good it must be: | ||
| + | |||
| + | * '''Clear''' | ||
| + | * '''Correct''' | ||
| + | * '''Complete''' | ||
| + | |||
| + | === SpecQA === | ||
| + | |||
| + | '''SpecQA''' is a process of reviewing spec and reporting problems with spec. | ||
| + | |||
| + | See good example of SpecQAReport in http://mantis.jaguarfreight.com/mantis/view.php?id=2102 | ||
| + | |||
| + | == Optimal Use of History and Preview Features == | ||
| + | |||
| + | Every wiki has a "history" - log of changes. | ||
| + | |||
| + | If you have particular task then commit final version ("Save page" button) it only after you finished. | ||
| + | |||
| + | Until then if you need to edit+preview+edit+preview then use "Show preview" button. | ||
| + | |||
| + | In this case History will have meaningful list of items and it is easy to use "diff". | ||
| + | |||
| + | If you save after every little change then it would be harder to see how many times it was changed and for what reason. | ||
| + | |||
| + | Also use "summary" field and "This is a minor edit" checkbox. | ||
| + | |||
| + | == Top Down Approach, Correct Workflow, Collaboration == | ||
| + | |||
| + | It is important to understand that wiki spec for component is one article but: | ||
| + | * multiple team members contribute to it | ||
| + | * there is a correct "flow": for example Business Requirements section must be written before Detailed Design section and if BR section is updated again then Detailed Design must be updated accordingly | ||
== How To Write It == | == How To Write It == | ||
| - | * see [[Generic Spec Template]] | + | * see [[Generic Spec Template]] '''(important!)''' |
* see [[Wiki Template for Ops Admin]] | * see [[Wiki Template for Ops Admin]] | ||
* see [[Wiki Template for Ops Pdfs]] | * see [[Wiki Template for Ops Pdfs]] | ||
| Line 14: | Line 50: | ||
Examples of "well written" (but not ideal!) CT2 spec: | Examples of "well written" (but not ideal!) CT2 spec: | ||
| + | * [[Airlines]] | ||
* [[In Transit Report]] | * [[In Transit Report]] | ||
| - | * | + | * [[Delivery Order Trucking Air]] |
=== Creating a new article === | === Creating a new article === | ||
| Line 23: | Line 60: | ||
== See also == | == See also == | ||
| + | * http://en.wikipedia.org/wiki/Technical_writer | ||
* [[About Software Requirements In General]] | * [[About Software Requirements In General]] | ||
* [[Use Case]] | * [[Use Case]] | ||
Current revision as of 23:48, 6 June 2010
Contents |
[edit] What Is It
CT2 Spec is a "portal" for specific CT2 component that contains documented requirements/design/etc. It is a part of CT2 Wiki.
[edit] How to write a good spec
[edit] Three C of good spec
For spec to be good it must be:
- Clear
- Correct
- Complete
[edit] SpecQA
SpecQA is a process of reviewing spec and reporting problems with spec.
See good example of SpecQAReport in http://mantis.jaguarfreight.com/mantis/view.php?id=2102
[edit] Optimal Use of History and Preview Features
Every wiki has a "history" - log of changes.
If you have particular task then commit final version ("Save page" button) it only after you finished.
Until then if you need to edit+preview+edit+preview then use "Show preview" button.
In this case History will have meaningful list of items and it is easy to use "diff".
If you save after every little change then it would be harder to see how many times it was changed and for what reason.
Also use "summary" field and "This is a minor edit" checkbox.
[edit] Top Down Approach, Correct Workflow, Collaboration
It is important to understand that wiki spec for component is one article but:
- multiple team members contribute to it
- there is a correct "flow": for example Business Requirements section must be written before Detailed Design section and if BR section is updated again then Detailed Design must be updated accordingly
[edit] How To Write It
- see Generic Spec Template (important!)
- see Wiki Template for Ops Admin
- see Wiki Template for Ops Pdfs
- see Wiki Template for Ops Reports
Examples of "well written" (but not ideal!) CT2 spec:
[edit] Creating a new article
- Pick the right name. See #Article name conventions
- Link it to wiki category. There is a category tree that starts with Category:CT2
[edit] See also
- http://en.wikipedia.org/wiki/Technical_writer
- About Software Requirements In General
- Use Case
- Wiki Editing Tips And Tools
[edit] RFC
This section contains not yet approved ideas.
[edit] Creating a new version of the spec
- Assume that article name is: Aaaa Bbbbbb Ccc
- If you believe that old version should be preserved then:
- Create new article named: "Aaaa Bbbbbb Ccc v2"
- In article "Aaaa Bbbbbb Ccc":
- set background "olive"
- add "orange" link to "Aaaa Bbbbbb Ccc v2"
