Documentation email list?

[sparkes]

John Levin wrote:
> 
> On 1 Oct 2004, at 14:08, David wrote:
> 

> Of course, this doesn't mean there shouldn't be a plan, priorities, and 
> a set format (docbook?)

plan?,
step one. conqueuer world,
step two. decide what to do with it

;-)

docbook is a good standard to use.  It's a little tricky to get used to 
but there is plenty of support around and it can be transformed into 
lots of useful filetypes.  Help on docbook is available on #debian (and 
probably #ubuntu now) if you can handle the razor like wit of the 
residents ;-) sometimes they don't come across as the most friendly 
bunch but there are very helpful if you rtfm and are still struggling.


<snip>

> 
> 
>> The biggest failing of computer doco is either:
>>
>> a) incompleteness.. several steps left out because you are supposed to
>> just *know*, and
>>
>> b) too cryptic, on the assumption that of course you know how to do it,
>> why else would you be looking up docos, and of course you know what every
>> term and abreviation means because.. well... you just do!
>>
> 
> I'd add: outdated - not revised as often as the code
> and: difficult to locate - there's some excellent material spread around 
> the net, yet not bundled in with the app, or referenced from the home page.

the starting point IMHO should be the ex-Progeny Users Guide (now Debian 
  Users Guide) it's a fantastic start and a lot of stuff can be returned 
to the debian projects version of the doc.

It is currently slightly incomplete (with relation to ubuntu), it's not 
too crytic (and was developed to fill the same gap as ubuntu now) but it 
is outdated (with relation to ubuntu and the new debian installer)

> 
> (I hereby propose that a HOWTO: google should be a top priority.)

and a clear link to http://www.catb.org/~esr/faqs/smart-questions.html 
wouldn't go astray either ;-)  Lots of duplicated traffic over the last 
couple of weeks that google/asking the *right* question would have 
fixed.  But you can't have everything, where would you put it? ;-)


> 
>> One last thought. Any documentation project MUST be searchable. I'm 
>> amazed
>> to find that the gnome desktop help isn't searchable.
>>
> 
> Seconded.

isn't that googles job ;-) or greps ;-)

although I take the point on offline docs should be searchable by 
everyone many users are connected to the internet these days so this is 
becoming less of a problem.

> 
> John
> 
> 
sparkes

-- 
t:07005 968 999 f:07005 968 888
   http://www.swishdesign.com
    http://blog.westmids.biz
     http://www.fabhost.net
      http://lugradio.org