Programming without examples, demos, documentation?

https://news.ycombinator.com/item?id=7123358

by quadfour • 12 years ago

9 4 12 years ago

news.ycombinator.com

Hello HN, i'm a informatics engineering student from Portugal. Lately i found that i almost always over rely on demos or examples to start something quick or solve some problem. Checking examples is obviously quicker, but that won't do every time.

Last project i did, used apache jena (a java semantic web framework), they provide many examples on their website (i gotta say it needs improvement), if they didn't i'm afraid it would have taken me way too much time to get stuff working. It has way more classes and patterns that my beginner brain can handle at once. I found generally that is really hard to find the starting points just by looking at javadoc's. So, how do you manage when something you want to use is complex and there is no examples( or documentation), is this just an endurance problem to figure out how everything works? do you have any special approach? Thanks

pedalpete• 12 years ago

Depending on the situation, you may be able to jump into the source code and check how they do things, but personally, I don't.

If the developer/community of a language, framework, library, etc. etc. haven't taken the time to write good documentation and provide some examples, I tend to stay away from it. It takes extra time for us to understand how something was built, and why. The developer should help us along with this.

Think about even the simplest API if it isn't documented, how long will it take you to figure out what you can do with it and how.

For me, it is also likely that the original developer is a much better programmer than I am. Or at least, I assume they are. I suspect there will be much of their source that I don't understand. Of course, reading their code makes me a better developer, but I'll often need help, and good documentation will help along with that.

It sounds horrible to say "I expect that if you're going to create an open-source bit of code that will help me code better/easier/faster, I also expect you to document it well and give examples", but if somebody is going through the trouble of developing something they want other people to use, I think this is an important part of that process.

What do people think of documenting first, and building from that documentation? I'm putting together my first open-source project, and am thinking that may be a good way to manage the documentation thing. Anybody done that before?

jfaucett• 12 years ago

"If the developer/community of a language, framework, library, etc. etc. haven't taken the time to write good documentation and provide some examples,".

I couldnt agree more. It takes a lot of time and sweat to make a good library or framework, writing up some examples takes very little time in comparison and when the developer/team hasnt gone the last mile here, it usually makes me think they havent done it with their framework as well.

Also "What do people think of documenting first" well, theres a great talk by Tom Warner about README driven development that is just about this, and Im a huge fan of it. Work out how you would like to use your library before you program it, and as an added bonus you have documentation at the end.

Also as an added note to other devs reading this, I care much less about "API docs" because I get the same thing from just reading the source. Id be perfectly content with examples.

liuyanghejerry• 12 years ago

Let's have lunch without forks, spoons, or chopsticks.

ksherlock• 12 years ago

Use the source. Or a disassembler.