Creating documentation

[Phil Bull]

Hi Dougie,

On Sun, 2009-04-26 at 19:59 +0100, Dougie Richardson wrote:
> I was thinking that DocBook and our toolchain is frequently suggested
> as putting people off of contributing, would it be possible to create
> a text based submission system that those familiar with DocBook could
> wrap?
> 
> I find it awkward to read patches that are wrapped anyway and wouldn't
> mind wrapping them myself.
> 
> How we would we control it and would people be interested? Could we
> use it as a teaching tool for some of our IRC sessions - talk through
> creating a new page from a submitted text file? Would this be a lot of
> work?

It depends on what sort of work is being done. If someone is making a
small patch, it's pretty pointless because doing the markup forms the
bulk of the task.

If it's something more substantial, plain-text submission is fine. It
should be encouraged, even! When you're writing documentation, the most
important thing is the content, not the markup. I'd rather that new
contributors spent their time thinking about their writing rather than
grappling with DocBook.

I don't think that we need a separate submission system. We can just
have text files sent to the mailing list or attached to bugs.

Teaching people how to markup text sounds like an ideal topic for an IRC
session.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/people/philbull