

Programming without examples, demos, documentation? - quadfour

Hello HN, i&#x27;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&#x27;t do every time.<p>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&#x27;t i&#x27;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&#x27;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
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
"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.

------
ksherlock
Use the source. Or a disassembler.

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

