#ubuntu-doc report for 2004-12-30

[Enrico Zini]

Happy new year!!


#ubuntu-doc report for 2004-12-30

* What's in userguide/old ?

Froud asked what's in userguide/old.  It seems like things coming from
an old FAQm and he sees there are some good contents there that can be
moved to proper places.

ChrisH says: Good question. Last time we decided to merge it into the
             User's Guide. But we didn't have the FAQGuide back then.

"Spring cleanup" Froud would like to move the useful things from
userguide/old into where they are needed, then get rid of the old
directory.  He proposes that: "the general concepts can be rewritten and
thus moved into UG, or we can just add them to FAQ after comparing texts
on Wiki."


* Ubuntu DocBook Interchange Protocol

The title is scary, but read on.

Froud started an "Ubuntu DocBook Interchange Protocol" page in the
wiki[1].  Besides the scary name, the page describes how we write
DocBook so that other groups can easily import it:

  "One of nice points about Docbook is that it was designed so that
  people can easily interchange documents. At first this was mainly a
  UNIX thing, but as as the open source movement gained momentum this
  ability was extended to GNU/Linux. Today, Docbook documents are
  interchanged between people on all platforms.

  However, simply using DocBook or a subset of it is not enough to
  ensure successful interchange. Docbook has many tags and there can be
  as many permutations of its application as there are projects using
  it. So in order to facilitate interchange it is useful to inform
  people about the markup documents use and any of your additional
  markup conventions and processing expectations that impose constraints
  on processing. What follows is a definition of the Docbook Usage for
  the Ubuntu Documentation Project."

[1] http://www.ubuntulinux.org/wiki/UbuntuDocbookInterchangeProtocol


* "Installation guide" package in bugzilla

Enrico started the quest to have an "Installation guide" package in
Bugzilla so that we can report bugs and send patches to Colin for the
Installation Guide he maintains inside the debian-installer package.

Just to have an idea on how ignorant Enrico was on Bugzilla things:
 <enrico> lifeless: hey!  Question: I've seen needs for a "installation
          guide" component/subproject/whatever inside the "documentation"
          product/component/whatever in Bugzilla
 <enrico> The idea is having something representing the installation
	  manual inside the Debian Installer package, to report bugs for
	  Colin
But luckily:
 <lifeless> what you need to ask jdub for is a new 'package' called
            'installation guide' in the 'documentation' product.

So, the moral is: it doesn't matter if you're technically knowledgeable
or not: there's always someone you can ask! :)


* Committing syntactically incorrect DocBook

Froud noticed that it happes that syntactically incorrect DocBook gets
committed to the repository.

People agreed that it's not too bad and can always be fixed easily, as
the most important thing is that contents do get into the documents.

The quality of the committed DocBook can anyway always be improved by
writing some short guide like "How do write good docbook for the UDP" or
"Top-5 mistakes in committed DocBook and how to avoid them".  Having
well-formed DocBook will eventually be a good thing to allow other
groups to include parts of our work.


Ciao,

Enrico

--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050101/81aabe34/attachment.pgp>