Re: Restructuring and organising ( Rhythmbox ) documentation.

[Mats Taraldsvik <mats taraldsvik broadpark no>]

Hi,

thanks for your reply;

On Tue, 2008-05-20 at 09:32 -0500, Shaun McCance wrote:
> On Mon, 2008-05-19 at 21:28 +0200, Mats Taraldsvik wrote:
> > Hi!
> > 
> > We are a handful of people who are redesigning the rhythmbox web site,
> > and plan to reorganize and clean up the wiki(live.gnome.org). ( details:
> > http://live.gnome.org/Rhythmbox/NewContentStructure )
> > 
> > What I would like to know, is:
> > 
> > - Where is the current Rhythmbox User and Developer documentation?
> > - If it exists, who maintains it?
> > 
> > And, more general:
> > 
> > - Where do you want the documentation to go? I'm guessing
> > library.gnome.org.
> > - I have noticed that there are mostly APIs in the developer section in
> > library.gnome.org. Should we keep our developer guides on
> > live.gnome.org, or add them in library.gnome.org?
> > 
> > I'd really like to get things right the first time, and you're the
> > experts on documentation... ;)
> 
> The most recent maintainer listed for the Rhythmbox
> documentation is Baptiste Mille-Mathias.  I'm not sure
> if that's still accurate.  I've CC'd him.
> 
> All documentation lives in an appropriate module in SVN.
> In this case, all the documentation should be in the
> rhythmbox module.  The code that runs library picks up
> documentation from known locations (tarball release,
> I think), then builds and deploys automatically when
> there's a new release.  We can certainly add whatever
> documentation Rhythmbox has.

Ok, what our plan was, since we are redesigning the site after all, is
adding a Question Submission Form for asking questions. These are then
added to bugzilla, under a separate category (user- and dev-questions).
Instead of answering the question in the bug report, the answer is added
to the documentation, and a link is added to the bug report, pointing to
the documentation.

If documentation lives in SVN-module, how can we provide access to this
for regular users? It has to be easy to use (direct access is not
needed. Either, we would take a snapshot and add the resulting
documentation to live.gnome.org or the site every time the documentation
is updated, or implement some kind of viewing layer so we can provide
the documentation on our site.

> 
> As for the developer documentation, I send an email
> a couple months ago about a proposed restructuring
> of the developer documentation on library:
> 
> http://mail.gnome.org/archives/gnome-doc-list/2008-March/msg00072.html
> 

Looks good. I'm new to library.gnome.org, and first time I checked user
and dev sections, I wondered why references were the only documentation
in the dev section. It would be logical to store all developer
documentation there.

We would need something similar for the dev-documentation. See above.

> --
> Shaun

--
Mats