Nailing jelly to the penguin / Gentoo documentation project?

churcher

Nailing jelly to the penguin

Complaints of cruelty to penguins >/dev/null

I like phpBB. It's not perfect, and I think we've proven that it isn't terribly scaleable. But it works pretty well.

I like Gentoo's user community. We need to hang on to that sense of immediacy in obtaining support, particularly at the grass-roots level.

I like Gentoo's documentation, such as it is. I'm thinking of things like the install docs, for example. Well-formatted, fairly easy to follow. We need more of that stuff.

Searching forums for answers is great for quick answers, but I don't see it as a long-term solution. It has the following problems:

massive duplication
correct answer often hidden amid incorrect answers
correct answer often scattered across several pages
language used sometimes confusing
lack of structure

On the other hand, it's easier to keep up to date and draws on a large pool of Linux talent, without having to funnel information through a small number of maintainers.

Gentoo documentation project?

Take a look at http://www.php.net , if you haven't already. Their documentation is impressive, and benefits from user contribution without sacrificing structure or easy searching. It's also translated into a number of languages.

I suggest that, whatever else we do with the forum, we begin the task of creating a pool of more formal documentation drawn partly from the forums, partly from user and developer contribution. We could develop it as an experimental project for awhile until it becomes clear whether or not it's useful.

I am not suggesting we get rid of the forums, in case that's not blindingly obvious. I just think we should start to fish some of the better, more reliable information out into a new format.

I think php.net makes a good model for technical documentation, and I'd like to see it adopted for Gentoo docs. I believe that if Gentoo is known for having outstanding documentation, this will build on the strong community base we have already.

And yes, I'm volunteering to coordinate or help coordinate the effort (can't put the idea out there without being prepared to back it up). If the response is favourable, I'll put up a test site and we can start throwing some ideas around.

Some draft goals:

Organised topic hierarchy
Maintain a high level of user-contribution, not just by adding comments but by submitting new articles, HOWTO's, etc.
Strong search facility
Conversion to different document formats

Cheers,

Rich Churcher.

nephros · Posted: Thu Oct 02, 2003 12:27 am Post subject:

I think this is a great idea, if you get this started count me in for some work there.
Might I suggest even making it a Wiki, so that everybody can contribute easily, and corrections/adaptions can be done fast and unbureaucratically?
My hope is that could decrease the redundancy on the forums a little, as this is beginning to get annoying - also it would enhance and extend the excellent "Tips&Tricks" forum here.

That said, what do you think of this little plug I wrote up yesterday?

[EDIT:] fixed speling for "unbureaucratically" which is a monster BTW.
_________________
Please put [SOLVED] in your topic if you are a moron.

churcher · Posted: Thu Oct 02, 2003 12:48 am Post subject:

Yep, the wiki idea had occurred to me as well. Probably restricted access for primary documents, with a user comments section below each, and a submission method for larger docs.

Docbook conversion could be a possibility down the track, but I don't see it as a first-line solution because of the barrier to user submission (fewer people are willing to learn Docbook than they are to, say, learn to type ;-)

)

nephros · Posted: Thu Oct 02, 2003 12:56 am Post subject:

pjp · Posted: Thu Oct 02, 2003 3:12 am Post subject:

We've wanted to get a Gentoo Documentation Project going for some time. Unfortunately, it hasn't happened.

A couple of related threads to catch up on (so as to not rehash old ideas over and over):
Newbies ask the same questions, right?
knowledge base: how-to documents via commandline?

The biggest hurdle is explained here.

If anyone is willing to help solve the hurdle mentioned above, then we can probably get it rolling again. Otherwise, we're just left with ideas, suggestions and comments.
_________________
lolgov. 'cause where we're going, you don't have civil liberties.

In Loving Memory
1787 - 2008

churcher · Posted: Thu Oct 02, 2003 5:22 am Post subject:

Thanks pjp. I have now read the threads you mentioned, along with some associated links. If I may summarise (brutally):

