Simple Solutions

One of the hardest things to do is to discover the simplest solution to a problem.  To often software developers come up with the most complex solution instead of the simplest one.

The simplest solution is the solution with the least amount of functionality to solve the problem.   This makes the solution simple to design, simple to code, and simple to test too.   Another advantage of simple solutions it is easy to document and communicate.

Software Librarians

There is a job title in the software domain called software librarian. I searched for the job title of software librarian on Monster.Com.   It does not seem that software librarian jobs require any background in library science.   Instead the job description indicated they wanted someone who could code.  When I searched for medical librarian or law librarian the following appeared in every job description.

You must possess the following requirements and experience to succeed in this position: Master’s Degree in Library Science from an ALA accredited program.

What is the motivation for the fields of medicine and law to require a Masters in Library Science to organize their documents while there is no requirement whatsoever for the software industry?   These other industries have realized how critical it is to organize knowledge, so it can be retrieved and reused.

I suggested to a client they hire a librarian or two to help them organize their software application.    He looked at me and asked me one of those obvious questions, “where do we find a librarian.” I suggested he look for a librarian at the library which they did.  They hired two librarians to consult and help establish a numbering system similar to the Dewey Decimal System for their software applications.  Like the DDC their internal numbering system was a faceted system.  This allowed a lot of cross-referencing of documents. In the end they had an online system where they could search for documents by a specific part of the application.

A librarian, with a Masters degree in Library Science, makes between $36,980 and $56,960 per year.[i] The average salary of a software developer is around $69,240.  You can get a librarian for less than a programmer and they are going to be twice as productive (maybe more) as a software developer when it comes to organizing.

Read more at Reboot! Rethinking and Restarting Software Development – Interesting ideas on design and organization of website and information. – interesting ideas on how information is shifting.  It is coming to us in a variety different ways now.

[i] Bureau of Labor Statistics

Benefits to documentation (yes there are some)

When application documentation is given meaningful names and numbers, it can be found easily. Software organizations need to establish a standard naming convention for documents and the application.  Documents need to be named using some agreed upon standard and a numbering system. 

By definition a complex software application is difficult to understand and needs to be documented well.  Yet, I have heard comments like, “our software is too complex to document.”   If your software application is too complex to document, then the software application is too complex to understand and your software needs to be simplified.  If your software application is too complex to document, then how will the complexity be communicated?

 No one wants to be a software archeologist.  One problem with unorganized information is it can’t be found, so there is a lot wasted time spent pecking around looking for the right document or trying to find the right person to talk to.   Another problem is if your documentation can’t be found, then redundant functionality is often created.  Of course creating redundant functionality is a waste of time.    The real benefit to the organization of documentation is reducing wasted time and spending more productive time on projects.  This, of course, improves profitability. 

 Another benefit to organized documents is the ability to reuse parts of the application documentation.   Reuse has been a hot topic in software development for sometime and it should not be limited to just the code.   Everything related to past projects can be re-used including requirements, test plans, test data, even project plans can be reused.  Reuse is a good idea and it does improve both productivity and quality.   Artifacts that can’t be found can’t be reused.  Those companies that have mastered reuse see a natural increase in their productivity and profitability.

 Read More at Reboot! Rethinking and Restarting Software Development

Is documentation still relevant?

There was a great question posted on linkedin by Danielle Vokski.  Her question was, “Do you think that documented working procedures are still relevant in the changing climate of todays market?”

In todays changing and evolving market place there has to be a way to communicate and share ideas.   Documented work procedures do not have to be a written document.  It can be a video, podcast or an animation.

Keep in mind complexity does not necessarily equate to more documentation and a thicker user manual.  Consider the difference between an automatic transmission on a car versus a manual transmission. Clearly the automatic transmission is more complex, but requires much less documentation and user training than a manual transmission.

Another problem is if the environment changes then the procedures needs to change too.  The procedures become dated and useless if they are not changed.  Yet, the change needs to communicated to all those that are impacted by the change.

If the process is intuitive and/or the product is designed well, then it does not require much user documentation.   Don’t be confused because I am not advocating something like the code is the documentation.  What I am suggesting is the process has been studied so much and designed so well that it is intuitive.  If the process or product changes then it is intuitive how to adapt.

The documentation and skill required to repair an automatic transmission is much more than that of a manual transmission.  In the end whose perspective matters.

So let me answer Danielle’s original question with two answers.

1.  User documentation needs to become irrelevant. If the product is designed well and it is intuitive.

2.  Documentation is still relevant for the technical documentation.  The more complexity that is hidden away from the user the greater the skill to understand all the inter-workings. more at Reboot! Rethinking and Restarting Software Development

