Login | Register
My pages Projects Community openCollabNet

Wiki: Document Conventions

Edit this page | Links to this page | Page information | Attachments | Refresh page

  • The Quick Guide and the User Manual source contain the source for all supported languages in the same file. The choice of languages is controlled by the existance and value of the lang parameter in the low-level docbook tag (para, title, phrase, indexterm, ...).
      • Set the lang parameter on a low level in the document. The structure of the document shall be the same in all languages so the paragraph level is the appropriate one.
      • For each para, title, phrase, or indexterm always use the same order for the languages namely English, the source language, followed then by the other languages in alphabetic order. Example en, de, es.
      • 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 than html on the ArgoUML web site.
      • 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 using 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.


Document Conventions (last edited 2009-01-06 00:58:36 -0800 by linus)