I come across some really shitty documentations and some really nice document formats. Formats are important to documents, some might disagree that content matters more. But seriously aesthetics is what attracts you and what holds you on to something… That is why there are two words ugly and beautiful! So some documentation tips
- A simple terse heading on the cover page with Author name, revision and date. — Just like one would not want to meet a crowd at once, one who not want showers of text information at the beginning of a page.
- A small footer with Footer/Header in plain text colour, a slightly smaller font — It is the frame for the document Not a rough area to scribble tonnes of information
- Insert a Table of Contents at the beginning of the document with Cross referencing
- No Justified text for heavens sake, its like giving the reader a text to read on convex mirror
- Use of inbuilt Heading formats
- Do not increase indent as you go on with sub-headings. There is not point wasting so much indent space.
- Bold Arial Headings and Regular TimesNewRoman(Arial) paragraph text
- Use ‘captions’ options for Figures and Tables
- Use Cross Referencing in paragraphs to point to Tables and Figures
- Create inline diagrams. Do not insert .bmps or jpegs or cropped pictures.
Here is a document that I am maintaining for my usage, can be freely distributed and used. Git-SVN-Workflow and Moving to Git
Suggestions and more tips invited.