Subject:
|
Re: legOS docs - what do people want?
|
Newsgroups:
|
lugnet.robotics.rcx.legos
|
Date:
|
Sat, 20 Feb 1999 00:27:44 GMT
|
Viewed:
|
1192 times
|
| |
|
|
In lugnet.robotics.rcx.legos, emddjf@chron.com (Dwayne Jacques Fontenot)
writes:
> I am a logOS documentation volunteer, and I am curious as to what type of
> documentation the user community would like to see.
>
> What level of detail is required?
>
> What standard format should be used?
>
> How about usage examples of the various legOS features/functions?
>
> How should the docs be organized, stratified, prioritized?
>
> Let's discuss.
I think it would be coolest (and most helpful) if the docs were in a super-
portable format, either PDF or, heck, just darn plain old HTML.
HTML would be great because it could easily go on the CD-ROM (if there is one)
for Jonathan's O'Reilly book as well as Markus's website and also into the
standard legOS tarball distribution for offline reading and printing hardcopy.
Certainly, proprietary formats like Windows help files would be least useful,
unless they were automatically generated from a master source document (SGML or
HTML maybe).
I'd think the data structure and function cross-reference pages generated by
Doxygen would certainly be useful too in a downloadable offline form.
I'd like (personally) to see a short tutorial with a couple examples (maybe
just a couple quick canned demos) and a high-level overview with rationale
and features and something to help people decide if it's something they really
want to get into. Maybe something comparing it to the standard RCX firmware
and why it's better for serious geek-types.
But examples will probably be plentiful, and focusing on the API documentation
(completeness, correctness, etc.) may be the only thing that truly matters.
--Todd
|
|
Message has 3 Replies:
 | | Re: legOS docs - what do people want?
|
| (...) I'd vote for PDF over HTML. For one thing, a PDF document will be considerably smaller in size than an equivalent HTML document. HTML also has the less-than desirable characteristic (in my opinion) of "fragmenting" a hypertext document across (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
| | | Re: legOS docs - what do people want?
|
| (...) really good (...) I wholeheartedly agree! I've downloaded and installed the egcs binaries but could never get LegOS to compile because of my path environment as well as numerous other issues. I also concur that PDF would be a more desirable (...) (26 years ago, 20-Feb-99, to lugnet.robotics.rcx.legos)
| | | Re: legOS docs - what do people want?
|
| It definitely needs to be portable! (...) please no PDF, it is portable but a pain to read on a screen and I've always thought that it was easier to read api documentation on your computer screen since this is were you work (...) one) Also if you (...) (26 years ago, 21-Feb-99, to lugnet.robotics.rcx.legos)
|
Message is in Reply To:
| | legOS docs - what do people want?
|
| hello, I am a logOS documentation volunteer, and I am curious as to what type of documentation the user community would like to see. What level of detail is required? What standard format should be used? How about usage examples of the various (...) (26 years ago, 19-Feb-99, to lugnet.robotics.rcx.legos)
|
31 Messages in This Thread:
  
- Entire Thread on One Page:
- Nested:
All | Brief | Compact | Dots
Linear:
All | Brief | Compact
This Message and its Replies on One Page:
- Nested:
All | Brief | Compact | Dots
Linear:
All | Brief | Compact
|
|
|
|
