Okay, I am writing the GLM API reference manual pages and I think we should
decide on some doc conventions.
1) Should we use verbs in imperative form or in present tense form? For
example, which is better:
* (imperative) Convert radians into degrees.
* (present tense) Converts radians into degrees.
2) What is the general layout of a reference pages? Some ideas:
------
DESCRIPTION
Converts radians into degrees.
Parameters
radians -- radians to convert
Return value
Returns *radians* as degrees.
or perhaps:
------
DESCRIPTION
Converts radians into degrees.
PARAMETERS
radians -- radians to convert
RETURN VALUE
Returns *radians* as degrees.
Other sections; SEE ALSO, COPYRIGHT etc.
3) Anything else we should decide on?
At some point we should establish documentation editors who would have
access to our SVN 'docs/' subdirectory, and who go through the docs and
correct any misspellings and typos and check the conformance against our
conventions. These editors should be native English speakers, which I am
not.
--
Henri 'henux' Häkkinen |
