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

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

[Alec Warner]

First off, this is not a discussion on why XML sucks, or why we shouldn't
be using XML or anything like that.  This is not a discussion about what
we should be using instead of XML.  This is a discussion about using XML
for our webpages.

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.

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.

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?

Thanks,

-Alec

-- 
gentoo-dev@gentoo.org mailing list

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 1183 bytes --]

On Mon, 2007-03-26 at 08:05 -0700, Alec Warner wrote:
> 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?

- No
- http://www.gentoo.org/doc/en/xml-guide.xml
- No
- No, other than asking Xavier... ;]
- No
- Yes, we could, but we also don't do much "training" of any of our
people for many of our jobs and expect people to be self-motivated and
capable of self-teaching.  While we could try teaching people GuideXML,
I'm not sure if it would be a valuable expenditure of time.  That is,
unless you're volunteering to teach it.

-- 
Chris Gianelloni
Release Engineering Strategic Lead
Alpha/AMD64/x86 Architecture Teams
Games Developer/Council Member/Foundation Trustee
Gentoo Foundation

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[William L. Thomson Jr.]

[-- Attachment #1: Type: text/plain, Size: 760 bytes --]

On Mon, 2007-03-26 at 08:05 -0700, Alec Warner wrote:
> my basic question is do you as a
> developer find writing web pages to be confusing or difficult?

As one who does a fair amount of web development myself. I rather like
the guidexml formatted docs. Writing them is not a big deal at all.

>   Do you find that
> you bump up against restrictions in the DTD or other problems that prevent
> you from expressing yourself properly?

Haven't felt limited or restricted on anything yet. ;)

>   Do you have any idea how to
> actually go about extending GuideXML (or the other XML's we provide)  Have
> you ever tried?

No clue on extension, and no I have not tried. Haven't had the need just
yet.

-- 
William L. Thomson Jr.
Gentoo/Java

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 1367 bytes --]

On Monday 26 March 2007, William L. Thomson Jr. wrote:
> On Mon, 2007-03-26 at 08:05 -0700, Alec Warner wrote:
> > my basic question is do you as a
> > developer find writing web pages to be confusing or difficult?
>
> As one who does a fair amount of web development myself. I rather like
> the guidexml formatted docs. Writing them is not a big deal at all.
>
> >   Do you find that
> > you bump up against restrictions in the DTD or other problems that
> > prevent you from expressing yourself properly?
>
> Haven't felt limited or restricted on anything yet. ;)
>
> >   Do you have any idea how to
> > actually go about extending GuideXML (or the other XML's we provide) 
> > Have you ever tried?
>
> No clue on extension, and no I have not tried. Haven't had the need just
> yet.

As author of the projectxml I can say that extension is not trivial 
(projectxml is somewhat an extension of guidexml). The main problem is that 
the documents must remain compliant to the DTD of the format. Extending as 
such is nontrivial. The way projectxml does it is accepting all the relevant 
guidexml tags, just copy those over and then run the guidexml stylesheet over 
the result (which then also includes the project specific stuff).

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Kevin F. Quinn]

[-- Attachment #1: Type: text/plain, Size: 1466 bytes --]

On Mon, 26 Mar 2007 08:05:58 -0700 (PDT)
"Alec Warner" <antarus@gentoo.org> wrote:

> do you as a developer find writing web pages to be confusing or
> difficult?

No.

> Is there not a good tutorial for learning our webpage XML syntax?

For my use, I've found the available docs sufficient.

> Do you find that you bump up against restrictions in the DTD or other
> problems that prevent you from expressing yourself properly?

No.  I do try to keep things simple, which may be why.

> Do you have any idea how to actually go about extending GuideXML
> (or the other XML's we provide)  Have you ever tried?

No and no - I've never had the need.

> Could we improve training with regards to any of this?

Do we really expect people to hack around with the DTDs?  I thought the
whole point is that you stick to the stuff provided by GuideXML.  We're
not writing fancy interactive websites - we're just writing some docs.

All that said, I've only ever written single-page docs.  I don't _like_
GuideXML, but have no inclination to do anything differently for
Gentoo website stuff, and it's sufficient for the stuff I've used it
for.

I wouldn't want to write anything sizable in XML, as the markup just
gets in the way, much like many other markup languages (LaTeX, GROFF
etc).  Docutils' RST (reStructuredText) is much better in this regard;
its markup is much less intrusive than anything else I've used.

-- 
Kevin F. Quinn

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Mike Bonar]

-----Original Message-----
From: Alec Warner [mailto:antarus@gentoo.org] 
Sent: Monday, March 26, 2007 10:06 AM
To: gentoo-dev@lists.gentoo.org
Subject: [gentoo-dev] {Guide,Project,Foo}XML too confusing for many devs?

<snip> 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?

Thanks,

-Alec

-- 
gentoo-dev@gentoo.org mailing list

I have never had a problem writing for GuideXML, but I haven't done a lot of
it.  I found the online guide to be sufficient for getting things working.
I've never had a problem with the DTD or any other obstacle for expressing
content in XML.  As for extending GuideXML, I think we should discuss the
"business driver" behind that idea.

Do we have usage stats on the web sites?  I use the Handbook, package.g.o,
and the forums the most.  Would extensions to GuideXML help improve those
areas?  Should we encourage more content to go into the wiki, expecially
content that is likely to change over a short period of time?

Mike


-- 
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.5.446 / Virus Database: 268.18.18/733 - Release Date: 3/25/2007
11:07 AM


-- 
gentoo-dev@gentoo.org mailing list

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 377 bytes --]

On Mon, 2007-03-26 at 12:01 -0500, Mike Bonar wrote:
> Should we encourage more content to go into the wiki, expecially
> content that is likely to change over a short period of time?

Gentoo has no wiki.

-- 
Chris Gianelloni
Release Engineering Strategic Lead
Alpha/AMD64/x86 Architecture Teams
Games Developer/Council Member/Foundation Trustee
Gentoo Foundation

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Vlastimil Babka]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Chris Gianelloni wrote:
> On Mon, 2007-03-26 at 12:01 -0500, Mike Bonar wrote:
>> Should we encourage more content to go into the wiki, expecially
>> content that is likely to change over a short period of time?
> 
> Gentoo has no wiki.

