Re: Sprint proposal: examples for documentation

[Eduardo]

2014-09-10 16:19 GMT+02:00 Jordi Gutiérrez Hermoso <address@hidden>:

One thing that we hear a lot is that our documentation is difficult to
follow. While it's difficult to get precise information about what is
bad about our documentation, I think there is a very clear lack: not
enough examples.

So I propose that our open-to-all sprint on Sunday that would include
people not at there physically should be about adding examples to the
documentation. The barrier to entry for writing documentation is
fairly low, just have to learn a mininum of texinfo, and in many cases
we can simply turn existing tests into examples in the documentation.
It is also a task that is easily split amongst many people.

I could easily hack together some sort of interface where we list the
functions without examples, claim them, and start writing examples for
all of them.

What do you think?

- Jordi G. H.

Maybe you are talking about user level documentation. But in my case, from my newbye perspective as developer,  what I really find frustrating most of the time is trying to figure out what exactly does an specific  method from a certain C++ class. I find myself recursively inspecting functions until I reach the real implementation that allows me to understand the true behaviour. All that may be avoided with a simple "foo() method does that and that, but does not check this". I don't know if anyone feels like me when it comes the time to use the C++ API.

Anyway the proposal sounds fine!

Edu