New developer documentation

[Jordan Mantha]

On Jan 29, 2007, at 7:13 AM, Matt Zimmerman wrote:

> On Fri, Jan 26, 2007 at 09:27:39AM -0800, Jordan Mantha wrote:
>> On Jan 26, 2007, at 7:08 AM, Matt Zimmerman wrote:
>>> I would appreciate feedback from developers about it, especially:
>>>
>>> - Existing resources which should be linked from it, or
>>> incorporated into it
>>
>> Well, I don't really see any references to the Ubuntu Packaging Guide
>> [0] .
>
> Indeed, I wasn't even aware of that document until recently.  Who  
> wrote it,
> and who has reviewed it for accuracy?
>

Mostly I did during Dapper. It is shipped in the help for Dapper and  
Edgy for Ubuntu and Kubuntu. I have tried a couple times to get more  
dev reviewing but it's mostly been crimsun and a few other MOTUs that  
I can get to read it. I've incorporated much material from the wiki  
( pitti's excellent patching tutorial for MOTU School as an example)  
and Debian Policy. At some point I'd like to take much of the policy/ 
reference type material from the packaging guide and wiki and get the  
Ubuntu Developer's Reference going.

<snip>

>> "Starting points" starts out with a reference to MOTU and then in the
>> next section "Communication" it doesn't refer to #ubuntu-motu or
>> ubuntu-motu ML at all.
>
> Those resources are prominent on the MOTU page, however.  I do not  
> want to
> give the impression that MOTU should limit their involvement to
> MOTU-specific channels and lists, as was my worry when they were first
> introduced.

Good point

> It's useful to have separate discussion areas for MOTU so that they  
> can be
> used for intra-team coordination, Q&A, etc., but general developer  
> talk
> should be in one place for all developers.
>
> i.e., MOTU should also participate in ubuntu-devel at lists and  
> #ubuntu-devel!
> I'm CCing ubuntu-motu at lists in case this is not quite how it works  
> yet. ;-)

I think it is the case for the most part. I'm sure there is a bit of  
an intimidation factor, but that's not always a bad thing ;-)

>> Some of the links are to MOTU/ wiki pages but are referenced as being
>> general. I think we should either have a generic page (in perhaps a
>> generic namespace) or  1 page for Universe and 1 page for Main. I
>> think it would be nice to have 1 page and simply note where Main and
>> Universe workflows diverge. This page is certainly a step in that
>> direction and I'm glad to see it.
>
> That is my intention, yes.  It doesn't yet index all of the MOTU  
> resources
> (and there's an XXX about that).  I'd appreciate some help from  
> MOTU folks
> who know what's there and can advise us about how to best  
> incorporate them.

I think you've started a very good thing with UbuntuDevelopment. I  
think it might even be a good idea to use that wiki namespace and  
move the material from the MOTU wiki pages that is general to  
UbuntuDevelopment/ sub pages. That way it can be edited/reviewed/used  
by *all* Ubuntu developers. I generally dislike having lots of pages  
that are nothing but links that take you all over the wiki. Having  
concise and accurate developer documentation is very helpful.

I must confess that I mostly don't think of documentation outside of  
MOTU, primarily because it seems like most core-devs know what they  
are doing already and MOTU is generally the packaging beginner  
landing place.

The MOTU wiki has a lot of information, but there is definitely parts  
that are outdated or inaccurate. Perhaps a joint effort between  
MOTUs, core-devs, and perhaps a little help from the doc team ( tips  
on making the pages readable and user friendly) could get the Ubuntu  
developer wiki pages in good shape. I've seen first hand that the  
current situation can be quite confusing to new and experience  
developers alike.

-Jordan