Documentation and Knowledge Transfer

[Ancalagon]

Recently, I've been studying a production and operations management course, and we have spent a lot of time looking at factories and how they operate, including staff, training, motivation etc.

And one of the things about running a factory is that every process needs to be clearly documented so that staff can easily be trained in it, everything needs to be sign posted, the floor needs to be painted the right colour to tell you where to go etc. There is a lot of information available on how to do your job just on the factory floor.

And that made me think of documentation in IT, although I refer to documentation for internal use here - not the kind you give to customers. A lot of companies love documentation and it makes them warm and fuzzy, but developers dont like it.

My take on the love of internal documentation, is that the people who push it, think that a software development company is like a factory. Tasks are repetitive and easy to learn, documentation can provide everything you need to know, and you can take somebody completely unskilled and have them producing useful output in a year or two (obviously the factory comparison depends upon exactly what the worker is doing, but you get the point). People are replaceable cogs in the machine, and documentation is how you ensure that even after changing people, the machine functions the same.

So a lot of development managers push documentation, but I don't think its nearly as effective in software development as it is in a semi skilled environment. Things that should be stored in documentation are setup requirements, prerequisites, installation instructions, development machine configurations, common problems and how to resolve them, useful scripts, that sort of thing. Documenting every web service or every database column for internal use, to me, is pointless. If you don't have a naming convention so that people dont need to guess what something is or what it does, documentation won't help.

What is your take on it?

 

[icyrus]

Document reasons, decisions and strategy and areas where you introduce complexity.

 

[cguy]

My group in my company employs a full time technical writer. It's not a perfect solution - some things are too technical for him, so someone may have to write the occasional blurb for him, but he is very good at organizing the information, getting people to write useful documentation when required, and getting it displayed (intranet wiki-like solution). He also documents all processes and tools.

 

[Sonic2k]

My group in my company employs a full time technical writer. It's not a perfect solution - some things are too technical for him, so someone may have to write the occasional blurb for him, but he is very good at organizing the information, getting people to write useful documentation when required, and getting it displayed (intranet wiki-like solution). He also documents all processes and tools.

+1
Sadly cheapskate companies I have worked for made me take on this role

 

[garyc]

The reason that manufacturing companies have extensive documentation is largely related to legislative requirements and financial reasons. The legislative requirements revolve primarily around issues like health and safety. Things like the work documentation and painting of floors shows that due diligence has been done regarding safety. There is also very high turnover in lower skilled staff and it makes sense to have procedural documentation for the rapid training of replacement staff.

In the past I did some work on software development for aircraft systems. The level of documentation across all system levels was extremely high. This was to demonstrate compliance with the appropriate regulations and the derived standards. It also helped to avoid expensive mistakes being introduced into the product. Other areas, such as software for nuclear power stations, can have similar requirements.

Most software development companies do not have these drivers. There is no legislative pressure on their products and less in the way of financial implications. This is usually dealt with through the T&C’s which absolve the company of any responsibility. Some (but not all) companies, including some very well-known ones, save money on documentation and go for very rapid releases to market instead. The only downside is for the user – often this software never seems to meet even beta test status while on sale.

 

[cerebus]

You think internal facing documentation is pointless? No I guess you're right, it's much better to have a bunch of maverick coders working out of the sheer luminosity of their momentary inspiration.

Just on the point about documenting column names - we have a situation coming where an item in the UI is being renamed, but the columns that refer to it aren't. Without documentation you could end up with some very problematic situations in the future when new devs look at the columns without knowing the history.

If you don't have a naming convention so that people dont need to guess what something is or what it does, documentation won't help.

That much is true. Better even to have a fully implemented content architecture, more so the bigger the organisation becomes. The worst possible scenario for documentation is when it gets dumped into folder on shared drives. To have any value at all, internal technical documentation needs a repository (e.g. SharePoint, but there are many), a rigorous naming standard, and overseers.

 

[Beachless]

Personally I think its very important but it depends on your development methodologies if you are following agile and the developer is involved in all of the decision making meetings the documents become less relevant to the delivery of the project but is still relevant to the administration and maintenance of the project. In waterfall however the project can be designed and documented in totality by the BA and architect and the developer just needs to deliver according to the documentation without the need to understand the bigger picture. In this case all the web services have all been defined all the business rules, calculations etc are clearly described and all the developer needs to do is create the services. The developer still has freedom to code in their particular style but they have no need other than to deliver the service that produces a particular output based on the input and rules that were defined.

 

[cerebus]

My group in my company employs a full time technical writer. It's not a perfect solution - some things are too technical for him, so someone may have to write the occasional blurb for him, but he is very good at organizing the information, getting people to write useful documentation when required, and getting it displayed (intranet wiki-like solution). He also documents all processes and tools.

I'm a technical writer, but we mainly write external-facing documentation. I think the OP is talking about documenting internal processes:

My take on the love of internal documentation, is that the people who push it, think that a software development company is like a factory.

That wouldn't fall within the remit of a normal techwriter. It's enough work to keep up with the barrage of user documents for a suite of products.

 

[Ancalagon]

You think internal facing documentation is pointless? No I guess you're right, it's much better to have a bunch of maverick coders working out of the sheer luminosity of their momentary inspiration.

That's not what I said.

