All titles of chapters, sections etc. are capitalized throughout.
All titles of figures, tables etc. have the first word only capitalized.
Spelling is US English. (According to The Webster's Second Unabridged.)
Use full URLs throughout all documents! Rationale: These documents may also be published in other formats then html on the ArgoUML web site.
Do not include lists of what changes have been done to the files. This information is kept by CVS, the version control tool. This is changed since Jeremy Bennet did the work for the 0.9/0.10 User Manual and there might still exist such lists. Remove them while changing the files!
The Cookbook has a Change Log (See Change Log) that is updated for every significant change but that is for the purpose of making it easier for the readers.
When problems in the current implementation of ArgoUML are mentioned
or perhaps even emphasized using the
warning
tag,
include the issue number in a sgml-comment in the source
so that it is easy to know if this problem has been fixed
when revising the document.
The issue should be mentioned in the format “issue xxx”, i.e.
there should only be a space between
the word “issue”
and the issue number.
This allows the tigris web site to
generate links when viewing
the manual source.
Do not write "currently". Better write either
"in version 0.14" if you mean in the stable version 0.14 of ArgoUML or "in
version &argoversion;" if you mean in the current version of the document
as defined in default.properties
when
the document is deployed.
There
are some old references to "current" or "currently" also. If you encounter
them, try to remove them!
For documents that contain an “index”, Add indexterms while doing changes. Creating the index is a good idea and we eventually should have indexterms all over. Initially, the manual was written without useing indexterms at all. They have been added generously on certain parts but that makes the index strangely biased.
Capitalize the part of the indexterms that are terms.
Don't use the tertiary level of the index terms but use only two alternatives: Only primary, and primary/secondary. If you are unsure when to use primary or primary/secondary use the small word approach. I.e. if the indexterm contains a small word (typically to, of, for, in) and normally not capitalized, let the secondary start with that small word.
When using primary/secondary, see that you get the same kind of word as used before in the index (especially when it comes to differences in singular/plural-form). Also create other indexterm by turning the phrase to as many permutations that you can think of.