Proving In-Code Documentation is Better Than Extensive External Documentation

cdocumentationmanagement

What is the best way to prove to my boss that in code documentation is greater than extensive external documents containing documentation and screenshots of code/ui?

We have a group in the company running SAP code. Their documentation process involves hours of laborious documentation and screenshots of the code and the interface (before and after).

They want us (C# developers) to follow the same rubric as they do. I want to argue that using comments in the code, and a great, self documenting language such as C# is fulfilling the need for documentation the same as, or greater than the other team's document method.

Is there any published research by big companies that say external documentation is out dated and that in code comments are more efficient? (or something similar to this point)

This has nothing to do with users. This is NOT user training documentation. Only internal use.

This has nothing to do with Design Documents or Architectural Documents. It's comparing screenshots of code, before and after a change, and screenshots of forms, before and after the change, and putting them into a document with extensive documentation, opposed to simply having great incode documentation.

Would you really want to have to screenshot your code before and after every single baby change and then write a document explaining the change in great depth? when no one will ever use these documents as reference material in the future?

Best Answer

It all depends on the purpose of documentation.

Two GENERAL cases:

  1. Documenting the inner working of a piece of code, down in the gory bits and algorithms - the things that are not important to an outside world because they are hidden under an abstraction or behind an API - is probably best done in the code. Because outside the code nobody else knows or cares.

  2. Things that go further - API's, general design principles, interface definitions, messages that get exchanged, and so on - are a different matter. These should be defined in painful detail in external documents. And only changed later - with the blessing of god.

By APIs I don't mean the stuff that appears in a C header file, or some class definition (though the lines are getting blurry). That can usually be handled fine in the source.

There will be degrees in between that require thought.

Perhaps a few examples would help:

  • The algorithm you use to calculate days between dates should be documented in the code.

  • The multi-processor message passing system you defined with failover redundancy and process porting at run-time should be documented in documents.

  • The plugin architecture for your new driverless vehicle control system (you know, the one that allows you to add a new flight module at run time without rebooting), where the plugins are developed by an outside company - well, documentation in source alone would be very problematic, use a document with words in that describes interactions, dependancies, time ordering, gotchas, exceptions, limitations, and so on. With diagrams. All in one place.

You get the idea - there are degrees to these things, and reasons for going either way. Make an intelligent and well-considered decision.

Related Topic