Re: Canonical jhbuild documentation

[Sriram Ramkrishna <sri ramkrishna me>]

On Tue, Feb 10, 2015 at 1:06 PM, Allan Day <allanpday gmail com> wrote:
> Sriram Ramkrishna wrote:
> > > > Problem: we have many pages on jhbuild documentation
> > >
> > > Let's list them:
> > > 1. https://wiki.gnome.org/Projects/Jhbuild
> > > 2. https://developer.gnome.org/jhbuild/unstable/
> > > 3. https://wiki.gnome.org/GnomeLove/BuildGnome
> > > 4. https://wiki.gnome.org/GnomeLove/JhbuildIntroduction
> > > 5. https://wiki.gnome.org/HowDoI/Jhbuild
>
> Seems like you should talk this through with Carlos and Ryan - they're
> the effective maintainers of the wiki pages in question. I know that
> Carlos is keen to reduce the amount of duplication.

Yes, I sent this email after consulting with him and Fred.  It's been
kind of stuck, so I volunteered to help manage the conversation and
hopefully get it into a single manageable area for newcomers.

> People will always come across the official manual on
> developer.gnome.org, since this ranks highly in search results. So, if
> you really want people to easily find the introductory documentation,
> it will have to live as a part of the official manual. I get the
> impression that there has been resistance to this in the past, due to
> the desire to keep Jhbuild as a somewhat generic tool. However, I
> don't see how the two use cases (Jhbuild for new GNOME contributors,
> and Jhbuild for everyone else) couldn't be satisfied by structuring
> the manual according to audience.

This is precisely what I'm advocating.  Anything advanced, special
workflows, whatever should go into the manual and leave the jhbuild
for newomers as the single spot that people should go to for the first
time.  Improve the manual for everything else.  If you have
specialized jhbuild stuff then work with Carlos and see how it can be
worked out.

In general, we talk about "Just Works" for our desktop, let's apply
that to our build system.

Since Carlos is willing to maintain the page and is sitting in the
GNOME Love channel and monitoring the mailing list, he's in the best
position to refine and update the page based on feedback given.

If there is something about Carlos' documentation that is missing that
is in the other pages, then let's bring it up either in irc, or you
can mail follow ups to gnome-love mailing list and we can debate it
there.

sri


> Allan
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> https://mail.gnome.org/mailman/listinfo/desktop-devel-list