Re: [Vala] Contributing (to docs)

[Phil Housley <undeconstructed gmail com>]

On 11 March 2011 17:38, Matt Butler <butler matthew gmail com> wrote:
> I've recently come across Vala, and am loving it so far. Provides the high
> level interaction I'm interested in using yet the speed and benefits of
> being natively compiled.
>
> One thing I've noticed however is that documentation is sparse and rather
> scattered. (For instance some information on the live.gnome.org project
> site, some on valadoc.org (api's) and for the life of me I haven't gotten
> the Devhelp documents working.
>
> In any case, I'm interested in helping to contribute to the documentation of
> vala syntax, apis, and potentially tutorials. I think this would also be a
> great way to help myself learn further details of the language, bindings
> etc.
>
> I'm wondering what would be the best way for me to be able to contribute,
> and if there is someone currently managing this area for me to collaborate
> with (especially initially to ensure I followed to any practices,
> formatting, etc). I'm looking forward to contributing as best I can to this
> project and improving the documentation on this wonderful language and
> associated libraries.
>
> Thanks in advanced,
>
> --
> Matt

Hi Matt,

No one is managing the documentation as such, though lots of people
have contributed to it. I wrote the original version of the tutorial,
and quite a lot of the manual, but they've both grown a lot since I
last did anything on them.

I'm not sure what more exactly you would like to see, so I'll quickly
describe the pieces that exist at the moment, and let you decide what
you would like to work on.

http://live.gnome.org/Vala/Tutorial is a feature by feature guide to
Vala, describing all the common and some less common parts of the
language. It doesn't give precise definitions, but has lots of (short)
examples. It does cover some bits of core library (glib)
functionality, but is mostly about the language.

http://live.gnome.org/Vala/Manual is or will be the reference and
specification for the language. It has nothing about any libraries,
but goes into precise detail about syntax etc.

http://valadoc.org/ is a reference to most of the libraries accessible
through Vala. It is generated/updated by the valadoc tool, but is also
editable. I would guess that at some point more documentation will be
auto-populated from the existing documentation for the libraries, but
I don't know how possible that is.

Everything else at http://live.gnome.org/Vala/Documentation is more
specialised, and generally more static, such as the articles on how
Vala differs from C# and from Java, and all the code samples (which
are hopefully self-documenting.)

I'm sure there is room for more articles on specific subjects, and for
more samples, but I don't know of any that people have specifically
asked for. Also, I think there has been some work on a longer form
tutorial, concentrating on working code rather than short snippets.
Hopefully someone else can update on the status of those.

-- 
Phil Housley