A Document on Documenting

What seperates the laymen from the technicians? Is it truly their superior intellects? Or, perhaps, is it the fact that they merely organize information in their minds better and more efficiently? Perhaps both reasons or none at all explain the positions they hold in their respective occupatorial situations. However, this document discusses neither Intellectual Theory nor Social Inferiority/Superiority complexes it merely states a definitive documentation of proper conduct when writing tutorials for posting on the site.

The key reason for documenting anything spawns from the belief that people learn and absorb information from reading. These articles, therefore, should follow a few logical guidelines.

The guidelines go as follows:

• Assume only that the reader wants to understand the topic of discussion.
• If possible split the discussion into sections delimited by difficulty.
Provide links to other topics regarding current topic of discussion.
• At the begining of a document state clearly the purpose or intent that the document attempts to clarify.(I personally do not believe in prettying up an article just so it sounds good... I mean, how nice can you make an article on SCSI interfaces?)
• Use proper header tags <H1 - H6> for titles and or important points of the document.
• At will, go into as much detail as necessary. Most times, though an article tends to go so deep that it seems logical to simply splinter off an article into its own topic of discussion.(Example, if talking about SCSI interfaces and you segue to a topic of ATA interfaces if the article necessitates a deeper discussion of the topic necessary for understanding the current topic of discussion then suggest reading more on ATA interfaces, until a hard link can be made to the topic. Then, provide a proposal for the document you need to the Documentor group.)
• Give each other feedback... if you see a typo, report it ... if you think part of an article is confusing, even for you... perhaps you could create a spawned topic discussion.

Make a proposal here. View the proposal log.