Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Documenting the Manual

Goals

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.

Writing Style

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.

Illustrations and Graphics

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.

Vocabulary and Jargon

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.

Contractions

Avoid use of English contractions: can't, won't, isn't, etc. These are common use, but they reduce the professionalism of the documentation.

English Slang and Idioms

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.

Pronouns

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.

Documenters are encouraged to avoid the use of "you", the second person, in their submissions; this tends to come across as a personal connection in English writing and such a degree of informality in a reference manual is not attractive; we decide to leave that approach for friendly letters and emails. Instead, try to use "we" when discussing matters that require some sort of pronoun use. It seems to be an acceptable level of informality for a manual and connects the readers with the authors; it also may communicate a feeling of participation because "we" sounds like everyone is involved in the content discussion.

In reference to using "you," there is one situation where it is permissible in the interest of convenience: that situation involves the use of "you" when it is understood but not expressed. An example: "Note that the installation..." and "Examine the source code." In these cases, "you" is understood. This style guide declares these situations acceptable practice. Once again, though, avoid overuse.

Please avoid the use of "one." The gender neutral style is considered extremely formal in English and is probably the fastest way to engender disinterest in a reader.

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.

Parentheses

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.

Other Items

  • Paragraph structure, length (full block versus indented paragraph): wiki default for now
  • Spacing: paragraph, section, titles: wiki default
  • Titles: format, phrases

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, and/or when division into specific classes or interfaces are made.

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 Standard formatting for how to format headings, symbols, code and other elements in the reference.