Most serious engineers have learned to appreciate a medium for saving thoughts, decisions, and results of experiments or discussions for later reference. This is no less valuable for the software developer.
Personal Blogs
One of my motivations for writing this software development-oriented blog is as a form of a pensieve for observations and lessons learned related to software development. My JavaWorld-syndicated version of this blog includes this very motivation in its description: ‘This blog is intended to provide information to help other developers facing the same issues as well as providing me a method to document things in a well-known location for my own future reference.’ Because of their publicly available online nature, personal blogs are easy to access from almost anywhere.
Blogger added a new Gadget a while back that allows me to provide a powerful Google Search-backed search of my blog’s content. This makes it easier than ever to find something I know I wrote about it when I need certain details that I’ve forgotten. Re-reading one of my posts or the example code in one of my posts often brings back many other details related to the post.
With modern e-mail systems offering large amounts of data storage space, it is easier than ever to store information in my mail storage. E-mail may be preferable to a personal blog post if it seems only individually interesting rather than generally interesting or if it contains details that are not appropriate for public consumption. E-mail tends to be easily searchable as well. E-mail is really more of a powerful communication tool than a pensieve substitute, but it can serve that function to a lesser degree.
Using e-mail as a pensieve has its drawbacks. Changing e-mail systems can be problematic if previous experience is only available in the older e-mail system. E-mail can also be more temporary in nature in some cases where aggressive e-mail purging occurs. A feature of e-mail that can be both an advantage and a disadvantage is the nature of the multi-way communication that occurs in a given e-mail thread. A particular thread can be rich with details leading to a design decision or other important details, but these same important details can also be difficult to glean from the verbosity of some e-mail threads. Splitting e-mail threads can also make it difficult to confidently reconstruct a particular decision or discussion.
Online Collaborative Tools (Google Docs)
I have been using Google Docs in a variety of work-related and personal-related areas and really enjoy the collaborative nature of these products. Having others be able to instantly see my changes and my being able to instantly see their changes is very useful. In addition, the ability to see the ‘latest and greatest’ anywhere that I have online access is liberating because I don’t need to worry about having access to the productivity software products on any computers I’m using and, even better, I don’t need to worry about ensuring that the latest version of the file is available on some medium.
These online tools have many of the advantages of the Wiki (discussed next), but tend to be useful for smaller groups of people where the ‘overhead’ of the Wiki does not seem justifiable or where the people involved are more comfortable working with productivity software such as spreadsheets, presentations, and documents than they are with Wiki text and HTML.
Wiki
Most software developers can quickly and easily pick up the basics of any given Wiki product and quickly start using it effectively. Wikis seem to be a natural fit for software developers and in many ways feel to me like an extension of the approach I used years ago of creating static web pages to store information for others’ reference and for my own personal future reference. Wikis are easier to add content to than static web pages and are far easier for multiple authors to edit. One of the major advantages of Wikis over static web pages and even over the online collaborative tools is the built-in versioning. It is often useful to see a previous version of a particular Wiki entry. Versioned Wiki pages are a sort of versioned Pensieve, allowing the developer to determine what (s)he or others was thinking or deciding at any given point in time.
Another advantage of the Wiki is the ability to easily link to other HTML material such as Javadoc, online product documentation, bug or defect reports, and related blogs and articles.
Conclusion
We have many fine tools available to us today for recording important decisions and lessons learned. I have seen these technologies improve dramatically during my career, but the degree of improvement is even larger when compared to the documentation tools described in The Mythical Man-Month. It is exciting to think about what the future holds in store for improving our ability to persist our memories in a fashion that allows us to easily recall them and feel as if we’re experiencing again a moment from our past.
Reference: The Software Developer’s Pensieve from our JCG partner Dustin Marx at the Inspired by Actual Events blog.
