Writing the Documentation First
— how to bring more of your ideas to life —
--
In an effort to increase productivity in my development of open-source software, I have begun to plan my code much more thoroughly than before. Although many hold to the belief that planning itself drains productivity, my method of planning does not fall into the standard definition of planning.
Documentation has always been close to my heart. I take great pride in ensuring documentation for all my projects is clear and organized, while always favoring descriptiveness to brevity.
Take a look at the documentation for Git Goodies in which I had an image example of the output of every command possible. This command reference is preceded by an introduction that is in story-form, portraying a common scenario during which Git Goodies would come in handy. This approach kills three birds with one stone because the introduction acts as a friendly transition into the project, provides use-cases for the project, and even shows the reader just how easy and intuitive the project really is.
I used to write a project’s documentation after all the programming for the initial release had been completed. Writing the documentation at this time allowed me to program with few major interruptions and since the program was finished (for now), writing allowed me to reflect on the development of the project.
I followed this method of writing documentation for a majority of my current projects, including Git Goodies. Recently, however, I have flipped my workflow around.
As the projects I undertook increased in complexity, I realized that some planning would be required in order to keep everything in order; both in my brain and in my code.
I began by creating a Trello board for each project; however, I soon learned that too much of my time was spent on Trello and not enough of my time was spent in my text editor.
Eventually, I came to realize that writing documentation was a great way to plan out the specifications and use-cases of the project. Thus, leading to me writing the documentation beforehand versus after the project had been completed.
Documentation generally contains content pertaining to installation and usage of the program. As most of my projects are open-source libraries or tools for developers, the documentation also held an in-depth look at the methods or commands complete with parameters and outputs.
As I am writing the code, I tend to use the documentation as a checklist; thus, the documentation ends up being a very effective blueprint for the project as a whole. As everything is out of my head and now on paper, I am able to put more of my mind toward writing code.
One way you know your documentation is useful documentation is if you are able to work backwards and end up with a complete program. Writing the documentation first allows you to test your documentation and make edits and improvements where and when needed. Additionally, it serves as an opportunity to proofread and check for any mistakes — grammatically or specification-wise — in the documentation.
Although this workflow saves time by completing two tasks with one required task, it is not perfect by any means. Here are some pitfalls that I have run into and that may be enough to push some away from this methodology.
For starters, writing the documentation first gives you a false sense of accomplishment, analogous to one you might feel if you write a review of the book you haven’t written yet. As a majority of us write our documentation after completing the project or a portion of the project, seeing the completed documentation is as good as completing the outlined code.
This can lead to laziness in completing the actual code, which makes the documentation you wrote 100% useless and the time you spent is now wasted. I hate to admit it, but two projects with major potential went down the drain this way. Four months later, I am now attempting to resuscitate these projects. I can’t be certain that using this workflow alone led to me not finishing the project; however, I am certain it was a large factor.
Additionally, sometimes it’s difficult to judge how difficult a feature of your project will be to implement. Due to this, you may still have to spend time fine-tuning and updating your documentation while or after programming.
On the bright side, writing your documentation beforehand allows you to spot and suppress any bugs or issues that may arise during the actual development. In some cases, it may even save you from writing a bunch of unfeasible and useless code.
As always, the most important factors in undertaking large projects are your willpower and motivation to complete the project itself, regardless of when you write the documentation. With the right mindset, you can take advantage of the benefits of writing documentation beforehand while avoiding the pitfalls.
