Confirmed users
586
edits
Platform/GFX/DesignDocumentationGuidelines: Difference between revisions
Platform/GFX/DesignDocumentationGuidelines (view source)
Revision as of 15:06, 13 May 2014
, 13 May 2014→In a separate file in the gfx/docs directory: s/docs/doc/ because that's what's in m-c
Msreckovic (talk | contribs) |
(→In a separate file in the gfx/docs directory: s/docs/doc/ because that's what's in m-c) |
||
| (2 intermediate revisions by one other user not shown) | |||
| Line 2: | Line 2: | ||
== What == | == What == | ||
=== Documenting design for the upcoming work === | |||
We will start the conversation about the design in a bug. Design work in progress can be attached to the bug, we can record feedback, reviews, etc. It is expected that we will keep those documents in the same format as what will eventually be landed to gfx/doc directory. | |||
Once the design is mature enough, even if not complete, it should be landed in the gfx/doc directory. We want to make sure that the design in progress is differentiated from the final design, or that which already has implementation behind it. The recommended approach is to create an empty level 2 header that describes that state of the document. This should immediately follow the first level 1 header in the document. | |||
=== Documenting design for the historical work === | |||
In this case, we're trying to retroactively document the design of something that already exists. As soon as something useful exists, we should land it, even if it does not completely document the design. This is especially the case if multiple people are going to be needed in order to document the whole piece of work. Like above, make sure the first level 2 header is explaining the fact that this is work in progress. | |||
== How == | == How == | ||
| Line 20: | Line 30: | ||
** The documentation is subject to reviews | ** The documentation is subject to reviews | ||
=== In a separate file in the gfx/ | === In a separate file in the gfx/doc directory === | ||
* Name the documentation file appropriately, use the .md extension (assuming it is markdown) | * Name the documentation file appropriately, use the .md extension (assuming it is markdown) | ||
| Line 53: | Line 63: | ||
=== What kind of a bike shed would you like? === | === What kind of a bike shed would you like? === | ||
Using ====== for level 1 headers instead of # seems to play better with Doxygen when using the labels: | |||
This is header level 1 {#nameofthefileinlowercase} | |||
This is header level 1 | |||
====================== | ====================== | ||
rather than | |||
# This is header level 1 {#nameofthefileinlowercase} | |||
== Results == | == Results == | ||
If we follow the above rules, everything should nicely get extracted to html, for those browsing graphics documentation pages, while also providing in source information for those browsing the source. | If we follow the above rules, everything should nicely get extracted to html, for those browsing graphics documentation pages, while also providing in source information for those browsing the source. | ||