Difference between revisions of "User:Dzonatas Sol/AWG Design Document Template"
Jump to navigation
Jump to search
Dzonatas Sol (talk | contribs) (template guideline for AWG design documents) |
Dzonatas Sol (talk | contribs) |
||
| Line 1: | Line 1: | ||
{{:AWG/PageHeader}} | {{:AWG/PageHeader}} | ||
= Guidelines = | |||
* Review [[Design Document Template]] for insight of needed content. | |||
* Title each page with "AWG ''NAMEOFDOC''" where ''NAMEOFDOC'' is the actual name. If possible, upper case only the first letter of each word in ''NAMEOFDOC'', as it is typically done for a title, like "AWG Document Title." The first four characters "AWG " are significant to the macros. | |||
* Start each page with <nowiki>{{:AWG/PageHeader}}</nowiki> in order to transclude the header layout (as shown above) and its macros. | |||
* Avoid generalizations in the Description field. As much as possible, write statements in terms of the now, which means there is an actual model to describe. Also, the use of grammatic infinitives is a bold indication of a generalization (some usage in nouns is unavoidable). Remember, any generalization in design is a bottleneck in implementation. | |||
* Keep the Description field concise but mappable. Use <nowiki>{{AWG|</nowiki>''NAMEOFDOC''<nowiki>}}</nowiki> to map to other AWG design documents. Any specifics beyond basic purpose, terminology, or mappable usage goes in another section (and refer to [[Design Document Template]] for possible sections). The description being mappable to other design documents is a power of the wiki -- use it! (especially to map back to the article itself, for example "A <nowiki>{{AWG|</nowiki>''NAMEOFDOC''<nowiki>}}</nowiki> is ...") | |||
* Upload an icon for the page under the name '''AWG_''NAMEOFDOC''.png''' where ''NAMEOFDOC'' must have underlines instead of spaces. A macro in the pageheader detects the image and inserts it automatically. For now, the icons are sized to 100x100px. Icons are a good means to graphically map the model, so it is good to keep them distinct from each other (or redo them to make them more distinct). | |||
* Use regular wiki sections below the pageheader. If there a specifications, create a "Specification" section. | |||
* Any ''talk'' in the main article is subject to be rewritten to make a formal statement about the design or can be moved to a more appropriate (discussion) page. | |||
Revision as of 08:04, 21 October 2007
|
||
|
Description:
| ||
Guidelines
- Review Design Document Template for insight of needed content.
- Title each page with "AWG NAMEOFDOC" where NAMEOFDOC is the actual name. If possible, upper case only the first letter of each word in NAMEOFDOC, as it is typically done for a title, like "AWG Document Title." The first four characters "AWG " are significant to the macros.
- Start each page with {{:AWG/PageHeader}} in order to transclude the header layout (as shown above) and its macros.
- Avoid generalizations in the Description field. As much as possible, write statements in terms of the now, which means there is an actual model to describe. Also, the use of grammatic infinitives is a bold indication of a generalization (some usage in nouns is unavoidable). Remember, any generalization in design is a bottleneck in implementation.
- Keep the Description field concise but mappable. Use {{AWG|NAMEOFDOC}} to map to other AWG design documents. Any specifics beyond basic purpose, terminology, or mappable usage goes in another section (and refer to Design Document Template for possible sections). The description being mappable to other design documents is a power of the wiki -- use it! (especially to map back to the article itself, for example "A {{AWG|NAMEOFDOC}} is ...")
- Upload an icon for the page under the name AWG_NAMEOFDOC.png where NAMEOFDOC must have underlines instead of spaces. A macro in the pageheader detects the image and inserts it automatically. For now, the icons are sized to 100x100px. Icons are a good means to graphically map the model, so it is good to keep them distinct from each other (or redo them to make them more distinct).
- Use regular wiki sections below the pageheader. If there a specifications, create a "Specification" section.
- Any talk in the main article is subject to be rewritten to make a formal statement about the design or can be moved to a more appropriate (discussion) page.