Hey guys and ladies :)
I have finally gotten some time to start my help guide for the fedora project. It is nowhere near done yet as i only have one and a half chapters completed with a planned total of eight chapters covering both ends of a request for help and so on.
What i am posting about it a request for feedback on what i have done so far, i would hate to complete it and realize that i did it wrong. Pointers would also be gratefully accepted.
What i have done so far is located at http://mindstorm.ath.cx:8080/fedora-docs/help-guide/help-guide-en/
I am drawing some information in context with permission* from http://www.catb.org/~esr/faqs/smart-questions.html
*permission is to comply with esr's copy policy @ http://www.catb.org/~esr/copying.html
Thanks for any input.
On Sun, 2004-03-28 at 07:42, Aaron Matteson wrote:
What i have done so far is located at http://mindstorm.ath.cx:8080/fedora-docs/help-guide/help-guide-en/
Integrate bits of: http://www.bytebot.net/fedora/getting-help.html
into it
Colin Charles became daring and sent these 0.4K bytes,
On Sun, 2004-03-28 at 07:42, Aaron Matteson wrote:
What i have done so far is located at http://mindstorm.ath.cx:8080/fedora-docs/help-guide/help-guide-en/
Integrate bits of: http://www.bytebot.net/fedora/getting-help.html
into it
Looks good, i see somethings you worded better then i could, mind if i use some of it? I know you already said to use bits of it, just wanted to make sure first. WIll of course aff you to the acknowledgements.
On Sun, 2004-03-28 at 14:55, Aaron Matteson wrote:
What i have done so far is located at http://mindstorm.ath.cx:8080/fedora-docs/help-guide/help-guide-en/
Integrate bits of: http://www.bytebot.net/fedora/getting-help.html
into it
Looks good, i see somethings you worded better then i could, mind if i use some of it? I know you already said to use bits of it, just wanted to make sure first. WIll of course aff you to the acknowledgements.
Yes
On Sat, 27 Mar 2004, Aaron Matteson wrote:
What i am posting about it a request for feedback on what i have done so far, i would hate to complete it and realize that i did it wrong. Pointers would also be gratefully accepted.
Good stuff, its nice and simple. Some feedback:
* A thought: maybe replace 'man' with 'info'. Info documentation is often better maintained than man pages, and if you type 'info' and there's no info page, it'll fall back to using the man page - so users get the best available.
* I'd mention /usr/share/doc/<packagename>-<version>/ as part of your 'Developer Documentation' section.
* 'Developer Documentation' could be taken two ways. Documentation from Developers (which I think you mean) and Documentation *for* Developers. I'd suggest retitling this section to 'Package Documentation' or just 'Documentation'.
Cheers, and thanks for your work.
Mike
--- Mike MacCana mikem@cyber.com.au wrote:
On Sat, 27 Mar 2004, Aaron Matteson wrote:
What i am posting about it a request for feedback on what i have done so far, i would hate to complete it and realize that i did it wrong. Pointers would also be gratefully accepted.
- A thought: maybe replace 'man' with 'info'. Info documentation is often
better maintained than man pages, and if you type 'info' and there's no info page, it'll fall back to using the man page - so users get the best available.
I actually wrote a short article covering the differences between the two a while ago:
http://iocc.com/~joshua/misc/maninfo.html
You have full permission to take anything useful from there, verbatim or otherwise. I'd also recommend 'pinfo' over the standalone 'info' reader. I actually think 'man' would have disappeared by now if 'info' was at all intuitive to use (and all programs had good --help output for quick checking). If you encourage people to use 'info' they'll either give up or eventually find 'pinfo'.
- I'd mention /usr/share/doc/<packagename>-<version>/ as part of
your 'Developer Documentation' section.
Big plus for this one, too.
Also, why not link to ESR's "Smart Questions" itself with ulink?
There are some minor grammatical issues (like captitalizing "I") that I assume you're already planning on fixing. :)
__________________________________ Do you Yahoo!? Yahoo! Finance Tax Center - File online. File on time. http://taxes.yahoo.com/filing.html
Joshua Daniel Franklin became daring and sent these 1.6K bytes,
--- Mike MacCana mikem@cyber.com.au wrote:
On Sat, 27 Mar 2004, Aaron Matteson wrote:
What i am posting about it a request for feedback on what i have done so far, i would hate to complete it and realize that i did it wrong. Pointers would also be gratefully accepted.
- A thought: maybe replace 'man' with 'info'. Info documentation is often
better maintained than man pages, and if you type 'info' and there's no info page, it'll fall back to using the man page - so users get the best available.
I actually wrote a short article covering the differences between the two a while ago:
http://iocc.com/~joshua/misc/maninfo.html
You have full permission to take anything useful from there, verbatim or otherwise. I'd also recommend 'pinfo' over the standalone 'info' reader. I actually think 'man' would have disappeared by now if 'info' was at all intuitive to use (and all programs had good --help output for quick checking). If you encourage people to use 'info' they'll either give up or eventually find 'pinfo'.
Thanks :)
- I'd mention /usr/share/doc/<packagename>-<version>/ as part of
your 'Developer Documentation' section.
Big plus for this one, too.
Also, why not link to ESR's "Smart Questions" itself with ulink?
Had meant to go back and do that but the intention flew the coop.
There are some minor grammatical issues (like captitalizing "I") that I assume you're already planning on fixing. :)
Didn't catch that, thanks :)
Mike MacCana became daring and sent these 1.0K bytes,
On Sat, 27 Mar 2004, Aaron Matteson wrote:
What i am posting about it a request for feedback on what i have done so far, i would hate to complete it and realize that i did it wrong. Pointers would also be gratefully accepted.
Good stuff, its nice and simple. Some feedback:
- A thought: maybe replace 'man' with 'info'. Info documentation is often
better maintained than man pages, and if you type 'info' and there's no info page, it'll fall back to using the man page - so users get the best available.
Good idea, will do.
- I'd mention /usr/share/doc/<packagename>-<version>/ as part of
your 'Developer Documentation' section.
Also a good idea, will get this section in there in a few days when i have a day off.
- 'Developer Documentation' could be taken two ways. Documentation from
Developers (which I think you mean) and Documentation *for* Developers. I'd suggest retitling this section to 'Package Documentation' or just 'Documentation'.
I see, hadn't spotted that. I did indeed mean Docs from the developers. Package Documentation is and does sound a lot more precise.
Cheers, and thanks for your work.
Thanks for the input and all input to come.
On Sun, 28 Mar 2004, Aaron Matteson wrote:
Mike MacCana became daring and sent these 1.0K bytes,
On Sat, 27 Mar 2004, Aaron Matteson wrote:
What i am posting about it a request for feedback on what i have done so far, i would hate to complete it and realize that i did it wrong. Pointers would also be gratefully accepted.
Good stuff, its nice and simple. Some feedback:
- A thought: maybe replace 'man' with 'info'. Info documentation is often
better maintained than man pages, and if you type 'info' and there's no
Only if you are using packages maintained by fsf.
info page, it'll fall back to using the man page - so users get the best available.
But either way you get something that is painful to use at best.
Good idea, will do.
PLEASE do not do this. Info is pure garbage. Pinfo is not much better but at least it is somewhat useful when you are forced to use it.
Tom
docs@lists.stg.fedoraproject.org
-
Aaron Matteson -
Colin Charles -
Joshua Daniel Franklin -
Mike MacCana -
Tom Diehl