using lenya / forrest for ubuntu documentation?

[Sean Wheller]

On Saturday 11 June 2005 19:00, Gregor J. Rothfuss wrote:
> i just came across
>
> http://www.ubuntulinux.org/wiki/DocumentationTeamMeetingSummary4
>
> especially:
>
<snip what="meeting-summary"/>

Hello Gregor, African Greetings. Good to see you venturing beyond the ASF :-)

You may or may not know me from the Forrest Project. I have a number of sites 
running under Forrest. My own included, which has a custom skin (URL at end).

>
> i wanted to alert you guys to an ongoing development over at the ASF. we
> are in the process of eating our own dogfood, and making steps toward a
> documentation system that might fit your bill:
>
> http://wiki.apache.org/cocoon/Doco

I am aware of this project. I follow forrest-dev and contribute where I can. 
The idea of Doco is good and was the base of a concept that I tried to 
explain to people at ubuntu. Unfortunately, for numerous reasons, I failed.

The problem is we need Docbook but users can't/don't want to spend time trying 
to learn it and work with it. Then there is SVN, as easy as it is to use, 
most users have a fear of working with revision control systems. They are 
comfortable hacking work in wiki or as HTML or in OOo Writer, but not using a 
Structured XML Editor or source/text editor. At Ubuntu most of the people who 
want to contribute docs are not very technical people, but they have figured 
out how to do something and want to contribute back by writing a how-to, for 
example. The Ubuntu-doc team policy has been to make it possible for everyone 
and anyone to contribute if the wish.

As you know, the problem with having multiple formats for storage of documents 
is that it become near impossible to manage and repurpose information over 
time.

So just as Doco describes, we wanted to bring the ease of wiki editing 
together with the valid and well-formed nature of XML. In particular to be 
able to utilize the batch processing environment already provided by Docbook. 
Mainly because Docbook is utilized by all Ubuntu upstreams.

In a test box that I installed for the purpose of developing a solution to 
this problem, Lenya did 90% of what we need, BUT:
1. I could not test it in a production environment like ubuntu.com
2. Docbook is a big DTD and Bitflux took long to load over my LAN. I would not 
like to try it over the Internet.

This Lenya was fed docbook xml from the docteam svn. So it was essentially 
editing the xml src of a working copy. It was a bit hectic trying to get the 
checkout files displayed in lenya but finally with lots of coffee and a few 
early mornings I got through the docs and made it work. Well, what worked was 
the editing, I made the system as easy possible for the test purpose. Working 
on Localhost and some computers in my LAN I was able to do edits. Then I 
would ssh into the box and svn diff to see it was working. If I could do that 
then I was happy because it mean I could merge the diff to the repos if I 
wanted.

In my senario I saw lenya as a great big harvester, many authors editing one 
working copy of svn that commit users could control and merge back to the 
repos. I did for see some workflow problems with this, but seeing doco I 
think you may have already nailed them.



One problem I must warn of. It's a religious question, of Java, that you will 
need to overcome with the ubuntu community, especially people at canonical. 
Seems that Java is a 4-letter word in the ubuntu community because it is not 
free. It's silly, I know, but that is the reality. I don't think the 
ubuntu-doc team cares what technology is used so long as the solution works, 
so there is your support base, but higher up you may have resistance. 
Sometime, the people up top, bless their cotton socks, tend to forget that 
this is a community project. Sorry I speak it how I see it these days.

I think that with Lenya Dev and Forrest Dev we can get a working robust 
solution. Should you fail in your attempts with Ubuntu, I have another 
opportunity. Some friends in the CO.ZA community are setting a server to run  
gnome.org.za. This is new, but would be used to edit docbook xml documents 
from the GNOME Documentation project checked out from GNOME CVS. Let me know 
if you would like to do this or not. It is not Ubuntu related and we have 
total autonomy over what we will do, so politics aside I think we can move 
quickly and possible have it up and running in 7 -14 days. It could be a 
great live test case. I think we are happy to play crash test dummy.

Hope this helps,


-- 
Sean Wheller
Technical Author
sean at inwords.co.za
084-854-9408
http://www.inwords.co.za
Registered Linux User #375355
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20050612/2d61681b/attachment.pgp>