Skip to main content
gamedev.net
🔒 Locked

Documentation ... !?

Unity
Started by Decrius Sep 5, 2010 at 3:31 PM 12 replies 2.7k views
Original Post
Decrius
Decrius
Yes, that part of a project you ought to do, but either avoid or delay till infinity. Well maybe not so extreme, but it sure ain't your favourite pastime.

Since I started with the D language (which I really find a great language), I once again noticed how documentation is either lacking, hardly accessible, badly written or computer generated. At least one of these options is true for most (hobby) projects, and also for D libraries (as they're pretty new). But also for my own large project I've been struggling and delaying to get the documentation coming.

I would like some input and advices / examples on what you find good strategies to document code. Good ways to make it accessible, readable and usable. There are several examples I have an opinion about though, it would be great to hear from other people what their experiences are with the different techniques, what worked well, what worked not...

Here is a list of methods I encountered and have a biased opinion about:


1. Automatically generated documentation. Often done with certain (like Java) style comments in the code. Then by running an application such as Doxygen over your code, it barks out a complete website with all classes, functions, constants, etc. covered. Each with some notes from the documentation in the code.

From my personal experience I find this technique deficient. It requires programmers to consistently add comments in the form of documentation to their code. This makes the code unreadable. Code is code, it can contain comments, but not documentation.
When using computer generated documentation as a user, it's often tough navigating. And the notes are poor and insufficient.


2. Unix manpages. Separately written, often very basic HTML with mono-spaced fonts. It has a list of links to all functions (it's often only for C libraries). Each function has one page with headers such as: Name, Synopsis, Description, Examples, See also, ...

I find this very clear. It exactly states what the function does, how it is called, how it is used and what related functions are. It often gives an adequate understanding about the usage. However, more often then not, it is written by the programmers themselves. This can result in documentation for the team (people who are familiar with the library) and not for foreigners (people who want to get familiar with the library). Besides, I haven't thought of a way to document more object oriented languages; documenting modularized functions (in namespaces / classes).


3. Wiki's. Often written by the community or a few advanced users / team members. Has pages with many interconnections with other pages, often written as tutorials or articles.

Most often very inconsistent in style and manners. Lots of information is added by different individuals, sometimes uncategorised (just dumped in one file) or too few / too much information. Many navigation possibilities to other pages, sometimes losing track or finding duplicated information. When done right, can be a very good medium to set up articles / tutorials, for references guides not so sure.


4. Custom made; good, bad or ugly.



Personally, I find unix manpages very clear and complete, but sometimes asserting that users are already familiar. Also, I'm not too sure how to document object oriented / modularised code with unix manpages. Wiki's can be very nice for articles or tutorials when set up right. I'm not a fan of community driven wiki's, as it takes time to maintain and the result is more often then not a collection of inconsistent pages.

What are your thoughts? Which method do you use (or which have I forgotten)? Which method do you find effective, and which embarrassing?

Any input is welcome, thank you!

PS.: sorry for the long post
[size="2"]SignatureShuffle: [size="2"]Random signature images on fora
Antheus
Antheus
Quote:
I would like some input and advices / examples on what you find good strategies to document code.

Who is your audience?

Quote:
Automatically generated documentation.
Technical detail. Has no impact on usefulness of documentation. It tends to harm it, since the auto-generation means people will make a mental note that writing documentation isn't needed anymore.

Quote:
2. Unix manpages.
My personal experience: dozens of pages of in-depth explanation of how the programmer's state of mind after eating a raising caused him to add each individual features before finally and painstakingly including the one and only thing that I will ever in my life care about: a one line example.

Quote:
3. Wiki's.
Requires a community and good moderation. There is nothing worse than non-professional wiki. Very few are actually useful.

Quote:
Personally, I find unix manpages very clear and complete
Which is great if coding for unix programmers. For the other 98% of programmers, it's a horrible mess of lol-ascii-get-with-the-times-grampa.

Quote:
What are your thoughts?
Documentation costs extra, 30% more per hour. It increases total project completion time between 3 and 10 times. Templates and standard compliance provided by client. Ability to deliver this extra effort needed is the difference between $5/hour PHP coder and $2 million project. It may sound silly, but the ability to produce any kind of meaningful documentation is *hard*, much harder than coding even the most complex project (at least for programmers). So anyone who needs it will pay for it, just like they pay for support on FOSS. If they don't need it - why make it.

For web stuff and services - provide SOAP or REST service, show sample JSON or XML with all possible parameters on one page, be done with it.
KulSeran
KulSeran
Quote:
1. Automatically generated documentation.

I completely LOATH this. Just don't. These are only useful if you already know what you are looking for. The problem is that most programmers aren't going to care about every class and function and how they interact. Only a small portion of your program should be external interfaces the end programmer needs to use. And someone should be in charge of designing that to the point that their can be specific documentation on what you need to do to get something running using that code.

I also agree that it clutters up the code. It makes perfect sense to put some kinda documentation at the top of each class, or top of each definition or at the declaration of a particularly complicated interface function. But, generally, thanks to IDEs it is simple to just jump around code. Therefore, to the best degree possible, the code should be easy to parse and well organized. Cluttering it with too much useless documentation breaks that. I think the big issue here is the "obvious documenter documents obviousness" syndrome, where you end up with 10 line comments on each function:
//-----// function mul_add// *base - integer input// *mul  - another integer input// *off  - another integer input// *returns - an int// *comments? - does something with the inputs,//              and returns the value////-----inline int mul_add( int base, int mul, int off ){   return (base*mul+off);}

That does NOT help my readability of this code file. Nor does it help my understanding! (made up that example, but I've seen similar stuff all over the place)

Quote:
2. Unix manpages.

I agree. These are excellent ways to document code, but again, they suffer from you needing to know what man page you are looking for before they become useful. Still, I'd take these over doxygen documents any day.

Quote:
3. Wiki's.
These tend to have all the information and tutorials you could ever want, but they lack direction and usually lack expert advice. Many of them really need a good "getting started" page on their wiki. And, beyond that they need the expert solutions for stuff. So many tutorials/wikis/web sites stop at the beginner stuff and expect you to figure out the rest on your own.

Quote:

Custom made; good, bad or ugly.

Always include a readme/getting started/how to install. Sample code is good too (Bullet documentation may not be the best, but it comes with tonnes of hands on physics examples).

[Edited by - KulSeran on September 5, 2010 4:21:40 PM]
Decrius
Decrius
Quote:
Original post by Antheus
Who is your audience?


I'd be building some projects (alone) in C/C++/D. The audience would be myself and all future users.

Quote:
Original post by Antheus
Which is great if coding for unix programmers. For the other 98% of programmers, it's a horrible mess of lol-ascii-get-with-the-times-grampa.


Yes it is a bit of an old habit. But my experiences with OpenGL's manpages are quite good. It tends to give me a good reference guide for particular functions. Though I admit that something like http://www.cplusplus.com/reference/ is much better accessible, but it pretty much follows the old unix manpage way of documenting functions. Btw, this is actually a good example of documentation for modularised code.

Quote:
Original post by Antheus
Documentation costs extra, 30% more per hour. It increases total project completion time between 3 and 10 times. Templates and standard compliance provided by client. Ability to deliver this extra effort needed is the difference between $5/hour PHP coder and $2 million project. It may sound silly, but the ability to produce any kind of meaningful documentation is *hard*, much harder than coding even the most complex project (at least for programmers). So anyone who needs it will pay for it, just like they pay for support on FOSS. If they don't need it - why make it.


Yes it costs a lot. But without documentation, code is worth (almost) nothing (like you stated). If I ever want to make a healthy usable project for the community, the documentation must be spot on. Including the tutorials / articles, this will take me most of the time of the project I suppose...:|

Quote:
Original post by KulSeran
I agree. These are excellent ways to document code, but again, they suffer from you needing to know what man page you are looking for before they become useful. Still, I'd take these over doxygen documents any day.


Yes, but this is true for most reference guides. It's mostly a look-up of how-did-it-exactly-work-again. I fully agree that one should add a getting-started / beginner-guides to get them going, and put many _working_ example codes with comments to explain things. Often, in resemblance to pictures, code is worth a thousand words.

Quote:
Original post by KulSeran
These tend to have all the information and tutorials you could ever want, but they lack direction and usually lack expert advice. Many of them really need a good "getting started" page on their wiki. And, beyond that they need the expert solutions for stuff. So many tutorials/wikis/web sites stop at the beginner stuff and expect you to figure out the rest on your own.


To avoid this, I often lock-up the user permissions. This pretty much breaks the wiki philosophy and allows only me (and in future a handful of trusted members) to modify the wiki. This brings consistency and expert input.
[size="2"]SignatureShuffle: [size="2"]Random signature images on fora
theOcelot
theOcelot
Yeah, if you ignore the "user-editable" part of a wiki and just keep the basic wiki platform, with just a couple authors, it just makes a nice way of storing and organizing docs. I'm using the MediaWiki app on sourceforge.net to document my project there. It works fine, when I get my rear in gear and write the stuff.
phresnel
phresnel
Quote:
Original post by Antheus
Quote:
Personally, I find unix manpages very clear and complete
Which is great if coding for unix programmers. For the other 98% of programmers, it's a horrible mess of lol-ascii-get-with-the-times-grampa.


The fact that a good manpage follows existing conventions in their structure (synopsis, description, return value, errors, examples) makes them usually highly navigatable. Your most nearby ascii terminal is not the only way to browse them.

Example (I made it so that I just need to type "man foo" into firefox's / iceweasel's "awesome bar" to find information on foo).

Even if one is overwhelmed for a slight moment, one soon learns to just grep or incremental-search for "examples", if that is what you need. If you need detail on the return-value, the figure is similar. For many corner-cases, existing manpages provide enough information. For many normal-cases, they have enough information, too. You just need to know how to navigate text-documents, which is very similar to navigating sourcecode, imho.

Admittedly, a lot of man-pages are not well-written, but so are other docs: When I look at this then I had a harder time finding format specifiers and grasping examples.


edit: Oh, and of course, them being mostly ascii means they also load pretty fast over small bandwidths, as a little bonus.
3Xist3nZ
3Xist3nZ
I think tools like doxygen or javadoc are a very good way to document code.
The only problem i see is that most developers think that one or two descriptive lines above every method/class is sufficient. Whats missing here is the big picture to tell the reader how to use all the classes and methods.

A very good example of how to do it, is Qts documentation (i love it, http://doc.qt.nokia.com/4.7-snapshot/classes.html). It is generated by a tool (similar to doxygen) but with lots of introduction pages and examples.
Structural
Structural
Quote:
Yes, that part of a project you ought to do, but either avoid or delay till infinity. Well maybe not so extreme, but it sure ain't your favourite pastime.

Why isn't it a fun thing to do then? Surely it adds value to the final product, no?

For some time now I've been a proponent of self-documenting code. Small classes and methods, descriptive names, and learning to read code quickly and efficiently. For me, it takes away the need to document the code on class/method level. Whenver I'm told I must document all of my classes and methods with big blocks of comments it feels like such a waste of time, because the code is so clear it's obvious what is going on. Also, documenting the methods themselves is pretty useless because every method in itself does very little. The magic/important thing is how everything works together, which is hard to document in code.

However, I still believe that concepts should be documented because they are not always immediately clear when reading the code.

Also, an exception may be when you are only exposing an interface without the code, and the interface has parameters or behaviour that is not immediately clear.
But still I believe that when you redesign the interface while keeping ease of use you can greatly reduce the need for documentation. For example, I always put some extra effort to take execution order dependencies out of an interface. Things like "you have to call initialize and set these parameters before calling Foo()" make me cringe. They are a programming errors waiting to happen.

Quote:
Original post by 3Xist3nZ
I think tools like doxygen or javadoc are a very good way to document code.
The only problem i see is that most developers think that one or two descriptive lines above every method/class is sufficient.
Whats missing here is the big picture to tell the reader how to use all the classes and methods.

Then I don't understand why you recommend doxygen and javadoc. Last time I used them, either they were intended to document code on file/class/method level. Whereas this big picture you talk about stands far above that level and is better documented using diagrams, pictures, flowcharts... something graphical.

STOP THE PLANET!! I WANT TO GET OFF!!
jwezorek
jwezorek
Look, I think people in this thread are talking about a lot of different things. Are we talking about documenting an API to a software library? or are we talking about internal documentation in/of the source code of a large application? These are two different things.
Ravyne
Ravyne
I find Doxygen and doxygen-style tools incredibly valuable and useful. I've also observed that most people who don't like these tools tend to not use them correctly, or to have only been exposed to generated documentation which didn't use them correctly.

Doxygen should *not* be used to create extensive conceptual or usage documentation -- at least not inside the source code anyhow. Doxygen shines at producing API reference documentation, which is only maybe half or one-third (or possibly even less) of all the documentation you should have. API reference documentation should include a brief description of the functionality provided, parameter descriptions (including valid ranges or input), return value description(s), what exceptions might be thrown, etc. API references should then link, or in some cases inline, additional documentation that is authored outside the source code files -- Conceptual documentation, How-Tos, code samples, design info, diagrams, etc.

Doxygen and other automated systems provide facilities to link/embed additional, hand-authored content, though it is often overlooked because it seems difficult to introduce, and they also usually provide inline (that is, through special comment structure in the source code) facilities for this functionality as well for completeness, though actually using these tools in that way will obscure the actual code quickly.

As an interesting side-note, some functional languages (I think Haskell, but I may be incorrect) offer a parsing mode where text is assumed to be non-code unless the line begins with a special sigil character -- so you get, in essence, high-level documentation in txt format that just happens to contain the actual code as well. Due to the terseness of functional languages, it would not be uncommon that 25% or less of these files might be actual code.
throw table_exception("(? ???)? ? ???");
3Xist3nZ
3Xist3nZ
Quote:
Original post by Structural

Quote:
Original post by 3Xist3nZ
I think tools like doxygen or javadoc are a very good way to document code.
The only problem i see is that most developers think that one or two descriptive lines above every method/class is sufficient.
Whats missing here is the big picture to tell the reader how to use all the classes and methods.

Then I don't understand why you recommend doxygen and javadoc. Last time I used them, either they were intended to document code on file/class/method level. Whereas this big picture you talk about stands far above that level and is better documented using diagrams, pictures, flowcharts... something graphical.


I am not a javadoc expert, but with doxygen you can write pages (look for "page", "section" and "subsection" in the doxygen manual) that are not directly related to a specific class/method/whatever. You can put your higher level documentation there (e.g. "Getting started", "Working with threads", "Managing resources"... typically you want to create a separate file for it, like "getting_started.dox").

The nice thing about this is, that you can reference those pages from your actual code documentation (classes/methods) and vice versa.

Diagrams or flowcharts are indeed very helpfull, but i think they cant replace a nicely written introductional text. Graphics and text have to complement each other. (btw: according to the doxygen manual you can include graphics into your documentation, but i havent tried that yet...)

Doxygen is not a silver bullet and i agree that writing good documentation is hard, very hard. Someone has to write it, keep it up to date, look for missing details, etc... thats a lot of work, for most hobbyist projects too much i think (including myself).

just my 2 cent :)
frob
frob
Quote:
Original post by Decrius
Quote:
Original post by Antheus
Who is your audience?


I'd be building some projects (alone) in C/C++/D. The audience would be myself and all future users.
Then you are probably documenting the wrong things.

That audience can look at the code and figure it out. The API details can be found directly by inspection.



You want to record what you cannot get from looking at the code.




The first thing you cannot get from the code is the external environment. Generally this means walking somebody through the entire process of getting started with your game, and documenting every step.

What software must be installed, including specific version numbers? What system settings need to be set to get running? How do you build the game for the first time? What tools are needed, and how does the tool chain work?

Completely missing tools are pretty easy to discover if you have another machine that currently works. But details are important. It is a waste of time to discover that the game works with library version 2.73, but when you installed it on a friend's machine you got version 2.74 which is incompatible.

The easiest way to generate that documentation is to actually get somebody running from scratch. Rather than doing everything directly, write down each step in a wiki and have them follow it. If they must deviate, adjust the wiki. If you document every question and answer they have going from a blank machine to a fully running debuggable playable game, that is a good part of it.




Another thing that future users (including yourself) should know is the rationale behind the system.

We can see HOW things are by direct inspection. WHY are things the way they are? What are exceptions to the rules? For example, you might have a specific naming convention because a specific tool requires it. Or you might note that everything is autogenerated except for two specific files, which are maintained by hand. These important details are easily lost, hard to re-discover, and should be recorded.



Another very useful but more difficult thing to document is troubleshooting steps. When you saw some specific error message, detail how you fixed it. In a business this is often done by keeping emails that discussed major problems, followed replies as people tried various things, and the eventual solutions. On your own projects, it is your own responsibility to keep those records.
Hodgman
Hodgman
Quote:
1. ...an application such as Doxygen...

From my personal experience I find this technique deficient. It requires programmers to consistently add comments in the form of documentation to their code. (A) This makes the code unreadable. Code is code, it can contain comments, but not documentation.
(B) When using computer generated documentation as a user, it's often tough navigating. (C) And the notes are poor and insufficient.
(A) isn't necessarily true. Doxygen is flexible about where in the code you place a comment. All of the documentation can go in a big lump at the bottom of a file, or even in another file altogether.

(B) This probably means that the programmers have simply added bare-bones doxygen tags, and are pretending they now have documentation. If you've just got a class hierarchy, function list, etc but no actual pages of documentation, then "yor doin it wrong".
Like 3Xist3nZ says above -- Doxygen gives you all the commands you need to create a complete hypertext document, with overview pages, example code, diagrams, a browsable hierarchy of concepts (which then link to the automatically generated function/class docs)...

(C) If you fix (A) and (B) by using the tool properly, then this problem goes away too.


In my experience, I've found doxygen documentation to usually be deficient too -- this has nothing to do with the tool though! This is from lazy programmers who aren't writing documentation, but now have the excuse "I tagged it so it's documented".

With something like a Wiki, the attitude is different - when you've got to write everything from scratch you're forced to actually write something useful.
However, there's no reason you can't use doxygen with that same attitude to produce some exceptional documentation, which is more easily kept in synch with the code-base.
Quote:
Original post by Structural
Last time I used [doxygen and javadoc], either they were intended to document code on file/class/method level. Whereas this big picture you talk about stands far above that level and is better documented using diagrams, pictures, flowcharts... something graphical.
As an example of the above -- The user-guide for doxygen (the regular 'user manual' for the tool, not file/class/method docs for the code) was made with doxygen.
Antheus
Antheus
Quote:
Original post by Structural
Why isn't it a fun thing to do then? Surely it adds value to the final product, no?
No.

Quote:
Whenver I'm told I must document all of my classes and methods with big blocks of comments it feels like such a waste of time, because the code is so clear it's obvious what is going on.
Maybe there's a requirement that there must be 500,000 lines of documentation. If there's only 499,999, the client will not pay.

Quote:
Also, documenting the methods themselves is pretty useless because every method in itself does very little.
Yet documenting the subtle edge case or deviation from accepted practice may mean the difference between that method being crucial or project being impossible.

Quote:
The magic/important thing is how everything works together, which is hard to document in code.
Not necessarily. If there is magic anywhere, then it's not documented properly.

Quote:
However, I still believe that concepts should be documented because they are not always immediately clear when reading the code.
What if client doesn't have source code? What if they can't read it? This is incredibly typical in most corporate settings.

Quote:
Also, an exception may be when you are only exposing an interface without the code, and the interface has parameters or behaviour that is not immediately clear.
Will this interface ever be used by someone else?

Quote:
For example, I always put some extra effort to take execution order dependencies out of an interface. Things like "you have to call initialize and set these parameters before calling Foo()" make me cringe. They are a programming errors waiting to happen.
Unless working with certain type of development, where coders will be following a checklist and be fired if they do two things out of order. So they are fantastic at following instructions to the dot. Yet, your clever hack will leave a certain edge case undocumented, so everything will fall apart when followed to the dot.




My point being - good documentation targets the intent and audience. What is absurd for someone may be crucial for someone else. What looks like great documentation may be a bunch of gibberish.


More examples - maybe your documentation needs to go through i18n, so that it can be translated into Mandarin by completely non-technical people. So it will need to be printed out, translated, then written back. And this alone will pay for 80% of your project and be the only reason you got the contract in the first place.

Maybe your client is government, and the project needs to have 3m of documentation. 3 meters of printed shelf space.

Or maybe your target audience are cool hip Ruby doods who shun any notion of documentation and want everything to be in Cucumber since plain unit test are like lame and any other documentation is tl;dr;

Or the only documentation is hundreds of pages of Visio diagrams, since those cheap keyboard operators are only good for filling in the blanks from such auto-generated stubs.

Or maybe your library will be so simple it will be picked up by a bunch of enthusiasts and they will suddenly want to know how it works, but they aren't all that good a coders but really like tutorials they can copy paste so they can get cool stuff done.

If making a Java library, you better use JavaDoc - it doesn't matter if it's good or not.


It really is difficult to find good guidelines, since the form and style of documentation is almost as delicate as literature. Finnegan's wake might be wet dream for certain people but most will prefer Harry Potter XVI. Or comics.

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.

Sign in to reply to this topic.