Complete Guide to Developing a powerful documentation - Lab Diary

John D K -

One of the most important programming skills to develop, for those just starting out in programming (and everyone else!), is the skill of managing information.

Next post: Better programmer - Blindfold programming

Next post: Better programmer - Blindfold programming - practical tips

It’s like a lifeline(a rope or line used for life-saving, typically one thrown to rescue someone in difficulties in water): when I started my Lab Diary, I started researching and qualifying better, filtering information and writing more, I quit asking superiors and developed my first application, I started this project and wrote a blog, I search less and work faster, I transformed my workday completely. I’m far from perfect, but I’ve progress a lot - comparing then and now it's like comparing black and white.

But if you don’t manage information so well, it could cause issues: "short memory problem" (I remember something but not enough), reinventing the wheel, procrastination, disorientating, confusion, tasks piling up and overwhelming you, and much more. So it’s such an essential skill to develop, but most people don’t know where or/how to start. This guide is aimed at helping you get started.

First things first - Lab Diary initialization

The first question that a friend asked me was: Why to create such a documentation if I have Google? Most of us don’t want to think about documentation, let alone take a bunch of actions on daily basis. For me, the motivation came from realizing that what I was doing was wrong or not enough. Ignoring the problems only made them worse and bigger. Working with great volumes of information could cause headache and burden.

Once you realize that you’re not efficient enough … you should start improving your routines slowly and persistently. Think of this like investment in yourself tomorrow - the quality information is one of the best investments nowadays. On contrary web is full with bad or duplicated information - you don't want to spent hours in surfing just to find a single line of code. A line of code that you already had and used in the past.

Lab Diary benefits

Some people are writing down on paper, other use only memory I myself prefer to use digital way of storing data. The benefits are:

  • Search - It's great to be able to go through thousand of lines in seconds
  • Copy & Paste - remember the last time when you had to "copy" from paper or image. What a loss of time. Mistakes are also very likely. Even for a simple code like this snippet copy & paste is indispensable.
public class HelloWorld {
    public static void main(String[] args) {
        // Prints "Hello, World" to the terminal window.
        System.out.println("Hello, World");
    }
}
  • Eternal Memory - once written forever available. Unlikely people who rely only on memory. If you met a problem and have a solution.
  • Independance - this way will allow you to have access to the solution no matter of internet connection or site availability. I remember when StackOverFlow was down(even for 5 minutes could cause a panic) that many developers were not able to produce a single line of code.

Lab Diary tools

The tools that I'm using are:

  • Typora - Windows, Linux and MacOS. Typora will give you a seamless experience as both a reader and a writer. It removes the preview window, mode switcher, syntax symbols of markdown source code, and all other unnecessary distractions.
  • HelpNDoc - Windows and Linux (working with Wine)
  • HelpNDoc is an easy to use yet powerful and intuitive tool to create HTML help files, help web sites, printed manuals and eBooks.
  • free for personal projects
  • Help+Manual - Windows
  • Help & Manual from EC Software is the favorite authoring tool for writing online help and technical documentation.
  • paid version
  • XMind - Windows, Linux, Mac OS
  • XMind is a brainstorming and mind mapping application. It provides a rich set of different visualization styles, and allows sharing of created mind maps via their website.
  • free - basic version
  • Freeplane - Windows, Linux, MacOS
  • Application for Mind Mapping, Knowledge Management, Project Management. Develop, organize and communicate your ideas and knowledge in the most effective way.
  • free

Lab Diary topics

Defining topics and categories is another important point. My rule is: topics should corespondent to knowledge areas:

  • Projects - describe all projects in 3 categories
  • current
  • completed
  • planned
  • Technical information - everything related to technical knowledge
  • applications
    • Browsers
    • IDEs
    • Mail clients
  • code snippets
  • language basics
  • algorithms
  • Design
  • templates
  • themes
  • Examples
  • example mails
  • example projects
  • OS administration
  • Windows
  • Linux
    • shell commands
    • Linux terminal basics
  • Mac OS

This structure is a sample one. It's better to start with a smaller one and gradually to shape it to your needs. The ability of modifying topics hierarchy and levels is from great benefit. If you are working in marketing area you could do:

  • Marketing
  • Social
  • Online Media
  • Content Management
  • Articles
  • Blog
  • Images
  • SEO
  • Online
  • Offline

Example structure from Help'n'Doc:

You can define topic name, structure, topic icon and all this in free and user friendly interface.

Conclusion

A huge mistake that a lot of people make with documentation is that they mess up at the beginning, and get discouraged by this. They feel bad about messing up. This causes them to give up and not want to continue with their Lab Diary.

Here’s the key: Give up is not an option. My favorite quote on the topic:

“Giving up is the only sure way to fail.” - Gena Showalter.