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