Guidelines for writing?

[Enrico Zini]

On Fri, Nov 19, 2004 at 03:49:11PM -0800, Matt Kirchhoff wrote:

> I agree that nitpicking over grammar/punctuation is unnecessary, but
> we should employ guidelines for person/tense/voice and other major
> stylistic concerns.

On Sat, Nov 20, 2004 at 01:34:45PM +1100, Nick Loeve wrote:

> I am not sure if any tools for this already exist, but we could come up
> with some standard DocBook book and article templates, and as well as
> entities like above, we can also standardise the way documentation
> references or explains processes, OS's, and concepts. This could be a
> centralised growing list of 'documentation objects' that we can reuse
> and include into any xml process (XSLT etc). I think this will help to
> keep documentation clear and consistent across the whole documentation
> project.

I see the possibility of having a package for ubuntu documentation
people ("docteam-tools" or something alike) which installs a guideline
document (on which I could work with Matt, if Matt agrees) and various
docbook templates (on which I could work with Nick, if Nick agrees.

Matt, Nick: if you agree, I can create and post a skeleton package and
then we can fill it up together.


> So for an example...
> If we have the xml entity '&gnuubuntu;' to used in the DocBook source,
> the when we transform the DocBook source into wiki markup, it maybe be
> output as the term 'Ubuntu GNU/Linux' wrapped in a link to what
> reference means in terms of context. For this case it would be the open
> source attributes and concepts at work in Ubuntu.

This is interesting, but it would open some problems when one
concurrently updates both the DocBook and the Wiki, and then this
automatic conversion happens and the wiki changes get lost.


Ciao,

Enrico

--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at enricozini.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/20041124/32f9e0bd/attachment.pgp>