Right from requirements, design, development to delivery and release notes, documentation is a vital and critical activity (ref). Software documentation not only helps in listing the product capabilities, use cases, design, technical and test documentation, release notes etc., but it also helps in recording the ‘tribal’ knowledge and know hows which often just transcend within the team verbally.
It is also a good idea to record certain assumptions, notations and discussions taken when designing the architecture and design of the product which can be referred at a later point in time, thus corroborating certain architecture (or design).
Documentation in Small Projects
I have often seen and have experienced, that when working on small projects, people generally shy and desist from documentation.
Over time I have realized that there is no way of quantifying small. Sometimes these small projects grow into large solutions, sometimes they are re-used as components or features, sometimes act as reference for other projects.
At times like these, documentation comes as great aid. Without dwelling deep into code-base and comments, the general outline, flow of control, interface API definitions, parameters and return values can be understood on a high level thus making it easier for taking the next call.
Development setup & Ramp up of New Devs
During setting up new machines (dev or lab or production), a good setup and deployment guide is very handy and saves tens of man hours which otherwise are wasted in setting up the machines on a ad-hoc basis. If all the dependencies, pre-requisites, network configuration, firewall settings of a system are documented, the set can be easily handed over to a system administrator for configuration thus saving on time and energy.
Documentation helps new person get on-board the project easily and smoothly, without frenzy. If the development teams are geographically distributed, then it helps a great deal to get ‘on-the same-page’ faster with less confusion. They help in better maintenance of projects over long durations of time.
Documentation should no way be limited to above listed spheres of content but are also used for product setup, installation guide, software setup and pre-requisite listing guide, user analysis, project management, planning, etc.
Documenting using Microsoft Word
The traditional approach of documenting the information to be communicated (or shared) for preservation over time is saving it in Microsoft Word. For long, people have relied on Microsoft Word for storing, sharing and reviewing the documents. Generally people add a tracking page/table at the beginning of the document, and with each iteration keep on adding an entry for the changes made since last version (or release or iteration) and by whom. Something like this:
And then these are either saved on a team SharePoint site (or library) or are checked into the source control system (or version control system).
Documenting using Wikis
GitHub and BitBucket offer a more simplified and unified way of sharing and hosting documentation, called Wikis.
You can create content and documents using open-source Markup libraries like GitHub Markup, Markdown, TexTile, etc. They have a simple easy to write and easy to read syntax which can generate rich and valid HTML (including lists, quotes, tables, code blocks, etc).
You can easily track a wiki’s history for changes and view an old content.
You can select two different revisions and see the changes. Revert them if required. One of my favourite here is cloning the wiki locally, making it easy to add, edit or commit my changes. The file type extension used to save the pages determine what kind of converter to use to generate the markup, eg .md for Markdown, .textile for TexTile converter.
You can also add other file types like pdfs, txts, word, ppt, etc directly to the wiki repository, and then push these changes to the master branch to make it available to others and wiki readers.
In case you are working on a collaborative project but still want to restrict editing permissions to other collaborators you have the options to turn that off.
So, when you plan to move from other systems to a platform like GitHub or BitBucket, it is always good to leverage the options provided by these services and use them to the fullest.
Your Thoughts
Have you ever faced a situation when you realized a document around such-and-such would have helped you? Or you think your office follows the best process and practices which are different from the above mentioned approaches. Do share with us in comments below or message us on Facebook. We promise to document it and share with you all. :)