Not entirely true, project overlays on overlays.g.o can use the wiki on
trac there. And at least we (Java) use it to hash out new stuff (that's
exactly "content that is likely to change over a short period of time"),
that can be later converted to guidexml (FAQs etc).
- --
Vlastimil Babka (Caster)
Gentoo/Java
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGCl+etbrAj05h3oQRAo1wAJ9bwzarFNWHXaNKjdkC9+zFMLzapgCfRyBB
PJltO8soodQZLPE637hqJYM=
=kq4g
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 1378 bytes --]

On Wed, 2007-03-28 at 14:29 +0200, Vlastimil Babka wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Chris Gianelloni wrote:
> > On Mon, 2007-03-26 at 12:01 -0500, Mike Bonar wrote:
> >> Should we encourage more content to go into the wiki, expecially
> >> content that is likely to change over a short period of time?
> > 
> > Gentoo has no wiki.
> 
> Not entirely true, project overlays on overlays.g.o can use the wiki on
> trac there. And at least we (Java) use it to hash out new stuff (that's
> exactly "content that is likely to change over a short period of time"),
> that can be later converted to guidexml (FAQs etc).

Gentoo has no wiki.

The Gentoo/Java project has one.  As do many other projects, including a
couple I'm on, but my previous statement is still true.

At any rate, it's just arguing semantics, where there's no need for it,
and all that does is cause tension, frustration and aggression.  Maybe
if we all were a little less likely to go around trying to prove
everybody else wrong by trying to dissect their wording and instead
focused on technological improvements of our distribution, we'd have
some really kick ass technology being created.

-- 
Chris Gianelloni
Release Engineering Strategic Lead
Alpha/AMD64/x86 Architecture Teams
Games Developer/Council Member/Foundation Trustee
Gentoo Foundation

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Mike Frysinger]

