Re: Sprint proposal: examples for documentation

[Carnë Draug]

On 10 September 2014 15:19, Jordi Gutiérrez Hermoso <address@hidden> wrote:
> 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.

At OctConf, two years ago, there was a proposal about having demos
merged into the documentation. There was no real discussion about it,
only that there is a duplication of effort. It may be worth discuss this
better and implement something.

> 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?

While it is something that would be nice for us, it's probably not the
sexiest project, and therefore not be the best thing if we want new people
to join. A list of easy to implement missing functions (there's a few from
recent Matlab releases) may be of more interest for some people. Maybe
a small set of small projects for different levels of comfort with Octave,
may be better. Writing doxygen documents could also be a good one.
I may be wrong, and having people all working in different things goes
against the point of a code sprint.

Carnë