=============================================================================== ***Guidelines For Proper Documentaion*** ------------------------------------------------------------------------------- Aurthor: Brad Byrd Date created: August 08, 2004 Version:1.0.0 Descripstion: Tells the procedures used in making documentation files =============================================================================== The following indicates the proper format of the documentation files. This section would be used to tell any message that is non-documentation related to the user ========== A. HEADERS ========== Headers tell the reader what is in a certain section. There are three types of headers. (a) MAJOR HEADERS (b) MINOR HEADERS (c) SUB-HEADERS MAJOR HEADERS denote a certain topic of the minor headers below it such as "GETTING STARTED". The topic should continue until the next major header is reached. MINOR HEADERS denote a more specific topic such as "Configuration" The topic should continue until the next minor header is reached. SUB-HEADERS should only be used for Guidelines, Steps and Lists. The proper format for sub-headers is 6-space indent and the title should be in all caps also they should have atleast two seperarting lines on both the top and bottom. All text should line up with the sub-header start. and the title should have one blank line betweewn it and the text. For an example of how to use headers examine this document. 1. GUIDELINES FOR HEADERS ------------------------- (a) To maintain a professional appearance of the help files please make sure that the symbols ("=" and/or "-") cover the entier line of text (see example below) (b) "MAJOR HEADERS" are the headers that have the equal (=) sign on both the top and bottom and should be denoted with a capital letter (EX. A, B, C). "MINOR HEADERS" are the headers with dashes on the bottom only and should be denoted with numbers (EX. 1, 2 ,3). The numbers should have periods after them. (c) Should you run out of letters for the "major headers" you can use double letters. This however should be avoided if at all possible. (d) When useing pointers in a sub-header the "one space rule" will apply unless otherwise noted. (e) Two blank lines should follow the end of a major & minor header. This rule dose not apply to sub-headers. (f) Unless otherwise noted it is not necessary to make titles all caps. (g) All headers (including sub-headers) can have an optional "introduction space". after the introduction sapce one blank line should follow 2. Example of header useage --------------------------- This section will demonstrate the correct methods of useing headers. (a) Correct method of makeing headers MAJOR HEADERS ============= A. Title Here ============= MINOR HEADERS 1. Title Here ------------- =========== B. Pointers =========== Pointers are the symbols, letters and numbers used to tell a specfic point. This is required when making Steps, Guidelines and lists. This section will tell the proper method of useing pointers and what types to use for differant situations. 1. Steps -------- Steps are used to to tell the end user the proper method of a certain procedure and should use numbers (EX. 1, 2, 3) EXAMPLE OF USEING STEPS 1. sit in chair 2. turn on tv 3. enjoy STEPS FORMATTING (a) A period should follow the number. (b) Three-Spaces should seperate the pointer from the text. Except when used in a sub-header and then the one space rule applies. However the pointer should still line up with the sub header. 2. Guidelines ------------- Guidelines are used to to give non-specific instructions and/or conditions to the end-user. Guidelines should be denoted with lower-case letters with parentheses around it. EXAMPLE OF USEING GUIDELINES (a) insert guideline here. (b) This is how more than one line should look, This is how more than one line should look, This is how more than one line should look, This is how more than one line should look, This is how more than one line should look. GUIDELINE FORMATTING (a) Guidelines such as this one can be used anywhere in the document. However Three spaces must seperate the pointer and the rest of the text. Except when the guideline is used in a sub-header and then one space should be used. However the pointer should still line up with the sub-header (b) Quotes count as spaces and thus do not have to follow the four space rule (see: "Guidelines for headers" for an example) except when used under sub-headers and then the one space rule applies. 3. LISTS -------- List are used to list the features the software or other software related items (see example below) EXAMPLE OF HOW TO USE LIST By the time you read this file you will be able to. * Properly format a documentation file. * make your help files more readable to your end users. (a) Lists can be used to list features or "exepectations" (what you expect the user should be able to do after reading the help file). ======================== C. Documentation headers ======================== Below is the proper format for the "documentation header" (the header at the very top of this document) Just copy and paste it at the very top of your Documentation file (if you use the program this will automaticly be done for you) =============================================================================== ***Title of document*** ------------------------------------------------------------------------------- Aurthor: Date created: August 08, 2004 Version:0.0.0 Descripstion: =============================================================================== =========== D. EXAMPLES =========== You can use examples for when you have a pice of code (in the case of the above example it was used to put the proper format of the documentation in the document examples can be used in this way as well) or that might be a bit on the long or complex side 1. Guidelines for examples -------------------------- (a) A min. of 5 spaces is required 8 is the recommend number however. (b) Two blank lines must be at the top and bottom. (c) Examples can only be used in MAJOR/MINOR Headers, they cannot be used in a sub-header. ====================================== E. Closing Statement / End Of Document ====================================== At the end of a readme file or header (except sub-headers) you can close-out you topic with few closing remarks. This section will also deal with properly ending a Documentation file 1. Guidelines for closing statement ----------------------------------- (a) Keep them brief. (b) No header is required for closing statements just four (4) blank lines. You may however if you choose use a MAJOR HEADER as the start of you closing statement. (c) If you decide to use a header treat the closing statement as an "introduction space" (d) Refrain from useing phrases such as "End" and "The End". 2. End of document example -------------------------- The following indicates the proper format or the "End Of Document" Footer. Copy and paste this into your document. =============================================================================== **insert text here** =============================================================================== 3. Guidelins For End Of Document Footer --------------------------------------- (a) in the "**insert text here**" spot you can put any text you like. Keep it to one line and don't go past the equal line. This document covers the rules governing the creation of documentation files for the Directo link tracking system Anybody is free to use thease guidelines.