Links for writing better documentation

Tips for effective documentation –


Just Google it! Huh?

There is a misconception it is okay to have documentation scattered about individual computers and a “shared drive.”  The myth is documentation can be found via searches and it does not need to be organized.  Some organizations want to implement a Google style search mechanism.  The beauty of the Google search engine is it seems so simple.  Google relies on creators of websites linking information together and some relatively complex algorithms.  The founders of Google wrote a paper entitled, The Anatomy of a Large Scale Hypertextual Web Search Engine outlining how the Google search engine would work.   It is not as simple as it looks.  Most organizations with disorganized documentation cannot get their developers to use consistent terminology nor can they get them to embed hyperlinks in a document.

If a specific document is referenced by many other documents, then the document is significant.  If the document is not be referenced via some linking mechanism, then there is no way to determine its significance. The problem, of course, is getting individuals to link documents together.   Believe it or not I have had developers argue this point.   Even though they have never read the short paper or long paper written by Brin and Page the founders of Google they just somehow know all the inter-workings of Google.  They think it would be easier to design a complex search engine with artificial intelligence not yet invented by mankind instead of standardizing terminology and using some sort of naming convention for their documents.

Read more at Reboot! Rethinking and Restarting Software Development.

Organization makes a system of many appear fewer

Mark Twain once said, “A person that does not read books is no better off than a person who does not know how to read.”  An organization that creates chaotic documentation is no better off than an organization that does not create any documentation.  The argument could be easily made the organization is actually better off by not wasting time creating chaotic useless documentation.

On any single software project or application, there can be 100’s perhaps 1,000’s of artifacts.  The artifacts can be requirements specifications, design documents, flow charts, code, test plans, test cases, so on and so forth.  Most of these documents will reside on personal computers or stored on some shared drive.   I have worked with organizations where all “important” documents are stored on a shared drive.  The share drive was created with no standards and no subdirectories.  In other words, there is just a big pile of documents.  Within those documents there are no naming conventions, no standard glossary and no standard format. It can be nearly impossible to find information, so developers just ignore any previous written documentation and start from scratch.

I ask software development organizations to compare how they catalog and organize their documentation to how a library organizes knowledge.  I ask, “What would the local library look like if they followed a similar process for organizing documentation?”  Some people tell me the library would be empty, others tell me books would just be staked up all over the place, still others tell me some of the books would be half written and some of the books would be tucked away in librarians desks.  For too many software development organizations their documentation is not organized at all and it is chaotic at best.

The idea of classifying information and knowledge is not a new idea and has existed for several millenniums.  Classifying was one of those skills in which Aristotle excelled.  Aristotle understood information is easiest understood when it is classified and organized.    The idea of organizing and classifying is nothing new and it should not be a novel idea to software development. The bottom line humans like things organized, we have been organizing information for millenniums, and it is time software development get on board.

Get Fluent in IT Speak

To get the right word in the right place is a rare achievement

– Mark Twain (American humorist, 1835 – 1910)

Years ago, I was speaking at a conference in the Ukraine and a live interpreter was translating my speech.   The members of the audience were wearing headphones, so they could hear the translation.  At the break, the interpreter came up to me with a list of words and asked me to explain the meanings.  She asked me to explain what was meant by the word, “y’all.”   I am from Texas and everyone in Texas (and the southern part of the USA) knows what “y’all” means. I explained it was slang for all of you and the plural form of “y’all” is “all y’all.”    The interpreter had a list of other words that I did not even know I used.  I was totally unaware that I used words like “fixin” or “gotta.”[i] Since I do a fair amount of public speaking in places other than the Southern USA, I have tried to eliminate slang and jargon from my vocabulary.   This has helped me become a better communicator.

Confusing Communication

One of the barriers to improving productivity and quality is poor communication.  Over the years I have carefully observed how software developers interact with each other and especially how they interact with the core business, user community and customers.   Software developers are not good at communicating with the core business or with their customers.

It is common in the software domain to have inconsistent terminology and symbol usage whether it is written documentation or actual code. Using inconsistent terminology, symbols and languages causes confusion among readers and it negatively impacts communication, productivity and quality.  Standardization of terminology goes along way to improve both productivity and quality.  Unfortunately software developers often proclaim standardization negatively impacts their creativity and it burdens projects, but nothing could be further from the truth.

Software developers, like any technician, have to communicate with each other and ultimately they have to communicate with the core business.   The choice of vocabulary and the method of communication is not the same between technical teams and with the core business.  The type of communication used to communicate with the core business should not be the same as the technical communication used by software developers.  The core business does not have the skill set to understand the technical jargon.

