[kde-guidelines] The principle of guidelines.kde.org -- one step further

[Lauri Watts]

On Tuesday 28 September 2004 18.12, Frans Englich wrote:
> On Tuesday 28 September 2004 04:08, Aaron J. Seigo wrote:
> > On Saturday 25 September 2004 10:07, Frans Englich wrote:
> > > What do people think?
> >
> > this is a vision that i can get behind. i'd still like to commit to
> > www/areas/guidelines for now since that's already set up and lets us put
> > a few drafts out before putting it elsewhere

Assuming I understood correctly (leave developer.k.o where it is, create 
guidelines, and then work on moving the developer.k.o site into the 
areas/developer, in a coherent and managed structure, with "docbook inside" 
and then eventually grouping all developer information there - did I 
understand that right?)

What Aaron said.

I've very often said that developer.kde.org pretty much needs to be taken out 
and shot though.   There's so much disorganised content there, and it's very 
difficult to find any of it. 

In fact, I'm willing to donate a server space to work on a rebuild.  

First though, I need to go right now and finish up draft framework so that we 
have something for Aaron to look at (and maybe commit

(boring technical talk from here on in)

The devil is in the details, but the details don't need to be set in stone 
right now.  I'm not in love with cocoon, specifically - I don't see it 
solving anything that xsltproc and a cronned make job with some creative 
stylesheets can't solve.  I could be biased here, but my experiences with 
cocoon just haven't been very pretty (and that sun resolver stuff is just 
nasty nasty evil to work with), while I have seen websites bigger than ours 
that build themselves other ways.    

I do dislike too much dynamism in a site that is inherently quite static - 
there are many pages on developer.k.o that in reality don't and won't change 
from year to year.  Right now the problem is that you can't *find* the 
content, not that it's changing too fast to keep up with.    

So long as all the necessary files are created on a regular basis, a cron job 
to run an update on any files that got a cvs checkin would minimise the load.  
Note that docs.kde.org does *not* run this way (it runs the entire make docs 
script on the entire docs repository, for mainly historic reasons) and it can 
totally bring the webserver to it's knees. Since it's the same webserver as 
developer.k.o, I can take a guess how well it's admins will like us loading 
it up with more stuff.  (Can you say "not very much?")  Anyway, I'm not just 
guessing on the kind of load this type of work will generate, unfortunately, 
it's enormous.  XSLT processing, no matter what the processor, is highly 
intensive, doing as little as possible of it, and only when required is a 
good goal for a webserver admin.

The FreeBSD Doc's (and the rest of FreeBSD's site) are sort of 
semi-static/semi-dynamic - they are XML built, and created from an XSLT 
transform.  Much of it is docbook backed, and those parts generate chunked up 
html, "all in one" html, pdf, ps, rtf, and even pdb files to read on your 
palm pilot.  They don't do it dynamically every time you click a link, but 
they do run every few hours, (and could easily be taught to only regenerate 
docs that have changed.)    They do it using the infamously 
just-about-as-hard-to-work-with-as-sun-resolver Jade, but we don't have to. 

Finally there's also the advantage that a typo in say, a stylesheet, or an 
inadvertantly invalid doc, won't make something inaccessible, since the 
previous iteration is still there.

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.kde.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-guidelines/attachments/20040928/a870a8af/attachment.pgp