Re: [gentoo-dev] {Guide,Project,Foo}XML too confusing for many devs?

[Anant Narayanan]

> Many projects have old and nasty webpages.  This has been a problem within
> gentoo since before I arrived and probably has been a problem since we
> started having webpages.  One of the issues I wish to address is whether
> or not writing webpages in XML (Guide or Project or something_else) is
> just too much of a barrier for many people.  I've personally always been
> pretty much a 'copy something that works and edit the bits I need' kind of
> a guy.  There is certainly a large body of work to steal^H^H^H^H^Hcopy
> from.  However when something you are working on doesn't fit inside of
> something that has already been done it becomes very difficult to make it
> 'fit' into our existing XML structure.

I doubt whether any other format for webpages would allow you to copy
stuff directly in. You need to format in any case...

> This forces you to either ask for help from the masters of GuideXML (aka
> the Docs team) or try and figure out how the hell to write the xsl and
> dtd's yourself, or give up.  Personally I think most people end up at the
> latter case (the giving up one).  I know developers that won't even touch
> any webpages at all; I can only assume that they just hate XML long time
> and find the whole issue of writing pages complicated and burdoning.

You don't need to write DTDs or XSLs on your own for anything other than
changing the GuideXML syntax itself or the look of the Gentoo web-pages;
things that not every dev wants to do.

> So this is getting pretty long winded; my basic question is do you as a
> developer find writing web pages to be confusing or difficult?  Is there
> not a good tutorial for learning our webpage XML syntax?  Do you find that
> you bump up against restrictions in the DTD or other problems that prevent
> you from expressing yourself properly?  Do you have any idea how to
> actually go about extending GuideXML (or the other XML's we provide)  Have
> you ever tried?  Could we improve training with regards to any of this?

I guess the point of last year's GuideXML SoC project was to help devs
who didn't find writing GuideXML *cough* exciting *cough* enough. Which
is why I developed Beacon [1]. Looks like the project hasn't been as
successful as I would have liked within Gentoo (although other projects
[2] are certainly considering using it!). The fault is entirely mine,
and I will strive to improve Beacon to a really usable level, and maybe
convince the Infra team to install a copy on one of our servers for our
devs to use.

Best Regards,
--
Anant

[1] http://code.kix.in/projects/beacon
[2] http://www.php.net/ideas.php (PHP LiveDocs may use Beacon as backend)

-- 
gentoo-dev@g.o mailing list