Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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)

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

Edit Edit - This has nothing to do with Design Documents or Architectural Documents. Its 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?

share|improve this question
2  
Are there dedicated QA resources assigned to the project? –  hardmath Apr 22 '13 at 17:41
1  
@hardmath Yes there is. Our users enter QA period periodically. But the QA documentation and test scripts are written by the dev team, and is not included under the umbrella of this question. –  jordan.peoples Apr 22 '13 at 17:59
2  
would it be possible to generate the requested documents via some sort of automated process? Yeah, its a workaround but it might be a useful option to consider. –  Winston Ewert Apr 22 '13 at 18:21
    
For one, internal code documentation can export to external code documentation (javadoc, and C# /// comments, for example). You can't go the other way. –  Ryan Hayes Apr 23 '13 at 14:21
1  
I can't imagine why anybody would want screenshots of code, or in-code comments describing the UI. Neither seem particularly useful. –  Eric King Apr 23 '13 at 18:08
show 8 more comments

6 Answers 6

up vote 2 down vote accepted

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.

share|improve this answer
add comment

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.

share|improve this answer
2  
I generally agree, but Donald E. Knuth might not. :-) –  Peter K. Apr 22 '13 at 20:32
    
@PeterK. I just read through the introduction to that article, but It doesn't seem to contradict the sentiment of this answer. Care to point me to a specific part of it, or to summarize the article? –  Servy Apr 22 '13 at 20:38
    
Donald Knuth is famous for many things, many of which call into the category of "stirring" or being deliberately contentious - perhaps in order to get people to think. –  quickly_now Apr 23 '13 at 7:11
add comment

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.

share|improve this answer
6  
I think you're assuming way too much there. I've totally had situations where I looked at code and I understood what is going on without having to read any comments or documentation. Sure it might be more rare than one would like, but it does happen! –  MrFox Apr 22 '13 at 18:32
    
and I've looked at 5 million loc programs and thought.. "where's the architectural diagram?" –  gbjbaanb Apr 23 '13 at 10:31
    
i think you missed the point somewhat. When would you ever have thought "man i really want to see a screen shot of the before and after code from this function" –  jordan.peoples Apr 23 '13 at 17:53
    
screenshots aren't exactly dev documentation, but essential for user docs. Maybe they form part of internal training, and for that - the dev counts as a user. though I have worked with some complex packages where a screenshot would have helped tell me what it was supposed to do. –  gbjbaanb Apr 23 '13 at 18:47
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
1  
@GlenH7, I think people missed the point: his boss' is trying to trace the code changes. What SAP process showed him is a way to achieve that traceability –  Fabricio Araujo Apr 24 '13 at 16:51
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.