[Merge] lp:~nhandler/ubuntu-doc/packaging-guides into lp:ubuntu-doc

[Nathan Handler]

On Sun, Apr 19, 2009 at 6:43 PM, Matthew East <mdke at ubuntu.com> wrote:
> Well, user documentation on help.ubuntu.com is included there mainly
> because plenty of users go straight to the internet for their
> documentation, and don't look in the system help brower. Also, we have
> a lot of material in the wiki which is only on the website, and not in
> the package. So I don't think it's a fair comparison.

That was pretty much the point that I was trying to make. In your
earlier email, you said "the wiki was the
place where other development documentation was found". I was simply
trying to show that it is ok to have some of the documentation on the
wiki and some packaged.


> I think the development team should weigh up the pros and cons and
> figure out which process it wants to follow.
>
> As far as I can see, there are extremely compelling reasons for having
> the primary version of the packaging guide in the wiki.

I completely agree. The primary version of the packaging guide should
be on the wiki. As a result, the points brought up in Jordan's email
really would not apply. Users would be able to continue making changes
to the wiki as they have done in the past. From a contributing point
of view, there would be no change in the work flow. My idea would
simply provide another method for users to access the guide.

> That doesn't mean that if someone wants to do the work, and turn the
> packaging guide into docbook once a release (via moin->docbook or
> whatever tool works best), then it's a bad idea. It would not
> necessarily be up to date, but if the -dev team think it would be
> useful, then it can definitely be done. I think we should defer to
> them for the decision, though.

I would be more than glad to keep the docbook file in sync with the
packaging guide. I already subscribe to the wiki pages that make up
the guide, so I am notified whenever a change is made. But I am
interested in hearing what other developers and doc team members have
to say.

> I'm not sure. The people that will contribute to the packaging guide
> are members of ubuntu-dev, not ubuntu-core-doc. On that basis it
> should be in a bzr branch to which ubuntu-dev has write access, I
> would have thought. What are the reason you think it would help to
> have a single source package with ubuntu-docs if this goes ahead?

Like I said, the idea would be to have users make all changes on the
wiki. The bzr branch would then be updated a few time per cycle. As
result, I think it would make more sense to have ubuntu-core-doc have
access to the branch that the packaging guide is in, as they are the
ones with docbook knowledge, and would most likely be the ones keeping
the xml file in sync with the wiki page. I would expect that most
users/developers feel much more comfortable working with the wiki than
with a docbook file. I also am not extremely fond of the idea of a
source package for only the packaging guide.

Nathan