Some Gentoo users would like to see a command-line documentation facility in Gentoo
Some of these believe it would be best if this could be read without an Internet connection, while some feel that Gentoo is essentially pointless without a connection
Suggestions have been made along the lines of a portage-like repository of documentation
Various discussion as to what new Linux users need the most help with

My point was to address the quality of the web documentation and not come up with a Gentoo killer-app for docs. However, now you've got me thinking: is there a way to do both?

At the end of one of those threads, Tasslehoff said he was starting on something, but the last post to that thread was in late July. I've PM'd him, so perhaps he can comment on any progress in this area.

As to people with programming skills and time, I think I qualify (at least in part). I'm also a strong writer (in english, at least) which could prove important.

ian! · Posted: Thu Oct 02, 2003 6:19 am Post subject:

Just want to let you know that I am coding a document editor for Gentoo.

Features:

- webbased; easily edit and write documentation in your webbrowser
- WYSIWYG editor (you can see what the document will look like while editing it)
-"Guide XML" compliant XML will be generated
- will be able to generate PDF files for offline reading
- (could generate every other format...)
- supports revision and version history
- user and groupmanagement
... more to come.

I already posted an announcement on gentoo-doc mailinglist. I finished an early version (alpha3) a few days ago. Development is kind of stuck at the moment (I'm really short of time). The version available is just a proof-of-concept. A complete rewrite will follow.

Regards,
ian!
_________________
"To have a successful open source project, you need to be at least somewhat successful at getting along with people." -- Daniel Robbins

masseya · Posted: Thu Oct 02, 2003 5:15 pm Post subject:

nephros · Posted: Thu Oct 02, 2003 5:40 pm Post subject:

I have not checked how much of this is already covered by the www.gentoo.org docu, or the FAQ, or the tips&tricks, but these are things off my head that again and again are asked on the forums, and could be covered on a suplementary documention site.
A lot of this is already explained somewhere, but people still keep running into these.

booting:
* Grub can't find vmlinuz
* PANIC: cant mount root fs
* /dev/ROOT: no such device

hardware:
* How to enabe UDMA for my harddrive
* How to get my cd burner to work
* How to get my USB thumb drive to work
* How to automount cdroms like windows does
* why can't I mount my audio CD

general dealing with problems:
* my XXX program said something about not finding the mouse so I reinstalled gentoo but...
* HELP ME. X is not working, why?? (n/t)

general information about apps:
* what is a good cd writing program
* which mail client can do XXX
* on windows I used this obscure app that use to do foo, what is an equivalent in linux?

networking:
general network troubleshooting from card driver to DNS to IP masquerading.
How to set up AOL/ADSL/Cable/modem link

(list is completely incomplete.)
_________________
Please put [SOLVED] in your topic if you are a moron.

Redson · Tux's lil' helper Joined: 15 Apr 2003 Posts: 137

I agree that centralizing a lot of documentation needs to be moved from these forums, as we've seen that these forums are splitting at the seems.

I'm not sure I'd be of much help coding, but if you need someone to copy (and streamline) documentation from the forums to a new location, I would be more than willing to help.
_________________
Redson
http://watchred.com/

Tasslehoff · Posted: Thu Oct 02, 2003 8:39 pm Post subject:

my plan was to make a tree and leaf like site where you follow a series of questions which should give some suggestions to the resolution of your problem. progress on it is pretty much non existant. I was still planning the implementation when I ended having to work evenings which was the time I would have been coding.

I am going to be picking up the project again very soon when I wrap up the work I am doing in the evening.

But for this I was not planning a wiki like thing, but more of (once it really gets going) having maintainers for the main documentation but allowing user comments via a form on the bottom of each page.

My main hurdle is coming up with a way to make the branches both infinatly expandable and at the same time be able to intersect. I have ideas on this but have not had the time to give them a shot

churcher · Posted: Thu Oct 02, 2003 9:32 pm Post subject:

Thanks for bringing us up to speed, Tasslehoff.

KickThePenguin · n00b Joined: 04 Oct 2003 Posts: 2

Count me in

I love the idea, and seeing it written up in the elegant way churcher has managed to do is pure inspiration. My coding skills are good enough, and I do have some time to spare (well in the weekends anyways)... and I do think the current system can be very much improved.

Now that we have three coders on it, I think we should fire this project up asap. Others will certainly join when they see we mean business... Has anyone got a webserver to spare?

Hi everyone btw

--Mike

klieber · Posted: Sun Oct 05, 2003 12:25 pm Post subject:

churcher · Posted: Sun Oct 05, 2003 9:26 pm Post subject:

KickThePenguin · n00b Joined: 04 Oct 2003 Posts: 2

Getting somewhere

Status on the webserver churcher?

I can set one up myself, but no sooner than by next weekend I'm afraid

churcher · Posted: Fri Oct 10, 2003 7:34 pm Post subject:

I set up a development wiki with some initial ideas. Will post back once I've finished testing it, probably later today.

churcher · Posted: Fri Oct 10, 2003 8:19 pm Post subject:

http://gdp.eloquentgeek.com/

I'll PM passwords to those who have expressed an interest in contributing.

ian! · Posted: Thu Oct 23, 2003 8:19 am Post subject:

As I promised earlier I started a rewrite of the WYSIWYG-Gentoo-Documentation-Editor.

Go to:
http://213.146.113.231/cgi-bin/gendocedit/index.pl

User: gentoo-forums
Pwd: demo
(Click login-button in upper right corner to login.)

Remember that it's in a early stage. (pre0)

Help needed:
Do you want to contribute to this project?
I'm searching for translators who help localizing the application. If you are willing to contribute please send me an email. (see profile)

ian!
_________________
"To have a successful open source project, you need to be at least somewhat successful at getting along with people." -- Daniel Robbins

ian! · Posted: Fri Oct 24, 2003 10:11 am Post subject:

pre1 released.

Changelog:
- added design elements to the ui
- "review" now works 50% (except save notes)
- auto-focus on login form
- Database: included 'abstract', and 'reviewers notes'
_________________
"To have a successful open source project, you need to be at least somewhat successful at getting along with people." -- Daniel Robbins

pjp · Posted: Fri Oct 24, 2003 4:55 pm Post subject:

Looks like it could be interesting. Are there plans for a search feature?
_________________
lolgov. 'cause where we're going, you don't have civil liberties.

In Loving Memory
1787 - 2008

ian! · Posted: Fri Oct 24, 2003 6:54 pm Post subject:

ian! · Posted: Tue Oct 28, 2003 6:13 pm Post subject:

pre2 released.

Changelog:
- added (a simple) search function (thanks to pjp for that suggestion)

Go to:
http://213.146.113.231/cgi-bin/gendocedit/index.pl

User: gentoo-forums
Pwd: demo
(Click login-button in upper right corner to login.)
_________________
"To have a successful open source project, you need to be at least somewhat successful at getting along with people." -- Daniel Robbins

krusty_ar · Posted: Thu Oct 30, 2003 8:50 pm Post subject:

A litle to late maybe but this seems interesting

http://3d17.org/
_________________
I am Beta, don't expect correct behaviour from me.
Take part of the adopt an unaswered post initiative

ian! · Posted: Fri Oct 31, 2003 8:17 pm Post subject:

pre3 released.

Changelog:
- added ui-design to 'import Guide-XML'
- added 'publish' function
- added 'modify publishing groups' to admin menu
- added 'move up' and 'move down' functions in edit view
- added another 'ok' button to edit view on the left of the selected textelement (requested by jay)
- changed redirect to 'main menu' instead of 'add user' when adding a user was successful (requested by jay)
- added abstract input to 'create new document'
- added auto-focus to inputboxes
- added 'insert link' dialog

Go to:
http://213.146.113.231/cgi-bin/gendocedit/index.pl

User: gentoo-forums
Pwd: demo
(Click login-button in upper right corner to login.)
_________________
"To have a successful open source project, you need to be at least somewhat successful at getting along with people." -- Daniel Robbins