Guidelines for writing?

[Sivan Green]

Nick Loeve wrote:

>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.
>  
>
Sounds very good. I am very fund of standardization, so I would have to 
say a big "yes" to that. We would then just go and publish the "DocBook 
STD Ubuntu guideline" to help new people use the already established 
std, so getting a very neat and streamlined look and feel eventually.

>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. 
>  
>
I am not sure why you would want to go out and put this on the wiki, 
could you refer to my other post about the actual position of 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.
>  
>
This is how it should go, nice thinking!

Sivan