Guidelines for writing?

[Nick Loeve]

On Fri, 2004-11-19 at 15:49 -0800, Matt Kirchhoff wrote:
> On Sat, 20 Nov 2004 00:18:09 +0100, Enrico Zini <enrico at enricozini.org> wrote:
> 
> > This discussion made me remember that many editors have writing styles
> > guidelines for their writers, to guarantee some level of uniformity.
> 
> As an aside, I'd be willing to serve as an overall style editor for
> finalized documents. I have experience in this area, and I could help
> ensure stylistic consistency across the wide range of documents we'll
> likely encounter.
> 
> I agree that nitpicking over grammar/punctuation is unnecessary, but
> we should employ guidelines for person/tense/voice and other major
> stylistic concerns.
> 
> -- 
> Matt Kirchhoff
> 

When developing DocBook style documentation we could define some
standard xml entities for the different references to linux/gnu/ubuntu
defined earlier, and some basic stylistic controls... which leads me to
my next thought:

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.

Once we have some templates and 'documentation objects' we (i would like
to look at this task) can build a tool to transform docbook xml into the
formats needed for local documentation (ie for yelp etc), and also build
and post markup for the wiki. 

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.

Anyway... just a random idea i had right there and then :)

;) trickie