Last Will & Testament?
Let me start with a few relevant facts about my life. As some of you will know, I spend 60-70 hours every week helping with mailing lists, forums and userbase. It is a huge part of my life. However, in a few weeks’ time I will be 70, and I have a serious heart condition. I may be here for a few years yet, or I may be gone tomorrow. And what will be my legacy to KDE? At the moment it’s a handful (albeit a big handful) of wiki pages. That’s not what I want my legacy to be.
I have a dream for that, and it’s realisable. I want to leave a system that will spell an end to ancient documentation. A system that is easy to use and light on time required to maintain it. A pipe-dream? No, I don’t think it is. Several people have said that drafting documentation on a wiki is much easier than working directly to docbook, but getting the parts to talk to each other really makes it difficult. I’ve talked to Albert Astals Cid about what would help language translation, and I’ve talked to Burkhard Lück about what the docbook team need, and I do believe we could get a usable system, and without much delay. Here’s what I propose:
Stage 1 – the system is triggered by changes to userbase pages. It first addresses language needs.
Question: is it possible to create RSS feeds for certain groups of pages?
Problem: currently the Recent Changes RSS feed is broken, sending multiple copies of alerts. That would have to be fixed first.
Stage 2 – A mediawiki extension outputs a .po syntax file for the changed page. I understand that http://www.mediawiki.org/wiki/Extension:Translate would do that. Reading through the page, it looks as though a set of tools already exist that implement export and import.
Stage 3 – the exported .po file arrives in SVN, where the system follows normal development lines. It may save translators considerable time if a diff of the last two versions is sent as well. This information is readily available through the History pages.
Stage 4 – the mediawiki tool poimport.php is used to import the returned .po file into userbase.
Stage 5 – starts the docbook cycle. The mediawiki extension http://www.mediawiki.org/wiki/Extension:XML_Bridge creates docbook XML from mediawiki pages. The proposal page http://www.mediawiki.org/wiki/DocBook_XML_export explains how it works. The resulting output could be made available through docs.kde.org, on distribution disks, and on userbase.
If scripting is needed to make these stages flow, Sayak Banerjee, of forum fame, has agreed to write the scripts for us. Many thanks to Albert, Burkhard and Sayak for working with me on this.
So – where does that leave us? Well, before extensions can be added they have to be tested. For me to do that I need Mediawiki setting up locally, and for that I need a LAMP stack. None of this is familiar to me, and I’d be working alone, without any form of help. I could do it, but in a reasonable time-frame? I doubt that. So what are the options? I’m assured that the system would be an enormous time-saver for the i18n and docs teams, so what is the best way forward from here? Is it possible, for instance, that I could have access to a LAMP stack somewhere else, to be used as a sandbox? I need all the help and ideas I can get.
13 Comments
RSS feed for comments on this post.
Sorry, the comment form is closed at this time.
Wish you the best for your health…
+1 for the MediaWiki Docbook idea as well…
The main reason why I don’t update documentation is that I don’t really know how docbook works (yet), using MediaWiki would be so much easier to edit and to maintain…
Lukas
About your legacy, I think you underestimate what you have contributed. You initiated, inspired and guided many of the user oriented projects within our community. Many in the community helping out on userbase, the forums and mailinglists wouldn’t have been with us if it wasn’t for you. Not to mention your work with the community working group, again, it wouldn’t have been what it is without your input. You already have left a lasting impression on our community. I’d say faith has plenty of reasons for letting you stay many more years with us!
This is a pretty interesting idea and I wish you much luck.
I’m wondering if userbase is the best place to do this, though. Userbase contains a wealth of information, but it isn’t as detailed or formal as application manuals generally are. I think separating the two might help with focus.
It might be advantageous to create a new “docbase” wiki that contains only content that will end up in application documentation. That would also mean you don’t have to mess around with these extensions on userbase, which won’t really need them.
@Parker: The way I see it is not to have the majority of the current UserBase pages going through this system, but to allow projects to take an unlinked page or set of pages, i.e. http://userbase.kde.org/projectname/Manual which is not linked from any other page. This would act as a scratchpad and draft for developers to work out their ideas. It would probably mean that until they are nearing their desired results they would mark the pages as Minor Edit, and only when they upload an edit without that flag would the system be triggered.
Wow, Anne, I wouldn’t have thought you were much over 50? You certainly have an incredibly youthful vigour!
Your legacy to KDE will be a helluva lot more than a few wiki pages, there’s a lot of us you’ve helped a lot over the years and we have elephantine memories!
I can set you up a MediaWiki on my server if you want a sandbox to play around with pretty easily.
Let me know how I can help:
mike@mikearthur.co.uk
@Mike Arthur: Thanks for your support. I may yet be in need of practical help and advice.
I think this is a valuable effort. I’m afraid I haven’t been able to find the time to contribute much to KDE in the past, but in this instance, I think I can help: If you need a LAMP stack, I have no problem setting up a vserver with SFTP access to apache/php and an attached mysql (or postgresql) database.
Just write me an e-mail if you want me to do so. 🙂
-Toke
@Toke Høiland-Jørgensen: Thank you for the offer. I’ve had several offers, in an amazingly short time. I’m so impressed 🙂 I will definitely come back to you if I need it. Thanks again
You absolutely ROCK! I’m immensely grateful for the results of all your efforts. It is always interesting to read your posts to the planet. Great ideas for transforming our archaic doc system!
+1000 to this idea. Documentation to help learning / switching is frequently one of the biggest barriers to people coming to open source. Who hasn’t spent countless hours looking through old, outdated documentation when starting out?
I would also suggest that maybe, just maybe, our legacy is measured less in how many wiki pages we touch, than how many people…
Thankyou, Anne for touching so meany people through your efforts (even ones you’ve never talked to).
No matter how cool KDE is, health is always more important. I hope you’ll take a break, focus on getting better, and let us all read you blog posts for the next 20+ years. 🙂
Thank you, thank you, thank you for all the work you’ve already put into the community.
Hey guys. Great to see that you guys are picking up on the Translate extension. We hang out in Freenode’s #mediawiki-i18n if you need more information. See translatewiki.net for the currently largest implementation of the Translate extension. We have large goals, but very little PHP development capacity. Anyone willing to work on a generic MediaWiki-based localisation platform, is welcome to submit patches or become a MediaWiki committer if you want to be even more active.
I’m currently at the Google Summer of Code Mentor Summit (for another 5 more hours) and I have spoken with a PHP guy about translating the PHP documentation in about the same way. I do not know if the current svn base of the PHP documentation is about the same as the KDE documentation, but I think it would be a good idea to see if KDE, PHP and translatewiki.net can together set up a proper proof of concept and workflow.
Current feature list and bug list for Translate is kept at my user page on translatewiki.net.
@Siebrand: Thank you. That is a very helpful offer. I’m sure we shall be talking soon.