You should try and eliminate any jargon or technical words from your vocabulary.

[i] Fixin to go is used instead of, “I am getting ready to leave” and “I gotta go” is used instead of “I have to leave.”

Published in: on June 12, 2009 at 06:00  Leave a Comment  

The code is not the documentation!

There are a lot of reason why the code can’t be the documentation.  The first reason is obvious because most organizations and individuals have no standards in place.  As an example let’s compare sheet music with coding – shall we.

Keep in mind sheet music was not always been what it is today.  There have been several evolutions of what is known as sheet music.   A Benedictine Monk named Guido of Arezzo was the first to attempt the standardization of music notation in his book Micrologus published in 1026. The idea of sheet music has evolved over several centuries and as software evolves standardization of terms, vocabulary and symbols will be commonplace.  I hope it does not take the software industry a 1,000 plus years to standardize terminology.

There is no accepted standard for notation for software development.   By notation I mean how do we communicate about software.   Notation differs from organization to organization and even differs within an organization.    The lack of consistent standardized vocabulary, verb usage, and symbols is really unique to software development.

Any first year music student, unlike software developers, learns the symbols of music and basic music notation.  Music notation is a system of writing music so that specific pitches and rhythms can be communicated.  Music notation indicates exact pitches by the upward or downward placement of symbols called notes on a staff.  A note is an oval.  Its duration is indicated by whether it is black or white and if it has a stem and flag.  As music students progress the symbols become more complex.  While most music novices can play and understand a level one music book, it is impossible for a novice to play or even understand an advanced music composition.

Sheet music, unlike code or software documentation, is written concise and consistently. Structure in music allows the composer to communicate to musicians how the piece should be played.  It is a printed page, like a book or poem, that tells a story.  A talented, creative and imaginative person created the story.  Without consistently written sheet music it would be impossible for musicians to play the story with their instrument.   Just like structure does not inhibit the creativity of a composer, structure does not inhibit the creativity of a software developer.

Sheet music transcends language and time. Music notation gave western music a means of a written historical record.   I was working in Vienna, Austria and picked up some sheet music written by Wolfgang Amadeus Mozart  for my daughter who plays the piano.    Mozart’s lived 250 years ago and his language was German.  My daughter who is 15 years old does not speak German, but can pick up this sheet music and play it on her piano.  While the content is different the symbols are exactly the same for a contemporary piece like Linus and Lucy, the recognized Charlie Brown theme song written by Vince Guaraldi.   The same could apply to two different software functional specifications, they should be written in a consistent manner.  I do not expect a software documentation to transcend 300 years, but it should transcend the entire life of the software application.

There is nothing on sheet music, which is not necessary.  Even though sheet music varies depending on the instrument being played the symbols all have consistent meaning.  A typical piece of music contains all types of measurements, symbols and directions.  A whole note is always a whole note and a quarter note is always a quarter note. Without all of this structure and rules it would be difficult for a musician to perform a piece of music.  It would be impossible for an orchestra to come together and play as a symphony.   When documentation is written inconsistently it is hard to communicate what is desired because inconsistently written documentation inhibits communication and causes confusion. The same is true for software.   When individuals write documentation inconsistently, it is difficult for everyone to understand what was meant. Naturally this hurts productivity and quality.

While it is common for a person writing documentation for a software project to decide on how to write the documents, a composer of music does not decide to develop his own vocabulary or develop their own symbols.  The idea of music composition is an advanced mature industry.  Individuals that write music are trained to write music and they are trained to read music. There are special courses required for those musicians who write and transcribe music.  It is possible for a person to get a Masters Degree in Music Theory (M.M. Theory) or Masters in Music Composition (M.M. Composition) .  It is possible at some universities for an individual to earn a PhD. in Music Composition.  Think about it, music is so advanced in its notation individuals can obtain Master (and sometimes PhD.’s) in the composition of music.   Granted a person can earn a Masters in Software Engineering, but this is analogous to earning a Masters in Music.  A Masters of Software Engineering is a generalist degree.  The required course work to earn a Masters of Software Engineering varies from university to university.   Even the term software engineer is vague.  Typically a software engineer encompasses everything from a programmer, software architect, software designer,  and manager.

In Mozart’s day music was hand copied by an apprentice because there was no such thing as a copy machine. This was one of the problems with printing and reproducing sheet music because sheet music requires special symbols which are not part of everyday language.   Printers who printed sheet music had to have the capability for music engraving.   These printers had special characters not typically used in everyday life.  Today, scorewritter software contains all the necessary symbols for a composer to write music.   If a software organization decides to use symbols to communicate then it is important to be able to type those symbols.

