API Network Corp

Ann Arbor, Ypsilanti, Michigan

  • Full Screen
  • Wide Screen
  • Narrow Screen
  • Increase font size
  • Default font size
  • Decrease font size

1st Time Here?

We are a global company building open source relationships that connect you with the world ... READ MORE

The j! Asylum

There really is no Joomla asylum, but there are things you should know before you go template hunting ... READ PDF

Role Playing 101

Without the right people, your toobox is empty.  Install this process with all your Joomla projects ... READ PDF

Why You Need A CE

The Content Engineer is the star of any successful Joomla effort. Don’t start a project without one... READ PDF

Conversion Art

It’s very easy to screw up a conversion project but it can also be easily avoided if you follow these rules... READ PDF

Software Documentation - Part 3

But we have a thick folder full of documentation. So what's the problem?

The problem is that you do not need lots of pages in multiple 3 ring binders — you need good, usable, and easy to access/searchable documentation.  Documentation written in the first stages of design and development is useful for that strict stage — it brings a clear understanding of what is going to be built.   It's for the builders.   When the system is in place, the importance of these documents dramatically fades away.   It now becomes very important to know how the system is developed and why that specific course of action has been taken.      The builders are gone, the maintainers remain.

It is a painful and scary time when you must spend days in only trying to retrieve some documents strictly related to the development (and not designing) process.  In most cases, this documentation is extremely meager, scattered and hard to locate, most often because it does not exist.

As for the quality of documentation, it is important to remember that its main reason is not to have it or show it — even if these are good additional reasons when dealing with a potential customer or partner. The most important reason of writing and having documentation is using it.

You should be aware of a very disturbing reality.   There is something known as the art of writing bad documentation.  It happens most often, because of fractured processes, lack of time and lack of concern about the output.   Hey, nobody reads the stuff, so why can't I do it tomorrow, or next week?

This "bad documentation" is a must read for every manager that deals with software management.    It's obviously meant to be sarcastic, it's a bell to ring in front of every thick folder full of documentation that makes us forget about quality, instead mesmerizing us with its almighty plop factor.

Maybe you have done a marvelous job of writing documentation for your systems/websites.  More than likely, you haven't.    If you're like most, your documentation is more about what you planned to do, rather than how it was done... leaving those who must mop-up after you with an often very challenging task.   This is why so often new people arrive and and conclude it's easier to rewrite than fix.    That can be a very expensive solution.

this is really from Wordpress!

If left to the programmers, those hammering out the code, expect no worthwhile documentation to be left behind.   In fact, you'll be lucky if they put meaningful comments into their source.   The only way to ensure your intellectual property is "covered" with meaningful breadcrumbs is to have a set of processes in places that puts "what did I do today and why I did it that way" at the same level of "fix the problem, make it work, hit the deadline" -- which is something that almost never happens.

FYI: That image above:  It's real.

Seriously. This is how template.php begins. This is the hello to all those who may venture in searching for a clue.  No official Wordpress header telling who wrote it, the type of license, where to go to report bugs.

Big mess and ugly too.

When the source code of the software you're trying to fix begins with someone saying it's a big mess, and ugly... that's your cue to strap in for a long bumpy ride.

You are here: Home