

Making Code Easy to Understand – What Developers Want (a study) - cfontes
http://blog.architexa.com/2011/07/making-code-easy-to-understand-what-developers-want-a-study/

======
Rusky
Definitely agree- usually whenever I start looking at the source of an open
source project it's difficult to figure out where things are. A top-down view
of the project's architecture, besides just the source tree, would be
extremely useful in situations like that.

~~~
abhirakshit
Rusky,

I agree that understanding an Open Source project without proper documentation
is really hard. For the same reason we are trying to create this site
(<http://www.codemaps.org/s/Lucene_Core>) to document open source projects.
This is still in beta and we would be glad to hear your thoughts on it.

------
johnwatson11218
I have been very frustrated in the past when the only documentation provided
was javadoc. In many cases there was an xml that was not documented very well,
and subtle things about the classpath that kept the system from working. Often
the javadoc is just regurgitating the name of the method. In many cases the
javadoc reminds me of the help systems in windows programs. I think I remember
seeing a discussion on reddit where they were asking if anyone had ever found
an answer in a windows help topic.

~~~
sethrq
I agree, no one type of documentation can live in a vacuum. Ideally, javadoc,
sample code, tutorials, diagrams, and summaries/explanations would be present
for every code base. But in reality I find even a few simple diagrams combined
with a insightful description is infinitely better than pages of minimal
javadoc.

------
DougWebb
So, developers need and want Overview Documentation, and Overview
Documentation is not the same thing as Reference Documentation (which is what
tools like JavaDoc produce.)

Does anyone find this surprising?

Regarding code examples vs test cases: they're different in the same way
Overview docs are different from Reference docs. The code examples are part of
the overview, and show the typical / most common ways of using the code. The
test cases are like reference docs, and show every nuance and feature of the
code, including all variations on argument and response types and error paths.

------
aangjie
I once remember taking over maintenance of a previous project and being handed
20-25 pages of minute details(mostly meaningless to anyone but a newbie to the
s/w). But no mention of what happens overall. I spent a day to come up with a
workflow diagram (in a page) that made quick sense.

P.S: for those who like to blame outsourcing to India, this one was from a U.S
contractor

------
dstywho
i don't want java doc :D; i want rdoc.

------
wccrawford
I like how 'code examples' are above 'test cases' ... But a test case would
include a code example, and proof that it works. -sigh-

~~~
angdis
I think code examples are something that are best included in the "getting
started" section of documentation. It gives the user a quick, usable, concise
illustration of how to perform the most basic tasks. Sometimes that's all you
need and this is frequently omitted by some software documentation.

Test cases are certainly useful if you need to dive into
comprehensive/advanced usage of the API. But if you just want to "get
started", a huge vat of unit tests can be daunting.

