Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.lang.forth > #28104 > unrolled thread
| Started by | Richard Owlett <rowlett@pcnetinc.com> |
|---|---|
| First post | 2014-01-25 11:52 -0600 |
| Last post | 2014-01-28 10:40 +0100 |
| Articles | 6 — 6 participants |
Back to article view | Back to comp.lang.forth
[OT?] Would journalists be preffered documenters? Richard Owlett <rowlett@pcnetinc.com> - 2014-01-25 11:52 -0600
Re: [OT?] Would journalists be preffered documenters? Paul E Bennett <Paul_E.Bennett@topmail.co.uk> - 2014-01-26 10:30 +0000
Re: [OT?] Would journalists be preffered documenters? trebor.english@gmail.com - 2014-01-26 10:40 -0800
Re: [OT?] Would journalists be preffered documenters? "Elizabeth D. Rather" <erather@forth.com> - 2014-01-26 12:47 -1000
Re: [OT?] Would journalists be preffered documenters? anton@mips.complang.tuwien.ac.at (Anton Ertl) - 2014-01-27 14:51 +0000
Re: [OT?] Would journalists be preffered documenters? Matthias Koch <matthias.koch@hot.uni-hannover.de> - 2014-01-28 10:40 +0100
| From | Richard Owlett <rowlett@pcnetinc.com> |
|---|---|
| Date | 2014-01-25 11:52 -0600 |
| Subject | [OT?] Would journalists be preffered documenters? |
| Message-ID | <4LKdne1GpOo0U3nPnZ2dnUVZ_hednZ2d@supernews.com> |
Documentation is a recurring topic on this group On a Linux distribution specific list I've been unsuccessfully asking questions. No matter how I phrase the questions, I keep get answers to "HOW". Back in the 50's, I was taught that there were also 5 W's: Who What When Where Why I think quality/useful documentation should cover at least What When Why Anyone know of a documentation project with that POV? Thank you for your time. If any think off-list response is best, y address is valid - if well filtered. Thank you for your time.
[toc] | [next] | [standalone]
| From | Paul E Bennett <Paul_E.Bennett@topmail.co.uk> |
|---|---|
| Date | 2014-01-26 10:30 +0000 |
| Message-ID | <bkk6erF8v5sU1@mid.individual.net> |
| In reply to | #28104 |
Richard Owlett wrote: > Documentation is a recurring topic on this group > > On a Linux distribution specific list I've been unsuccessfully > asking questions. > No matter how I phrase the questions, I keep get answers to "HOW". > > Back in the 50's, I was taught that there were also 5 W's: > Who What When Where Why > > I think quality/useful documentation should cover at least > What When Why > > Anyone know of a documentation project with that POV? > > Thank you for your time. > If any think off-list response is best, y address is valid - if > well filtered. > > Thank you for your time. Only all the major projects I have dealt with Richard. Then, my industry sectors, being mainly in the Safety Critical domains, has expended time and money to getting the documentation right. For the task the companies concerned usually hired Tech Authors. I thought I rote fairly good documentation myself but the best Tech Authors could make it seem like you were coming to the system afresh when you read their stuff (based on what I and other team mebers had written). -- ******************************************************************** Paul E. Bennett IEng MIET.....<email://Paul_E.Bennett@topmail.co.uk> Forth based HIDECS Consultancy.............<http://www.hidecs.co.uk> Mob: +44 (0)7811-639972 Tel: +44 (0)1235-510979 Going Forth Safely ..... EBA. www.electric-boat-association.org.uk.. ********************************************************************
[toc] | [prev] | [next] | [standalone]
| From | trebor.english@gmail.com |
|---|---|
| Date | 2014-01-26 10:40 -0800 |
| Message-ID | <5f006bb8-e2f4-45bf-ad44-125e895fbce9@googlegroups.com> |
| In reply to | #28104 |
On Saturday, January 25, 2014 12:52:34 PM UTC-5, Richard Owlett wrote: > Documentation is a recurring topic on this group > Where I worked in 2000 - 2001 the technical writing group was only two people. I brought them a copy of a page that, as I recall, was a list of about 10 rules for journalists. The two rules I found most memorable are: - Remember to never split an infinitive. - Eschew obfuscation. They found the list fascinating and entertaining. Real journalists might have been exposed to those concepts previously. Librarians are another group with language experience who might be useful in the generation of documentation. At least they would have skill in proof reading.
[toc] | [prev] | [next] | [standalone]
| From | "Elizabeth D. Rather" <erather@forth.com> |
|---|---|
| Date | 2014-01-26 12:47 -1000 |
| Message-ID | <CZydncbrH_boDXjPnZ2dnUVZ_radnZ2d@supernews.com> |
| In reply to | #28104 |
On 1/25/14 7:52 AM, Richard Owlett wrote: > Documentation is a recurring topic on this group > > On a Linux distribution specific list I've been unsuccessfully asking > questions. > No matter how I phrase the questions, I keep get answers to "HOW". > > Back in the 50's, I was taught that there were also 5 W's: > Who What When Where Why > > I think quality/useful documentation should cover at least > What When Why > > Anyone know of a documentation project with that POV? > > Thank you for your time. > If any think off-list response is best, y address is valid - if well > filtered. > > Thank you for your time. If you're looking for the right "background," I would propose teaching, preferably teaching a topic related to the subject of the documentation. Teaching experience helps you understand what questions the reader will have in mind, and what concepts will cause confusion and difficulty. In addition, you'll have the experience of developing ways of communicating that avoid or address the confusion and difficulty. Cheers, Elizabeth -- ================================================== Elizabeth D. Rather (US & Canada) 800-55-FORTH FORTH Inc. +1 310.999.6784 5959 West Century Blvd. Suite 700 Los Angeles, CA 90045 http://www.forth.com "Forth-based products and Services for real-time applications since 1973." ==================================================
[toc] | [prev] | [next] | [standalone]
| From | anton@mips.complang.tuwien.ac.at (Anton Ertl) |
|---|---|
| Date | 2014-01-27 14:51 +0000 |
| Message-ID | <2014Jan27.155155@mips.complang.tuwien.ac.at> |
| In reply to | #28104 |
I guess journalists may learn how to do tech writing, but I don't
think that they would write good documentation without additional
training. Even at a very low level, they learn the wrong skills:
E.g., we learned in school that in good literary style you do not
repeat words; instead, you use synonyms. Journalists tend to follow
that rule to comic proportions, occasionally even using synonyms that
make their text (and, worse, the subject that they refer to)
ridiculous. In tech writing this rule is a bad idea, because it tends
to confuse readers.
- anton
--
M. Anton Ertl http://www.complang.tuwien.ac.at/anton/home.html
comp.lang.forth FAQs: http://www.complang.tuwien.ac.at/forth/faq/toc.html
New standard: http://www.forth200x.org/forth200x.html
EuroForth 2013: http://www.euroforth.org/ef13/
[toc] | [prev] | [next] | [standalone]
| From | Matthias Koch <matthias.koch@hot.uni-hannover.de> |
|---|---|
| Date | 2014-01-28 10:40 +0100 |
| Message-ID | <lc7u87$l6f$1@newsserver.rrzn.uni-hannover.de> |
| In reply to | #28104 |
> Back in the 50's, I was taught that there were also 5 W's: > Who What When Where Why > > I think quality/useful documentation should cover at least > What When Why > > Anyone know of a documentation project with that POV? I know a very beautiful example of documentation that follows this guideline, it's in the Philbrick "Applications Manual for Computing Amplifiers for Modeling, Measuring, Manipulating & Much Else". http://www.analog.com/library/analogdialogue/archives/philbrick/computing_amplifiers.html It's the part "Why How When Where" I recommend you to have a look at. http://www.analog.com/library/analogdialogue/archives/philbrick/003-008.pdf I love the design. Matthias
[toc] | [prev] | [standalone]
Back to top | Article view | comp.lang.forth
csiph-web