On Sunday 08 January 2006 19:07, Renat Lumpau wrote: > Devwiki i thought of devwiki when I started writing Gentoo/Alt documentation. I then discarded the idea for a series of reason, the first of which is the one already stated by Brian, that the docs results unreadable by non-devs, and also not all devs have currently access to the wiki, sa they need to register and then ask infra for access. The method is for sure unintuitive for devs, and unacceptable to leave the documentation up (if some non-dev want to know how to fix something because it's currently unmaintained in tree and submits a patch, I think it's worth to leave the doc public).
I also don't find GuideXML so bad for documentation, also if developers' eyes only. The GDP style is simple enough as XML to allow using of CVS. The idea of using devwiki for drafts is a bit better, but I tried that, too, when I moved the above noted Gentoo/Alt documentation in GuideXML out of the devwiki. Chris White helped me with the GuideXMLification, as the syntax is different enough to be unpractical to use devwiki for drafting. Also, drafts are usually better when they are visibile to as much eyes as possible, so I'd rather let them visibile to user too. There are some ways that might be practical. The first one is the simplest I can think of: let general documentation like the "how to fix common problems" document to be handled by GDP as developers' documentation when they are finished, and work on them in a special "draft" directory inside /proj/en/ (with no access restrictions) so that they can be handled by many devs at a time. When the document is ready, it's submitted to GDP which will handle the future maintenance. Another way is to provide GuideXML xslt on dev.gentoo.org so that we can put guidexml-formatted pages directly on our public_html before submitting to GDP. The third way is somewhat more complex: provide a standanlone branch, aside of proj and doc, called "devs", where we can commit guidexml documents that aren't strictly referring to a single topic, but rather organized by who's working on them, still under CVS so we have history. There the drafts can be worked on, and then again passed to GDP when they're final. I tried ordering the three ideas by order of flexibility and easyness for infra to enact them, and they are only what I came up after an afternoon spent thinking on it. There might be practical issues with all of them. I don't like the idea of a wiki not for the public thing (I think it would still be limited in write access to devs), because not only it would be yet another tool to learn usage of, but it would be "off style" with the rest of the site. Also, limiting it to devs to write it would lose the main feature of a wiki, so it would be like wasting the load that it would add... I still like the idea of continuing using GuideXML, after have learned to use it it's really practical to me at least. -- Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/ Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE
pgp1kss5nhzpm.pgp
Description: PGP signature
