What is the best way to prove that in-code documentation is greater than extensive external documentation?

Question

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?

Answer 1

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.

Answer 2

They're not intended to do the same thing. Sure there could be some overlap, but in general in-code documentation is going to be at a lower level describing what this one section of code does, whereas external documentation is going to be better at describing the application at a higher level, or even as a whole, beyond the scope of just one code file.

I'd say it's not a question of one or the other. Both should be used.

Answer 3

You may think code is "self documenting" but I can assure you you're wrong. The only reason you think it is, is because you have the knowledge on how your code works hiding inside your head - its like having an invisible, unwritten set of documentation memorised. Work on someone else's code and you'll begin to see this (usually this manifests itself as the "my colleagues code is crap" syndrome, really its just because you're missing any documentation on how it works).

"external" documentation is every bit as important as the code, you must be able to communicate what the code does, how it does it (in broad design terms) and why it does it. These things cannot be embedded within the fine-grained codebase. Sure, you can do internal code docs too, and they can be auto-generated, but I always found them to be a little pointless compared to just reading the code (and the embedded comments).

Where you're right is that documentation doesn't have to be a laborious task, written in huge Word documents. You can make the task much easier by writing it in a lightweight markup language (eg ASCIIDoc or ReStructured Text) which can then be compiled into Word or HTML formats. This documentation 'source' can then be edited within your IDE as they're only text files, and you can apply code review tools and your SCM to it too. This approach makes the necessary documenting task significantly easier for developer teams.

Answer 4

I think you need to be some where in the middle. Different audiences require different levels and styles of documentation.

Your SAP peers may be overdoing for developer's consumption, but I would imagine their documentation transitions nicely into Help Pages or a Users Guide. Code comments don't help sell the application to management in the early stages. Requirements and high-level design documents don't fit well in the code either but are certainly critical to everyone's understanding of correct/expected behavior.

Answer 5

You can generate help files from XML Comments in source code. SandCastle can take those comments and create nice help files, which you can complement with conceptual documentation.

EDIT: The tools allows you to:

1. Brings your comments on the code to an external documentation
2. Your docs' source is versioned, without extra effort (since your source code already is, right?)
3. If you need to explain concepts to newer developers, the docs project manager app have an (semi-decent) editor to what is called "conceptual documents" in a XML-based language. I've used myself, the editor is good enough to it not being a problem.
4. I don't remember details from memory, but I believe you can link all that (code-based and conceptual) content to each other, allowing you to get something in the lines of VS help.

All this allows you to get all content from what already exist in your sources, and complement it with conceptual explanations (the "how this all fits on the puzzle?" stuff). And having the hability to export it to HTML, CHM Help and other formats. I believe it would placate your management need for external documentation from the internals.

EDIT 2: Answering to the OP's second editing, what he's looking for is some kind of changelog to answer why(and when) some changes happened.

You could implement it on code or an external "conceptual content" artifact that you change (or generate) from your source control system hooks. That way, each time you generate the documentation, it get's the "What's new in this release" document in a easily presentable format.

It can even be an different documentation project file from your documention main project (which means it can be generated separately and with different presentation settings).

BTW, seems your boss is looking for some model to follow. SAP process appear to be way too much, but you can show him what he's trying to achieve (which is traceability of the changes: the "who, when and what" question) in a automated (and presentable) way.

PS.: An bug tracking system would help here too, as you can include the change request (or bug file #) that motivated the change too.

Answer 6

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?

It could be, but it is not a rule. What will the documentation be used for? (Who accesses it? How often? What feedback/decisions come out of that activity?)

Their documentation process involves hours of laborious documentation and screenshots of the code and the interface (before and after).

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?

Seems like they're doing it wrong'* - they don't need your documentation - they need a note somewhere, saying:

git/hg/svn/xyz diff -rXXXX -rYYYY # show code differences
git/hg/svn/xyz info XXXX          # show change description and details

or something similar. This can easily be automated by any good SCM, or with whatever your deliverables are called ("feature releases", "change requests", "iteration ending reports", "public commits", "solved defects", etc).

when no one will ever use these documents as reference material in the future?

If indeed no one will ever use them, then it's easy to prove: no one will ever use them. Can you speak to them to find out if this is indeed the case?

---

'* - I am not sure if they're actually doing it wrong. It depends on what this documentation is used for.