Since there are no standards for coding like sheet music, the code cannot be the documentation.
Published in: on June 12, 2009 at 01:01  Comments (1)  

Brunelleschi’s Dome

In the late 1200’s it was decided that Florence needed a cathedral that would rival the cathedrals of London and Milan.  The original planners had envisioned a cathedral with a dome that would be the largest dome ever constructed.  They decided to move forward with the construction even though the designers were not certain how the actual dome would be constructed.

Brunelleschi's Dome

Brunelleschi's Dome

For nearly a century it was obvious that no one in Florence or anywhere for that matter had any clear idea how to construct the dome.   All attempts to build the dome had failed and the cathedral was domeless.  While the intent of the dome was going to represent civic pride it instead was a constant reminder of failure and embarrassment.   The story does not end here.

The original planners had been overly ambitious.  All contemporary building knowledge had been exhausted.  The man that would eventually design and oversee the construction of the dome was named Filippo Brunelleschi.    Brunelleschi believed the secret of the dome was not in contemporary knowledge but held in the past.  He would resurrect forgotten concepts by studying the ancient architecture of Rome especially the Pantheon.  He spent over a year studying the Pantheon and it eventually gave up its architectural secrets and he had his solution.   He designed and constructed the largest unsupported dome in Christendom. The dome is an architectural achievement that architects still marvel at today.

Sponsors of software projects can be overly ambitious too.  One of the problems with iterative development such as Agile is it is based upon design as you go. One of the problems with designing as you go is the probability of creating undesirable constraints. Brunelleschi knew he could not tear down what had already been built.   He could not start from scratch.   The outer walls of the cathedral had already been constructed and this dictated the size and shape of the dome.  The same thing happens in software development where previously written code and design constrain all future solutions.

The requirements of the project need to be outlined and the technical solution needs to be understood.  The degree of understanding needs to be in proportion to the importance of the problem.  It was not a good idea to start construction of the cathedral without a clear understanding of how the dome would be constructed.   Lucky for inhabitants of Florence and everyone who has visited the city that Brunelleschi appeared on the scene.

Brunelleschi documented his project in secret code he only understood to maintain controlPlans over the project. He even refused to explain the details of his plan to the project sponsors. They had no choice but to tolerate Brunelleschi’s difficult and uncompromising behavior.   He documented the project without any intention of communicating, so clearly the reason he documented the project was because it was too complicated for him to do all the analysis in his head.

Brunelleschi’s Dome: How a Renaissance Genius Reinvented Architecture (Paperback)

Welcome to Club Chaos!

The secret of all victory lies in the organization of the non-obvious.
– Marcus Aurelius (Roman Emperor AD 121-180)

Things Just Seem Complex

Software applications and documentation seem more complex when they are not organized. It does not matter if it is software applications, books, collections, or lives anything that is not organized seems more complex than it really is.   As John Maeda writes in The Laws of Simplicity, “Organization makes a system of many appear fewer.”   If applications and associated artifacts are not organized, then there is only a sense the application is complex.  By organizing application artifacts complexity of applications is reduced.

I have been to a lot of grocery stores around the world, including Rome, and it seems like they are all organized in a similar manner.  In any grocery store there is the fruits & vegetable section, meat & cheese, bread, canned goods, frozen foods, snack foods, liquor, so on and so forth.

Organized documentation and functionality is important for everyone especially the novice.  A grocery store is a complex system. Since the grocery store is organized, it is easy for the novice clerk to re-shelf the contents of the grocery store and the novice customer to find what they are looking for.   A novice is a person who is trying to understand something for the first time.  Think about all the different manufacturers of products or the number of countries where products originated to stock the grocery store shelves.   The goods only represent one layer of complexity.  Another layer is the scheduling of employees to clean the store, to shelve, and to run the cash register.  The beauty is all the complexity has been hidden from the customer.   The grocery store is an organized complex operation; yet, our interactions seem simple.

When software applications evolve without a comprehensive design, functions get scattered around and it becomes hard to navigate all the confusion.  Since there is no clear functional decomposition of the application, the user of the application and developer have a hard time finding a specific piece of functionality.   The application is difficult to navigate and users become frustrated.

Developers have a hard time finding functionality or understanding the functionality that already exists.   This causes redundant functionality to be created.  This extra functionality is not needed and it becomes additional expense to create and to maintain.

The perceived complexity is worse when multiple applications share information and communicate via undocumented interfaces.  If documentation is not organized which describes all the complex interrelationships it is going to be next to impossible to grasp what is actually happening.