Separating yourself from your software

Question

Hello folks:

My work consists of technical analysis. I like software development, but that is not my job. However, I've developed a substantial system of executables, libraries, databases, and modules. It is not unrealistic to say that such products have made everyone's job easier. I produced a fair amount of documentation for every product.

In my line of work, being a reasonably competent software developer can actually hurt (if your original job is not software development), meaning that you can quickly be relegated to software maintenance and, worse, you can be tied to a project because "only you know the software". If you consider that in NASA a project can last 15-20 years (Voyager has lasted 32), that is not necessarily a good thing. Even though you are as good as any, others move on to the awesome flagship projects or hardcore engineering (my passion).

In order to prevent this, I've developed the following rule:

If you ask a question, I respond but you document the answer in the official manual; if you ask for a feature, I will work with you implementing it in the actual code.

What I think will happen is that users will try harder before asking questions (otherwise they will have to document the answer themselves), and more people will learn the internal workings of the software as new features are added.

Enough context.

In concrete, I would like to know what official process is followed in your software development life cycle to ensure that knowledge is transmitted across the organization.

I strongly believe this is not a subjective question, but will make it community wiki to avoid confrontation.

Thank you.

Answer 1

It's a great idea to make sure documentation covers any questions that arise. These questions come up because:

• The feature is not documented yet
• The documentation is written, but not clear enough, or assumes some knowledge that the reader has not yet aquired (needs cross-references or just a bit more explanation around the subject)
• The person has not read the documentation (they didn't find it or didn't even bother looking for it)

If the user didn't find it, chances are that you're being too helpful, so they are asking you before they consult the docs. You must push back. Otherwise, there are documentation "bugs" to fix.

However, the approach of telling users that they must document things is unlikely to work. The problems you will see with this approach are:

• Most users simply won't do it unless you have enough clout to force them
• Most will do a poor job - a bare minimum to satisfy the requirement
• Even where they put some effort in to do a "good" job, the documentation may still suffer from a lack of consistency - in terms of how much information is offered, the language used, the level that the documentation is targetted at, and the assumptions that will be made about what the reader already knows.

Ultimately, you will probably have to act as an editor, or write the docs yourself.

The other part of your rule is better. Instead of just doing things for people, push back and give them enough information that they can help themselves. As you say, this helps spread the knowledge, and also empowers others to help you extend your systems. The negative side of this coin can be that others may also hack things in and you'll find your tidy/organised/stable structure beginning to get a bit more messy and flakey as time goes on.

Ultimately, approaches that may serve you better are:

• Talk to your manager and request that you get the chance to move on to the more exciting projects, with perhaps a portion of your week allocated to maintenance/custodian duties. A good manager who appreciates your skills will try to help you get job satisfaction and career progression.
• Take on an understudy - a junior programmer who is brought in to help you maintain the systems until he has enough knowledge to take over the role of maintainer. Again, this is something to take up with your manager as a way to free yourself up to move on to new challenges. Remind your manager that your skills are of more use to the company on the new projects.
• If your manager won't help you move forwards, the only ways I've found to truly be free of the entanglements of legacy software are to wait for the software to fall out of use (which could be a long time), or move to a new company (which has an instant effect, but could leave you rebuilding a similar system from scratch for a new company).