Re: The problem of documenting complex modules.

"...they don't have a simple in; a clearly defined and obvious starting point that gives a universal starting point on which the new user can build."

This is nothing but the truth.

It seems like there is a tendency on CPAN that the documentation of some modules is written in a disastrous style. Just good for some initiated who know what to do.

But compared to the documentation of less or more complex modules/classes in other languages, especially a certain language i think that we still live in the Garden of Eden.

I don't know if you program in Java (unfortunately i'm forced to do it now). If not please try to figure out some stuff in this language. A very special experience. I guess you will land on some websites that just show that crap from javadoc. Next step: go to Oracle's Java Tutorial Site. Then go to Stackoverflow and continue. Now buy a book. Steps are interchangeable. No JavaMonks. That was it. I wish you well ;-)

Best regards, Karl

P.S.: IMHO another example of good documentation of complex stuff at MCE by marioroy.

ŤThe Crux of the Biscuit is the Apostropheť

Comment on Re: The problem of documenting complex modules. Download Code

Replies are listed 'Best First'.
Re^2: The problem of documenting complex modules. by BrowserUk (Patriarch) on Jul 10, 2015 at 19:35 UTC
I don't know if you program in Java I do. Or at least I did once. It is the only language I ever got certified in. Not that I consider that any recommendation. It took me just 3 weeks to go from zero Java to passing the three levels of Java certification that BrainBench offered back then (something like: Beginners, Advanced and Enterprise). I was angling for a (senior) position in a startup my brother was getting involved with, that required Java. (I kick it in to touch after my first telephone conference with the head honcho of the founding trio; he was a salesman, selling something that didn't exist, he didn't understand, and which he had no idea of how to create. But he talked up a storm and had secured $5,000,000 round 1 VC cash on the back of it. When pressed, he admitted that his main goal was a couple of years of fast cars and high living before folding the company.) If not please try to figure out some stuff in this language. A very special experience. I had to do so very recently in order to produce a Perl equivalent to a Java library. Not a pleasant experience, hence why my aversion to javadoc and its ilk is so fresh in my mind. With the rise and rise of 'Social' network sites: 'Computers are making people easier to use everyday' Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. I'm with torvalds on this Agile (and TDD) debunked I told'em LLVM was the way to go. But did they listen!	[reply]
Re^3: The problem of documenting complex modules. by karlgoethebier (Abbot) on Jul 10, 2015 at 20:14 UTC
"He was a salesman, selling something that didn't exist, he didn't understand, and which he had no idea of how to create." A cool lyric. Perhaps it is a bit too long to print it on a T-shirt to wear in office. Best regards, Karl ŤThe Crux of the Biscuit is the Apostropheť	[reply]