Re: [Vala] Contributing (to docs)

[Matt Butler <butler matthew gmail com>]

Hi Phil,

Thanks for your reply. I suppose initially I'd like to work with the
valadoc.org site and APIs to expand them further, as many currently just
show the method or class signature without any/many details about arguments
or explanation as to what all their purposes are (most are obvious by their
names, but certainly some could be elaborated on). However two things I'm
concerned of here. First is that while the site seems to be setup wiki-like,
after logging in, when I change to the APIs the log-in doesn't persist.
Secondly and more so, if the documents here are automatically generated I
wouldn't want for it to all be lost next time the documents are generated. I
understand that the majority of the valadoc references are generated
directly from source and the comments in source could be updated to have
more full documentation, however I believe most of the VAPIs are
automatically generated from vapigen.

I'm not sure if there is a away I can contribute to fleshing out these Vala
API references or if it's best that those are auto-generated from their
existing C documentation/sources.

Matt

On Sun, Mar 13, 2011 at 8:46 PM, Phil Housley <undeconstructed gmail com>wrote:

> 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



-- 
Matthew Butler