Monthly Archives: October 2010

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

RecordMyDesktop

I used an utility on Linux some time back to demonstrate an application that I developed. “Anything that can go wrong, will go wrong” – Murphy’s law. And so, I did not want to have a live demonstration. Not that my app code is flaky, but things screw up at the demo, no matter how hard you try and hang your self upside down, it does nt matter. It just goes wrong..

So I used this utility to record the procedure for executing the app. And yes the presentation went really well. The utility is called RecordMyDesktop.

I tried documenting a small procedure on installing and using this app. Here is how.

https://docs.google.com/document/pub?id=17SeRczNA_CafxBZ9qSmvy6otbo4K62mvV7e1qnYEdT4&embedded=true

Thanks
Shyam