Documents are meant to be beautiful

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.
Shyam

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: