New web based docbook editor project (was Re: Helpingyourdocumentation effort.) sec=unclassified

Thu Apr 20 03:47:18 UTC 2006

>  Can someone pleaes explain to me why opening up gedit or kate or Quanta++ or anyother editor is so hard to use?  This is talking from 
>  someone who has never created a package, never even created his own makefile and yet I can create documents in DocBook using Kate to >  edit things.
>  
>  I am trying to see what the big "barrier" is and I just don't get it.  Let me explain further, I have alway been interested in Linux and always
>  thought it would be cool to 'give back to the community."  However I was a programmer, I wasn't a developer and yet with the simple tools of 
>  kate and subversion I can work on the documentation.  Of course that has now grown to working on wiki docs, bug testing and other great 
>  things.
> 
> Can someone help correct me? (honest I want to try and understand)

The barrier is the learning curve associated with such tools and the obvious work flow issues that are involved. Proof of this is the numerous "unofficial" Ubuntu documentation projects that continue to pop up everywhere, people just want to write and not have to learn several different tools to do so.

To contribute currently you have to:

a. Learn Subversion (large learning curve)
b. Learn Docbook (large to huge learning curve for many)
c. Learn how Quanta works (I still don't use these tools and prefer a text editor myself)
   or
c. Be comfortable using a text editor (maybe with simple highlighting) to edit Docbook code
d. Install and set up these tools
e. Get a commit account on the Docteam's Subversion server (which allows you to trash everything at will)
f.  Switch between these tools to update, edit, commit, build and check work
g. Learn how to generate .po files etc manually for translation
h. Maintain Makefiles generate html, pdf etc
i.  Some skill with English

That's all I can think of now, but compare that to:

a. Learn the basics of Docbook (not even necessary with an editor like Samara)
b. Learn how to use a web browser (everyone except grandma, god bless her soul, has this skill already pretty much)
c. Learn how the 'website' works
d. Some skill with English - could even be any other language that you care to write in and translate on the fly (very awesome).

Then pile on top of that the added benefits of different access levels, a largely automated community contribution/correction system, proper control of this system by key Documentation Team members and better integration with Rosetta and Launchpad itself; I know which one I would prefer. One additional benefit is that people such as yourself can still fire up Subversion and G/Kedit and continue to contribute exactly as you have always done. 

This will take some work to implement, don't get me wrong on this, but the benefits are just too large to ignore.

- Robert Stoffers

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20060420/3d0fbfac/attachment.html>