| 1 |
Hi all, |
| 2 |
|
| 3 |
I know an official Gentoo Wiki has been discussed fairly recently, but |
| 4 |
I'd like to throw a different spin out: A wiki for official |
| 5 |
documentation (handbooks, other guides) only. |
| 6 |
|
| 7 |
The wiki would only be editable by Gentoo Devs. For authentication, I'd |
| 8 |
be surprised if there's not an extension that can hook into the existing |
| 9 |
LDAP or whatever databases. |
| 10 |
|
| 11 |
The basic idea is to replace the current documentation with something |
| 12 |
that's much easier to edit. |
| 13 |
|
| 14 |
I recently looked at editing the handbooks to provide patches to update |
| 15 |
them for autobuilds, death of GRP, using "eselect profile" for profile |
| 16 |
management, etc. My problem is I have limited time, and while I have |
| 17 |
tackled GuideXML in the past, it's not something I enjoy doing at all - |
| 18 |
I have to lookup the syntax every time and double check everything. On |
| 19 |
top of that the Handbooks in particular are (at a glance) a maze of |
| 20 |
multiple files pieced together into the finished product (I haven't got |
| 21 |
round to checking whether this maze is mapped out anywhere yet - I had |
| 22 |
multiple things on my todo list at the time and decided to just move on |
| 23 |
to the next item). |
| 24 |
|
| 25 |
On the other hand, I (and I suspect a large number of other people in |
| 26 |
general) use wiki's quite a lot, am familiar with the syntax and find |
| 27 |
them a breeze to edit. In my opinion, it is likely the the official |
| 28 |
documentation would receive more, faster contributions if they were on a |
| 29 |
wiki instead of built using GuideXML. |
| 30 |
|
| 31 |
Providing static copies shouldn't be an issue. There are various |
| 32 |
extensions to provide wiki documents in various formats and I believe |
| 33 |
that, if a system doesn't already exist, one could be built relatively |
| 34 |
easily, to allow automatic generation of static versions. |
| 35 |
|
| 36 |
I think that even if some documentation ends up having to be duplicated |
| 37 |
(eg. between the x86 and amd64 handbooks), the losses through such |
| 38 |
duplication would be outweighed by improved contributions. |
| 39 |
|
| 40 |
I haven't mentioned an engine at all, but I'd suggest mediawiki because |
| 41 |
it's popular, has a lot of extensions already available and the syntax |
| 42 |
is familiar to many. |
| 43 |
|
| 44 |
Thoughts? Concerns? |
| 45 |
|
| 46 |
AllenJB |
Archives