Tag Archives: Information Technology

Documentation – The last 10%

Documentation is often the last step in a project plan. It is also the most often to be forgotten, leaving a project 90% complete. Originally I was one who tried to build documentation using the wrong tools and strategies. I assumed that I would start with a blank document and fill it up with a brain dump of information. With careful editing this would culminate in a well written and well structured document. Project complete. It never works that way for me. In fact I have seen many others fail in frustration trying to document the exact same way. So then what happens? Everyone just stops documenting all together due to frustration.

So how can I create effective documentation? First off I needed to realize that there is no wrong way to document as long as I kept a few rules in mind:

1. Understandable

Does what I am documenting make sense? Should there be additional context to go along with it?

2. Retrievable

Am I documenting in a way that I can find it again? Am I documenting in a way that will let me share it with others?

3. Relevant

This helps to define my scope. Do not overdocument, no need to document the entire install process, that is irrelevant. The installation keys, that is relevant.

 

I found that running documentation is a good habit if it can be maintained. As a project builds out if I can take 20 minutes to build a quick list of relevant information. It can be on sticky notes, text document, a word document, screenshots. Really it is about capturing the information in the moment. Everyone works a little differently. Worry less about the medium and more about the content.

As the pile of diverse information grows I need to organize. I find it easier to brainstorm and framework out my documentation using a mindmap tool such as: xmind

The amount of documentation can be overwhelming, and this helps to put my thoughts in order and create manageable sections that I can fill out.

Simple mindmap example:

Screen Shot 2015-01-29 at 5.09.37 PM

Now it is time to start putting those notes, images, and code snippets in folders or piles relative to the structure. Often it turns out that there is a lot more information I can put in my documentation than I thought, if I have been doing it properly it almost ends up building itself.

 

Server Upgrade:

  • Hardware
    • Dell R730
    • MAC: 01-80-C2-00-00-00
    • Notes: System was purchased 10/2/2014. See purchase order: 123456
  •  Hypervisor
    • ESXi v 5.5
    • DNS name- esxi.foo.bar
    • IP – 123.123.123.123
    •  Configuration
      • Username: test
      • Password: test123
      • Note: Change the password before 12/12 rollout
  • Operating System
    • CentOS 7
    • DNS name – web.foo.bar
    • IP – 123.123.123.124
    • Configuration scripts are stored under /home/newuser/confscripts/
  • Software
    • Apache v2.4
        • Sites – mysite.foo.bar
        • Ports – 80, 8080, 443
        • httpd.conf

      Listen 80
      ServerRoot /usr/local/apache2
      DocumentRoot /usr/local/webroot
      ...

    • SSH
      • Port – 22
      • Notes: disable root login

 

Some useful tools for documentation. If they don’t work, try something different, the key is to find a workflow and a set of tools that works WITH you not against you. This way you can build documentation into your daily operation.

Windows Documentation Tools:

  • Notepad++ http://notepad-plus-plus.org/
    • Great notepad utility for capturing notes, code snippets, includes syntax highlighting, and tabs. Keep it open and just throw info into a new tab
  • Greenshot http://getgreenshot.org/
    • Takes the pain out of capturing screenshots. Simple printscreen button gives you the option to select a region. And you can set it up to automatically name and save the images into a folder

OS X Documentation Tools:

  • OS X built in screen capture tool
    • It just works. (Command+Shift+4)
  • Sublime Text http://www.sublimetext.com/3
    • Another great text editor, this time for the Mac. Provides a simple and easy to use interface, with A LOT of power under the hood. Extensible through packages as well

Crossplatform:

  • Google Documents/Drive
    • Work on that documentation anywhere and collaborate with others.
  • XMind https://www.xmind.net/
    • I am addicted to this tool; The free version still has a ton of features and makes organizing your thoughts and taking notes so seamless. I highly recommend giving it a try, there is no wrong way to use it.