Changes between Version 18 and Version 19 of Manualdocumentation

Author:

larsivi (IP: 85.221.53.194)

Timestamp:

01/11/07 15:23:00 (17 years ago)

Comment:

Added section on how to structure a reference chapter

Manualdocumentation

@@ -1 @@
-= Documenting the Manual =
+ Documenting the Manual 
-
-
+
-
-'''''Very important:''''' the manual should not only tell you ''how'', but ''why''. This is what makes it more useful than the API documentation. Use examples, relationships-graphs, speculative ideas, whatever, to get the ''bigger-picture'' across -- to tell the user what they can ''do'' with the library. Without that, the manual will make for a very tiresome read. 
-
-
+
-
-Style is important.  We need to consider how we want to present the material here.  Formal technical writing typically employs short, choppy declaritive sentences; while readable, such a style is an extremely boring study for most readers.
-There are ways to make the reading more pleasant.  The idea is not to use sloppy grammar and idiom-filled English, but to adopt alternate sentence structures that vary the pace of the documentation.  This means changing sentence structure in paragraphs frequently and keeping paragraphs as short as possible.  Try to avoid sentences that are too long.  Concise expression of details is still preferred over lengthy complex discussions. With the right mix of style, Tango users will find reading much less strenuous than that of the typical technical work.
-
-
+
-
-Use illustrations and graphics as oft as necessary.  Often illustrations are excellent means of explaining material better than words.  Consider the use of graphs to demonstrate comparative data.
-Jargon is permitted as long as the definitions are easily referenceable (footnotes, endnotes, appendices). An appendix may be appropriate for technical jargon that will be frequently used throughout the book; Jargon that is used only once in a chapter may be footnoted.  D oriented jargon should be clearly defined in an appendix.  Examples of technical jargon are abreviations such as "RTTI" and "RAII" or words like "call-chaining" and "dynamic closures."  D specific technical jargon are all keywords and techniques specific to the language.
-
-
+
-
-Avoid use of English contractions: can't, won't, isn't, etc.  These are common use, but they reduce the professionalism of the documentation.
-
-
+
-
-Avoid use of English Idioms: "piece of cake", "catch-22", and "hold your horses".  Documentation should not be too localized.  Avoid use of regional English slang: "freebie", "cool", or "gut."  We want it to be digestable by international readers as well.  Furthermore, we do want to maintain some level of formality.
-
-
+
-
-While the a manual's writing style may attempt a certain level of formality, it is important not to sound officious and dry, a dangerous mode that might ensnare our readers in absolute boredom.  Boredom may be inevitable considering the volumes of information that must be covered.  Nevertheless, we must attempt to use a style that is not so likely to encourage the condition.  
-Finally, try to avoid overuse of even the acceptable pronouns, if it can be helped.  For example, try not to use "we" in every sentence. Mix things up. Vary the noun and verb positions a little.  Try to keep the flow of the text going. Perfection is rarely attainable, but we can aim for it.  
-
-
+
-
-Avoid overuse of parentheses in a sentence.  Reorganize the sentence or separate the parenthetical thought into its own sentence in such a way that it sythesizes with the original sentence.  Using parentheses interrupts the flow for the reader and often inserts details that are not completely parallel to the expression of the original. Use them carefully and sparingly and only if there seems to be no other way to express a detail.  Remember that in most cases there is another way.
-
-
+
-
- * Paragraph structure, length (full block versus indented paragraph): wiki default for now
-
-Note that submissions may be edited.  That means grammar, spelling, and sentence structure may be changed in an attempt to maintain style consistancy throughout the manual.
+
+== Structure ==
+
+A chapter in the reference can wary quite a bit, depending on the nature of the content.
+
+The suggested structure below, should be at least partially applicable to a typical chapter describing one a package in Tango, though.
+
+'''Title'''
+
+A paragraph or two introducing the subject of the chapter and what follows.
+
+'''Important concept'''
+
+An introduction to the concepts, and possibly interactions between these, necessary to get the big picture. The chapter may have more than one of these sections, but preferably no more than two or three (more than this, and a breakdown into further chapters should be considered). Only the most obvious of packages should consider leaving this section out at all.
+
+'''Module''' (format heading using {{{ [[docs(ModuleName,FQNModuleName.html,h2)]] }}} )
+
+Note that FQNModuleName.html means something like tango.text.convert.Integer.html.
+
+All modules should have it's own section, as long as it sees public usage. The sections can have sub-sections when talking about the functionality of the class.
+
+All public symbols, and important protected ones, should be listed and explained to some degree. Note that if several symbols do similar work, they can be grouped together.
+
+'''In review'''
+
+Should be in all chapters, summarizing the content.
+
+'''Additional Notes / See also / References'''
+
+Points of interest, links to deeper material, tangential information, links to examples, etc
+
+See '''[wiki:StandardWikiFormatting Standard formatting]''' for how to format headings, symbols, code and other elements in the reference.
+