You are not logged in.

#1 2005-01-14 08:56:49

cactus
Taco Eater
From: t͈̫̹ͨa͖͕͎̱͈ͨ͆ć̥̖̝o̫̫̼s͈̭̱̞͍̃!̰
Registered: 2004-05-25
Posts: 4,615
Website

Formal Documentation

A few questions...

I am just curious why there isn't more documentation at:
http://www.archlinux.org/docs/en/

Is documentation not being accepted from users?
Are users not contributing?
Is the use of XHTML a barrier for people?

Also:
I was wondering about the use of XHTML for documentation format, and did a forum search of all things... wink
It seems that Latex was used at one point, but a simple XHTML template was adopted for ease of use. I am curious about how that decision looks today to those that deal with the documentation. Is maintaining it easier/harder than before?

I ask because I have personal documentation in various formats: Docbook, html, plaintext, OOo, pdf, etc. Docbook is a pain to use (at least from my point of view), but it exports to other formats nicely. I am going to take a stab at learning Latex in the next couple of weeks, so I will likely have another format laying around.

I am sure others have similar troubles with their documentation, and I was curious what the devs have learned over the course of the last year or so about the issue.


"Be conservative in what you send; be liberal in what you accept." -- Postel's Law
"tacos" -- Cactus' Law
"t̥͍͎̪̪͗a̴̻̩͈͚ͨc̠o̩̙͈ͫͅs͙͎̙͊ ͔͇̫̜t͎̳̀a̜̞̗ͩc̗͍͚o̲̯̿s̖̣̤̙͌ ̖̜̈ț̰̫͓ạ̪͖̳c̲͎͕̰̯̃̈o͉ͅs̪ͪ ̜̻̖̜͕" -- -̖͚̫̙̓-̺̠͇ͤ̃ ̜̪̜ͯZ͔̗̭̞ͪA̝͈̙͖̩L͉̠̺͓G̙̞̦͖O̳̗͍

Offline

#2 2005-01-16 19:02:12

Xentac
Forum Fellow
From: Victoria, BC
Registered: 2003-01-17
Posts: 1,797
Website

Re: Formal Documentation

There isn't more official documentation because all of the user contributed stuff is in the wiki.


I have discovered that all of mans unhappiness derives from only one source, not being able to sit quietly in a room
- Blaise Pascal

Offline

#3 2005-01-16 19:43:30

cactus
Taco Eater
From: t͈̫̹ͨa͖͕͎̱͈ͨ͆ć̥̖̝o̫̫̼s͈̭̱̞͍̃!̰
Registered: 2004-05-25
Posts: 4,615
Website

Re: Formal Documentation

ahhh...
Do you view this as good, or bad?
Just curious.


"Be conservative in what you send; be liberal in what you accept." -- Postel's Law
"tacos" -- Cactus' Law
"t̥͍͎̪̪͗a̴̻̩͈͚ͨc̠o̩̙͈ͫͅs͙͎̙͊ ͔͇̫̜t͎̳̀a̜̞̗ͩc̗͍͚o̲̯̿s̖̣̤̙͌ ̖̜̈ț̰̫͓ạ̪͖̳c̲͎͕̰̯̃̈o͉ͅs̪ͪ ̜̻̖̜͕" -- -̖͚̫̙̓-̺̠͇ͤ̃ ̜̪̜ͯZ͔̗̭̞ͪA̝͈̙͖̩L͉̠̺͓G̙̞̦͖O̳̗͍

Offline

#4 2005-01-16 19:58:17

Xentac
Forum Fellow
From: Victoria, BC
Registered: 2003-01-17
Posts: 1,797
Website

Re: Formal Documentation

I think it's better.  As long as people monitor the wiki to make sure the quality of documentation in there is good (and right now, there aren't any official developers looking at it...), it's better to have more people writing docs than less.


I have discovered that all of mans unhappiness derives from only one source, not being able to sit quietly in a room
- Blaise Pascal

Offline

#5 2005-01-16 20:06:31

cactus
Taco Eater
From: t͈̫̹ͨa͖͕͎̱͈ͨ͆ć̥̖̝o̫̫̼s͈̭̱̞͍̃!̰
Registered: 2004-05-25
Posts: 4,615
Website

Re: Formal Documentation

Very true. And, I suppose at some point when a wiki page has been revised to the point of being rather concrete, it could make the transformation into a pretty official doc.


"Be conservative in what you send; be liberal in what you accept." -- Postel's Law
"tacos" -- Cactus' Law
"t̥͍͎̪̪͗a̴̻̩͈͚ͨc̠o̩̙͈ͫͅs͙͎̙͊ ͔͇̫̜t͎̳̀a̜̞̗ͩc̗͍͚o̲̯̿s̖̣̤̙͌ ̖̜̈ț̰̫͓ạ̪͖̳c̲͎͕̰̯̃̈o͉ͅs̪ͪ ̜̻̖̜͕" -- -̖͚̫̙̓-̺̠͇ͤ̃ ̜̪̜ͯZ͔̗̭̞ͪA̝͈̙͖̩L͉̠̺͓G̙̞̦͖O̳̗͍

Offline

#6 2005-01-16 22:26:03

Dusty
Schwag Merchant
From: Medicine Hat, Alberta, Canada
Registered: 2004-01-18
Posts: 5,986
Website

Re: Formal Documentation

When I was documenting, Dennis and I made a conscious decision to put most docs in the wiki, except those that are very Arch Linux specific, or that should only be done in a specific way (installation, for example).

The reason is, the wiki is easy to maintain. If a user finds an error, he fixes it, rather than pointing it to the official documentors who have to fix it; this takes more time and effort for all involved.

Plus, in my experience, most users knew more about the topic than I do. I found all I had to do was correct peoples' English... I can do that. wink

Dusty

Offline

#7 2005-01-16 23:43:03

cactus
Taco Eater
From: t͈̫̹ͨa͖͕͎̱͈ͨ͆ć̥̖̝o̫̫̼s͈̭̱̞͍̃!̰
Registered: 2004-05-25
Posts: 4,615
Website

Re: Formal Documentation

hmm..interesting..


"Be conservative in what you send; be liberal in what you accept." -- Postel's Law
"tacos" -- Cactus' Law
"t̥͍͎̪̪͗a̴̻̩͈͚ͨc̠o̩̙͈ͫͅs͙͎̙͊ ͔͇̫̜t͎̳̀a̜̞̗ͩc̗͍͚o̲̯̿s̖̣̤̙͌ ̖̜̈ț̰̫͓ạ̪͖̳c̲͎͕̰̯̃̈o͉ͅs̪ͪ ̜̻̖̜͕" -- -̖͚̫̙̓-̺̠͇ͤ̃ ̜̪̜ͯZ͔̗̭̞ͪA̝͈̙͖̩L͉̠̺͓G̙̞̦͖O̳̗͍

Offline

Board footer

Powered by FluxBB