[-- Attachment #1: Type: text/plain, Size: 1233 bytes --]

On Monday 26 March 2007, Alec Warner wrote:
> 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 dont think webpages are old because of the guidexml ... more because people 
simply forget to update them as most of our development happens beyond the 
website space

guidexml does have a small learning curve, but i'd much rather that than 
developers writing their own html because then nothing on our site would look 
cohesive ... as it is actually, i dislike our web sites that dont match the 
basic gentoo.org (*cough* overlays.g.o *cough*)
-mike

[-- Attachment #2: Type: application/pgp-signature, Size: 827 bytes --]

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

["José Luis Rivero (yoswink)"]

Alec Warner escribió:
>
> 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?
> 

Alec, as an alternative and if you don't want to waste your time 
fighting with guideXML or learning how to use it, feel free to send a 
request with data in plain text (and commenting the restrictions you 
found) to gentoo-doc list and maybe you'll find a volunteer who can 
create the page for you.

I'm quite sure that somebody from docs-team (user or dev) will help you 
but, if nobody appears, I will do it.

Once you've created the page, maintain it is quite easy.

Regards.

-- 
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha
-- 
gentoo-dev@gentoo.org mailing list

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

[Dawid Węgliński]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

José Luis Rivero (yoswink) napisał(a):
> Alec Warner escribió:
>>
>> 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?
>>
> 
> Alec, as an alternative and if you don't want to waste your time
> fighting with guideXML or learning how to use it, feel free to send a
> request with data in plain text (and commenting the restrictions you
> found) to gentoo-doc list and maybe you'll find a volunteer who can
> create the page for you.
> 
> I'm quite sure that somebody from docs-team (user or dev) will help you
> but, if nobody appears, I will do it.

I can do it, just let me know on mail / irc (see signature)

> Once you've created the page, maintain it is quite easy.
> 
> Regards.
> 


- --
,-----------------------------.
| Dawid Węgliński             |
| dawid.weglinski@gmail.com   |
| cla @ irc.freenode.net      |
`-----------------------------'
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGCC6M8nXYuEbonNARAp7VAKChEEwmJnraSzGKyxp2qVaSMyCmQQCgqden
EtiB8JB59r1rQ9bWNcvyqZg=
=MdXD
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

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

[Catalin Zamfir Alexandru]

[-- Attachment #1: Type: text/plain, Size: 2586 bytes --]

On Monday 26 March 2007 15:05, Alec Warner wrote:
> First off, this is not a discussion on why XML sucks, or why we shouldn't
> be using XML or anything like that.  This is not a discussion about what
> we should be using instead of XML.  This is a discussion about using XML
> for our webpages.
>
> 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.
>
> 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.
>
> 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?
>
> Thanks,
>
> -Alec

It ain't my business to talk on XML, as I'm not a Gentoo Web Developer, but 
personally I think that XML is one of the easiest SGMLs to learn, in 
comparison to the strict HTML 4.01, MathML or any other.

Plus, XML allows for really good administration for the content and separates 
between code and content. Thus, the content contained in XML can be exported 
to about any other form of representation. Some PHP and XML for rendering 
pages would be just "the bomb" at maintaining a good gentoo.org website. 
That's my opinion ...

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Jakub Moc]

[-- Attachment #1: Type: text/plain, Size: 523 bytes --]

[snip]

Err, where the heck has gone the GuideXML editor project that was part
of last SoC?

(And yeah, I've heard from quite a couple of people that they are not
touching any docs because the GuideXML thing is something they'd rather
avoid like plague).


-- 
Best regards,

 Jakub Moc
 mailto:jakub@gentoo.org
 GPG signature:
 http://subkeys.pgp.net:11371/pks/lookup?op=get&search=0xCEBA3D9E
 Primary key fingerprint: D2D7 933C 9BA1 C95B 2C95  B30F 8717 D5FD CEBA 3D9E

 ... still no signature   ;)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

["José Luis Rivero (yoswink)"]

Jakub Moc escribió:
> [snip]
> 
> Err, where the heck has gone the GuideXML editor project that was part
> of last SoC?
> 

Its name is 'beacon' [1] and is developed by our dev Anant Narayanan who 
probably can give you more info about it.


[1] http://code.kix.in/projects/beacon/

-- 
Jose Luis Rivero <yoswink@gentoo.org>
Gentoo/Doc Gentoo/Alpha
-- 
gentoo-dev@gentoo.org mailing list

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

[Lars Weiler]

[-- Attachment #1: Type: text/plain, Size: 2234 bytes --]

* Alec Warner <antarus@gentoo.org> [07/03/26 08:05 -0700]:
> 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?

I'm one of the few people who like XML.  Probably it's
because I don't have to care for the design and just need to
create content.  It's also the reason why I like LaTeX and
docbook (well, the processing-tools are not that well
developed for docbook yet…).

> Is there not a good tutorial for learning our webpage XML
> syntax?

The XML-files of already written pages ;)


> Do you find that you bump up against restrictions in the
> DTD or other problems that prevent you from expressing
> yourself properly?

There are for sure some difficulties with our DTD,
especially for our project-pages.  Adding a news-entry at
top or putting the elements in a fixed order.

> Do you have any idea how to actually go about extending
> GuideXML (or the other XML's we provide)  Have
> you ever tried?

I work with GuideXML for more than four years now.  I know
the XSLT-process behind, and I know our DTD.  In the past I
did some small extensions, but currently it's very good
developed and from my point of view it is usable.

> Could we improve training with regards to any of this?

See the server-messages when you commit an XML-file.  There
are two guys named who will help when there is an error in
the file during commit ;-)


But back to the question you started your message with: The
outdated project-pages.  My opinion is, that GuideXML is not
the blocker for updating them.  It's more a menpower issue.
Most developers have more fun in keeping their project in a
good state than providing information about the project on a
website.  Furthermore there are many non-native speakers in
the projects who don't want to write websites in a broken
language.  One person per project who watch the project and
collect the FAQs with answers might solve the problem.

Regards, Lars
-- 
Lars Weiler  <pylon@gentoo.org>  +49-171-1963258
Instant Messaging     : pylon@jabber.ccc.de
Gentoo Linux PowerPC  : Strategical Lead and Release Engineer
Gentoo Infrastructure : CVS Administrator

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Chris Gianelloni]

[-- Attachment #1: Type: text/plain, Size: 650 bytes --]

On Mon, 2007-03-26 at 21:46 +0200, Lars Weiler wrote:
> But back to the question you started your message with: The
> outdated project-pages.  My opinion is, that GuideXML is not
> the blocker for updating them.  It's more a menpower issue.

Exactly.

Even projects that I am heavily involved in, do I rarely fix up the web
page.  The Release Engineering page gets updates pretty much when
someone bugs me to do it, and rarely any time else.  I just don't think
about it.

-- 
Chris Gianelloni
Release Engineering Strategic Lead
Alpha/AMD64/x86 Architecture Teams
Games Developer/Council Member/Foundation Trustee
Gentoo Foundation

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 560 bytes --]

On Monday 26 March 2007, Lars Weiler wrote:
> There are for sure some difficulties with our DTD,
> especially for our project-pages.  Adding a news-entry at
> top or putting the elements in a fixed order.

And that is mostly because of the nature of DTD's. As soon as you want to 
require items you have to give order or write out all possible orderings. The 
stylesheet hapilly accepts any ordering, but expects certain things to be 
there.

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Alec Warner]

Thanks for all the replies (and the offers of help, very comforting).  I
will no longer accept the excuse of 'I can't write GuideXML' since we have
an army of volunteers to GuideXMLify stuff for us :)

As such, I don't need to learn (I know enough to get by, and with this
glep index I'll soon know more than I want to most likely).

The intent of my inquiry was really to get a bunch of viewpoints on how
documentation is handled.  We 'train' via a quiz and mentoring developers
to do ebuild tasks but we slack on other things.  Devs don't *need* to
know GuideXML but it would be nice to have a small tutorial (see fex, the
cvs 'tutorial' in the dev docs) so that a new dev could get somewhat
familiar with the whole process of making or editing a page.

I agree it is a manpower issue; we have had Gentoo Status projects in the
past that all pretty much died and part of my thought is to basically
force the project leads to write reports but thats not very nice either ;)

Once again thanks for the input ;)

-Alec

-- 
gentoo-dev@gentoo.org mailing list

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

[Denis Dupeyron]

I find that as long as you read and follow the Gentoo XML Guide,
writing docs is easy and using XML is handy. What I like the most is,
as it was already noted, that I don't have to take care of the layout.

However I have never found anything about writing project pages. Is
there anything out there that I have overlooked ? If not, I'd really
love to see this as a small addition to our XML guide.

Denis.
-- 
gentoo-dev@gentoo.org mailing list

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

[Josh Saddler]

[-- Attachment #1: Type: text/plain, Size: 728 bytes --]

Denis Dupeyron wrote:
> I find that as long as you read and follow the Gentoo XML Guide,
> writing docs is easy and using XML is handy. What I like the most is,
> as it was already noted, that I don't have to take care of the layout.
> 
> However I have never found anything about writing project pages. Is
> there anything out there that I have overlooked ? If not, I'd really
> love to see this as a small addition to our XML guide.

We don't maintain ProjectXML. Not sure who does, if anyone. It's
definitely not the GDP's area of responsibility.

FYI, we do have nice guides on writing GuideXML:

[1] http://www.gentoo.org/doc/en/xml-guide.xml
[2] http://www.gentoo.org/proj/en/gdp/doc/doc-tipsntricks.xml


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 1130 bytes --]

On Wednesday 28 March 2007, Josh Saddler wrote:
> Denis Dupeyron wrote:
> > I find that as long as you read and follow the Gentoo XML Guide,
> > writing docs is easy and using XML is handy. What I like the most is,
> > as it was already noted, that I don't have to take care of the layout.
> >
> > However I have never found anything about writing project pages. Is
> > there anything out there that I have overlooked ? If not, I'd really
> > love to see this as a small addition to our XML guide.
>
> We don't maintain ProjectXML. Not sure who does, if anyone. It's
> definitely not the GDP's area of responsibility.
>
> FYI, we do have nice guides on writing GuideXML:
>
> [1] http://www.gentoo.org/doc/en/xml-guide.xml
> [2] http://www.gentoo.org/proj/en/gdp/doc/doc-tipsntricks.xml


I do (sort of), and it is documented at:

http://www.gentoo.org/proj/en/metastructure/projectxml.xml

Unfortunately I don't know of any page that uses all features, but if you look 
around you can find some.

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Denis Dupeyron]

On 3/28/07, Paul de Vrieze <pauldv@gentoo.org> wrote:
> I do (sort of), and it is documented at:
>
> http://www.gentoo.org/proj/en/metastructure/projectxml.xml
>
> Unfortunately I don't know of any page that uses all features, but if you look
> around you can find some.

Thanks Paul, that's exactly what I was needing. I didn't think of
looking for it in the metastructure pages. I wrongly assumed it was
GDP stuff.

Denis.
-- 
gentoo-dev@gentoo.org mailing list

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

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 715 bytes --]

On Wednesday 28 March 2007, Denis Dupeyron wrote:
> On 3/28/07, Paul de Vrieze <pauldv@gentoo.org> wrote:
> > I do (sort of), and it is documented at:
> >
> > http://www.gentoo.org/proj/en/metastructure/projectxml.xml
> >
> > Unfortunately I don't know of any page that uses all features, but if you
> > look around you can find some.
>
> Thanks Paul, that's exactly what I was needing. I didn't think of
> looking for it in the metastructure pages. I wrongly assumed it was
> GDP stuff.
>
> Denis.

Well, googling for "gentoo projectxml" does get you to the right place 
immediately ;-).

Paul

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@gentoo.org
Homepage: http://www.devrieze.net

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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@gentoo.org mailing list

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

[Vlastimil Babka]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Anant Narayanan wrote:
> 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.

I think it lacks advertisement, IMHO many people just know there was
such project but have no idea if it was completed or what. And having it
online (at least some demo) would help greatly so people can easily try
it out without having to install a webserver, checking out the sources
etc etc.

- --
Vlastimil Babka (Caster)
Gentoo/Java
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGCmCltbrAj05h3oQRAn7EAJ0SgRHTeU339uMt/zkH6EoifOjtdwCgktHH
wo5WimRT1DoUC1FSLEbVWqo=
=01NV
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

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

[Anant Narayanan]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Vlastimil,

> I think it lacks advertisement, IMHO many people just know there was
> such project but have no idea if it was completed or what. And  
> having it
> online (at least some demo) would help greatly so people can easily  
> try
> it out without having to install a webserver, checking out the sources
> etc etc.

Yes, I think that seems to be the problem. I will try and work  
something out over the next few weeks and maybe get a demo up for  
everyone to use. gentoo.ru had one sometime back, but they removed it  
recently.

Cheers,
- --
Anant
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (Darwin)

iD8DBQFGCsWvTon3xA72kU4RAgzMAJ4/k0/UQfbkkB64JRQDbqGVrRyYLgCeJUTW
ApR2IyexpVCAsahv+8ak1YE=
=zgd9
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list