And in your example, the reverse is true - documentation gets out of date, and the more of it there is, the faster it gets out of date. The code is the only truth. In fact, why have the two names different? Isn't that just asking for confusion?

 

[cerebus]

That's not what I said.

I don't think you're very clear about what you're trying to say. Is it all documentation or just excessive documentation that you object to?

Things that should be stored in documentation are setup requirements, prerequisites, installation instructions, development machine configurations, common problems and how to resolve them, useful scripts, that sort of thing.
Documenting every web service or every database column for internal use, to me, is pointless. If you don't have a naming convention so that people dont need to guess what something is or what it does, documentation won't help.

So documentation with naming conventions is good, but there's a point where it becomes redundant to duplicate work in documents? That's certainly true, but it really depends on the organisation's needs. There's no single solution to that problem.

And in your example, the reverse is true - documentation gets out of date, and the more of it there is, the faster it gets out of date. The code is the only truth. In fact, why have the two names different? Isn't that just asking for confusion?

This sort of thing happens in a large organisation when they absorb smaller products and then decide to align the UI. Changing a column name is far from a simple process - there are dependencies from other applications and the semantic layer/reporting side that would need to be changed painstakingly. That's a major project.

 

[AlphaBravo]

You need to document your process flow and within this process flow there will be various work breakdown structures. If everyone folows this guideline no matter how tedious then managment can get on doing something else and stop micro managing people. so, documentation systems are there to guide everyone and set a path so that people can get on and do what they need to do without input from somebody else on minuscule issues...

 

[semaphore]

We comment all our code and run it through a compiler on every release/debug build to generate our documents.

 

[Ancalagon]

I don't think you're very clear about what you're trying to say. Is it all documentation or just excessive documentation that you object to?

Just excessive documentation.

So documentation with naming conventions is good, but there's a point where it becomes redundant to duplicate work in documents? That's certainly true, but it really depends on the organisation's needs. There's no single solution to that problem.

I think my point is more that poor managers see "thorough" documentation as a replacement for skilled staff. They think that, if they can get their devs to just document everything, that they can swap in a junior dev if need be. Good managers recognize that documentation is important, but more importantly, know what needs to be documented and how to facilitate that.

They think that, because it is possible in factories, it should be possible in development houses. While good documentation definitely aids software developer, its not the magic bullet that it is for less skilled work.

 

[cerebus]

We comment all our code and run it through a compiler on every release/debug build to generate our documents.

That isn't documentation. That's a list of bullet points and it sounds like a recipe for disaster. But I suppose if the goal is just to keep track of code changes, it's functional.

 

[cguy]

I'm a technical writer, but we mainly write external-facing documentation. I think the OP is talking about documenting internal processes:

That wouldn't fall within the remit of a normal techwriter. It's enough work to keep up with the barrage of user documents for a suite of products.

For us, it's all internal. We have no external users. The primary goals are to help new hires ramp up faster, to prevent knowledge from being lost, and to provide process guidelines, so things get done the right way, with the right approval.

 

[noxibox]

People are replaceable cogs in the machine, and documentation is how you ensure that even after changing people, the machine functions the same.

People do leave and not having the system details clearly documented means someone else has to trawl through source code to find out how the internals work. It's the equivalent of expecting someone to sit with an oscilloscope to figure out how a piece of electronic equipment works because no-one bothered to document the details.

We comment all our code and run it through a compiler on every release/debug build to generate our documents.

That's a good place to keep the relevant documentation. It still requires coders who are not lazy about proper commenting in the first place and then keeping them up to date as the code changes. In my experience the more they think they're brilliant coders the less inclined they are to comment their code extensively.

 

[semaphore]

That isn't documentation. That's a list of bullet points and it sounds like a recipe for disaster. But I suppose if the goal is just to keep track of code changes, it's functional.

Actually that IS documentation. Its documented code and its not "bullet listed" as you say, its actually full blown paragraphs for each function, if the function is not entirely clear. Please don't assume, as you do not know how its documented. Included within the comments are examples on how the methods work and the expected out comes. Our API's are not designed for the layman, you need to have some brains to use them. If we release a framework to an outside party we write full blown integration specifications for them.

 

[semaphore]

That's a good place to keep the relevant documentation. It still requires coders who are not lazy about proper commenting in the first place and then keeping them up to date as the code changes. In my experience the more they think they're brilliant coders the less inclined they are to comment their code extensively.

I don't comment every time little method unless its kinda obtuse. i.e. PerformEuclideanRotation

 

[cerebus]

Actually that IS documentation. Its documented code and its not "bullet listed" as you say, its actually full blown paragraphs for each function, if the function is not entirely clear. Please don't assume, as you do not know how its documented. Included within the comments are examples on how the methods work and the expected out comes. Our API's are not designed for the layman, you need to have some brains to use them. If we release a framework to an outside party we write full blown integration specifications for them.

Yeah it is documentation you're right. But how do you structure and maintain it? Is it just not that important in your context or do you have a methodology to preserve it? It sounds like there could be some serious pitfalls with that approach.

 

[semaphore]

Yeah it is documentation you're right. But how do you structure and maintain it? Is it just not that important in your context or do you have a methodology to preserve it? It sounds like there could be some serious pitfalls with that approach.

There are no pitfalls to this approach, we have been doing it for 2 years. The documentation is contained within the code and parsed as such. People are required to comment there code as its part of our policies and guidelines and as i stated this is for internal use not external.