1/9/2006
Gentoo Developer Docs
So the debate began again about creating developer docs. In the past there was an attempt to address this with the Developer Wiki but most of us are probably unaware of that site and it’s problems. Basically the biggest issue is that it’s so tightly locked down it’s nearly useless. Every developer has to request an account and request it of the correct person. I tried and still haven’t gotten an account.
Now in the past I was a supporter of creating a wiki and I still am. My idea is that we create a MediaWiki (I don’t like MoinMoin, sorry) and we give all @gentoo.org addresses access to sign up. It’ll be a quick code hack. If we want to let non-developers have access then we can add them on an individual basis. This allows for faster access, a more communal development model and faster development.
Currently the way to do it is to learn GuideXML and write GuideXML. Emerging some packages to test the GuideXML on your system. Now add a new project to CVS or add your doc to an existing project and commit it. Then you have to wait an hour to see your page show up on Gentoo Web. But it’s not linked from anywhere or searchable. So you somehow have to add links to make it accessible for people. The most common way to do this is to blog about it on Planet Gentoo or write an e-mail to -dev and after a week or so it gets lost in the clutter and it’s gone forever and no one ends up using it. Sure your project can add a link to it but the most important tool is a search feature or an index feature and that’s unavailable. Also the hour delay does not provide a conducive development environment.
That’s why I feel the best approach is to use the Wiki system. Sure some people want to use RST and xmlproc but why reinvent the wheel. Let’s just use a Wiki, it’s simple, easy to use, fast and communal. Detractors to this argument insist on not tying development to a web browser, but let’s face it folks, the end product is a web page. You’re going to have to use a web browser to test it.
Filed under: 4 Responses to “Gentoo Developer Docs”
Leave a Reply
January 9th, 2006 at 3:44 pm
I disagree completely.
1) All docs are searchable:
google.com:blah site:gentoo.org
2) Wiki notation is a pain to learn on its own, and is different enough from “official” docs that using it for docs, and then having the gdp decide to use the doc, would require a total rewrite.
January 9th, 2006 at 4:41 pm
> Emerging some packages to test the GuideXML on your system.
Not required, `xmllint –noout –valid path/to/file` will be enough in case you perform a two-line hack to the /etc/xml/catalog (iirc).
> But it’s not linked from anywhere or searchable
If it is stable enough (ie it won’t disappear after two weeks), ping anyone at #gentoo-doc or submit a bug for docs-team@g.o.
January 9th, 2006 at 11:10 pm
Dan: You’re unfortunately wrong because it takes some time for Google to re-index the Gentoo website. Also this requires leaving Gentoo’s webspace to search, which is kind of counter intuitive.
January 9th, 2006 at 11:12 pm
I realize this, However the new redesign has had talk of adding its own search in anyways. A wiki would be counter productive IMO.