Pat self on back

I was looking at webcvs the other day and found out that the new User Guide was first added to CVS about 5 months ago, and it already has 23,000 words (according to 'wc -w'), and makes over 100 pages in PDF. So here's a pat on the back to everyone who's helped - thanks muchly. And don't forget the competition: there are still a few days to get your entry in :-)

Documentation with Style(sheets)

Played around with the DocBook->HTML stylesheets and their many parameters. I managed to turn off the messy inline CSS that's been in the HTML output since (I assume) forever, and get a much more manageable table of contents for the user guide. Here's a super-mini HOWTO on customizing your KDE documentation:

1. Create a file with the following content:
   

   
   <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   
                   version='1.0'>
   
   
   
     <xsl:import href="KDEDIR/share/apps/ksgmltools2/customization/kde-chunk.xsl"/>
   
   
   
   </xsl:stylesheet>
   
   

   
   but replace KDEDIR with your own $KDEDIR. Save it as, say, mystyle.xsl


2. Take a look at The DocBook Parameter Reference (from where I for the example stylesheet above), choose a parameter you like the look of, and add an appropriate <xsl:param> line below <xsl:import>. A neat one to play around with would be html.stylesheet: you can change the CSS stylesheet used by the output HTML to one of your own devising.


3. Repeat step 2 for as many paramters as you like


4. Run "meinproc --stylesheet /path/to/mystyle.xsl index.docbook" in a directory containing some KDE documentation, and view the resulting HTML

I think you can also do this in a more automatic way, and on a per-document basis, using processing instructions like <?dbhtml html.stylesheet="foo.css"?>, but I haven't tried it yet.

Meanwhile, I have to go back to being eaten alive by every biting insect in Cardiff...

Win win win!

For those of you who don't read the dot, or just missed the story in the rash of posts in the last few days, we're running a competition. All you have to do to be in with a chance of winning some cool O'Reilly gear is write a page - just one page - for the new KDE User Guide. The competition's open to all, and you don't need to know DocBook - just submit your entry in plain text. The dot story has all the other details.

Taking off my promotional hat for a moment, I'll mention the competition we ran at aKademy, which was won by Waldo Bastian. His "KDE for Admins" notes are currently being merged into the User Guide, and look set to be a huge boon for the KDE documentation. Hopefully we'll get lots of entries of that quality for this competition. So get writing!

Glossary, FAQs, scripts

Plenty happening on the docs front at the moment, if a bit slowly:

• I've done some work towards having a KDE-wide glossary. The idea would be to have one big glossary, and allow application manuals to include only the entries that they need. There are still some technical problems with this approach, which I should discuss with Lauri, or anyone else who knows.


• The KDE FAQ is making some progress. I've summarized the plans for it on the wiki, and answers for any of those questions (or any other FAQ), are welcome. Thanks to Aaron for already doing so.


• After Carlos Woelz mentioning the visual dictionary, I remembered my old, and not particularly excellent, preferred_forms script. I'm not really sure what to do with it. We have a handful of other scripts for checking various aspects of documentation files, but they're all not-quite-finished, and we haven't got round to it yet. They should make a quite comprehensive suite for ensuring tidiness and consistency across docs in the future.


• I got my hands on Waldo Bastian's prize-winning notes on "KDE for Administrators", and started merging them into the User Guide. I've added DocBook markup to the first part, but it would also benefit from some fleshing out to go from 'notes' to 'documentation'.

Well, as everyone else has pointed out, aKademy was great. I'll add my thanks to all those who were involved in organizing it - hope you've all had a chance to recover now that it's over for another year :-)

I thought I'd start the shameless plugging of docs stuff now. We had a busy week, like everyone else, and made some good links with the rest of the community. Some of the highlights were:

• Discussion with the usability folks about improving KHelpCenter, with some great ideas, and hopefully an opportunity to get some payoff for all the effort we've spent in putting comprehensive markup in all the KDE documentation


• Learning (by experience) that 'pizza peperoni' in German does *not* mean the same as 'pepperoni pizza' in English :-)


• Getting some great ideas from Fabrice Mous about attracting and keeping contributors. We're trying to put them into action now, starting with discussions with the Quality Teams, and a new 'Welcome Pack' for people offering to help with doc writing.

You can find a more comprehensive list at http://wiki.kde.org/tiki-index.php?page=Documentation+Team+Ideas. If you want to help (and we're crying out for new contributors), drop us a line at kde-doc-english@kde.org.

Ana Ng and I are getting old...

Hrm. I suppose now I have a blog too, so I get to join the world and its dog in sharing my random thoughts with anyone bored enough to listen. Don't expect to find much here apart from shameless plugs for things we're doing in the KDE documentation team. Lots of ideas from aKademy, now's the time to put them into action.