Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
LaTeX for documentations in large projects
114 views
Skip to first unread message
alb
Aug 11, 2014, 5:22:04 PM8/11/14
to
Hi everyone,
today I spent nearly 8 hours chasing the very same content in more than 30
documents in order to bring up to date the entire documentation set. There
must be a more efficient way to structure documents and their content in order
not to duplicate information so wildly.
Single source of truth is a very basic principle that IMO is necessary when
dealing with hundreds of documents throughout the lifecycle of a relatively
large project.
Our systems are not big, though a project can last several years from the
breadboard to the flight unit and it goes through a long list of reviews with
a large set of documents, each with its own individual evolution.
Needless to say many may contribute to the same document and often, due to
scheduling and priorities, we are obliged to minimize the effort to update a
portion of the docs for a specific milestone, with the chance that part of the
information is not correctly propagated throughout the whole set and in less
than one can imagine the whole documentation set is an interwined list of
broken links!
On top of this, our nice friend 'Word' is making our life even more miserable,
forcing us to spend more time than acceptable on stupid formatting issues.
In my previous life I started to build an online documentation system for our
software users, using texinfo. It was pretty neat and simple, with
hierarchical nodes and leaves, which was accessible throughout our computer
network in several format (info, ps, pdf, html). A simple makefile took care
of bringing up to date the last changes and everything was under version
control. That was pretty ok for a limited number (some tens) of people more
confortable with a terminal rather than some flashy GUI.
Using texinfo in this case is certainly not viable given the formatting
prerequisites of our documents, but maybe LaTeX could prove itself a viable
solution. Main issue is to train 98% of the department to use a markup
language instead of MS Word (ouch).
After all this bla-bla finally I come to a more specific question: is there
anyone out there who has considered or is using latex in a collaborative
environment for their product documentation?
Any ideas/suggestions/remarks? I do realize that even if I get the rational
basis to put in place a documentation system based on LaTeX, or anything
similar, I may face irrational obstacles from people who would rather keep
things as they are instead of 'losing' time with a markup language for nerds
only.
Thanks in advance,
Al
--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?
today I spent nearly 8 hours chasing the very same content in more than 30
documents in order to bring up to date the entire documentation set. There
must be a more efficient way to structure documents and their content in order
not to duplicate information so wildly.
Single source of truth is a very basic principle that IMO is necessary when
dealing with hundreds of documents throughout the lifecycle of a relatively
large project.
Our systems are not big, though a project can last several years from the
breadboard to the flight unit and it goes through a long list of reviews with
a large set of documents, each with its own individual evolution.
Needless to say many may contribute to the same document and often, due to
scheduling and priorities, we are obliged to minimize the effort to update a
portion of the docs for a specific milestone, with the chance that part of the
information is not correctly propagated throughout the whole set and in less
than one can imagine the whole documentation set is an interwined list of
broken links!
On top of this, our nice friend 'Word' is making our life even more miserable,
forcing us to spend more time than acceptable on stupid formatting issues.
In my previous life I started to build an online documentation system for our
software users, using texinfo. It was pretty neat and simple, with
hierarchical nodes and leaves, which was accessible throughout our computer
network in several format (info, ps, pdf, html). A simple makefile took care
of bringing up to date the last changes and everything was under version
control. That was pretty ok for a limited number (some tens) of people more
confortable with a terminal rather than some flashy GUI.
Using texinfo in this case is certainly not viable given the formatting
prerequisites of our documents, but maybe LaTeX could prove itself a viable
solution. Main issue is to train 98% of the department to use a markup
language instead of MS Word (ouch).
After all this bla-bla finally I come to a more specific question: is there
anyone out there who has considered or is using latex in a collaborative
environment for their product documentation?
Any ideas/suggestions/remarks? I do realize that even if I get the rational
basis to put in place a documentation system based on LaTeX, or anything
similar, I may face irrational obstacles from people who would rather keep
things as they are instead of 'losing' time with a markup language for nerds
only.
Thanks in advance,
Al
--
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?
Don Y
Aug 11, 2014, 6:01:04 PM8/11/14
to
Hi Al,
On 8/11/2014 2:22 PM, alb wrote:
> today I spent nearly 8 hours chasing the very same content in more than 30
> documents in order to bring up to date the entire documentation set. There
> must be a more efficient way to structure documents and their content in order
> not to duplicate information so wildly.
>
> Single source of truth is a very basic principle that IMO is necessary when
> dealing with hundreds of documents throughout the lifecycle of a relatively
> large project.
> Using texinfo in this case is certainly not viable given the formatting
> prerequisites of our documents, but maybe LaTeX could prove itself a viable
> solution. Main issue is to train 98% of the department to use a markup
-----------------------------^^^^^^^^
MSWord isn't good for anything -- even a one page memorandum! Wait
until you discover that you can't access documents created with
version N-2 or whatever! <frown>
You will probably discover that you need a "Documentation Czar" to
"enforce" policy/consistency in your documents. In reality, this
individual will become the chief grunt -- responsible for FIXING
everyone else's screwups!
GUI's are dangerously seductive. They allow users to focus on the
*appearance* of a document instead of its semantic content. "OK,
that's in italics like it is supposed to be!" (No, italics are used
for several different types of tags in our organization... concentrate
on getting the TAG right, not the appearance of the text rendered for
that tag!)
Long ago, I used Ventura Publisher for my technical documents. But,
abandoned it when Corel bought the product and switched to a
"compiled"/proprietary format for the documents (prior to that,
you could always open the "original document" in a text processor
and apply fancy transformations that the GUI tool would never have
envisioned).
After that, I started using FrameMaker. In some ways, more capable.
In others, more limited. I have recently been contemplating moving
to a full SGML implementation (newer versions of FM support SGML to
some degree so my "conversions" shouldn't be too painful). But,
that's still a fair bit of effort, on my part, and, a fair bit of
*risk* so I have been procrastinating on that decision (and, meanwhile,
accumulating more documents that will eventually have to undergo any
such conversion!)
Beyond the tool(s), by far, the biggest problem will be training
folks for the proper mindset. To treat words, terms, phrases, etc.
as more than just collections of letters/glyphs. IME, this is a
lot tougher nut to crack! :<
Good Luck,
--don
On 8/11/2014 2:22 PM, alb wrote:
> today I spent nearly 8 hours chasing the very same content in more than 30
> documents in order to bring up to date the entire documentation set. There
> must be a more efficient way to structure documents and their content in order
> not to duplicate information so wildly.
>
> Single source of truth is a very basic principle that IMO is necessary when
> dealing with hundreds of documents throughout the lifecycle of a relatively
> large project.
> On top of this, our nice friend 'Word' is making our life even more miserable,
> forcing us to spend more time than acceptable on stupid formatting issues.
> In my previous life I started to build an online documentation system for our
> software users, using texinfo. It was pretty neat and simple, with
> hierarchical nodes and leaves, which was accessible throughout our computer
> network in several format (info, ps, pdf, html). A simple makefile took care
> of bringing up to date the last changes and everything was under version
> control. That was pretty ok for a limited number (some tens) of people more
------------------------------------^^^^^^^^^^^^^^
> forcing us to spend more time than acceptable on stupid formatting issues.
> In my previous life I started to build an online documentation system for our
> software users, using texinfo. It was pretty neat and simple, with
> hierarchical nodes and leaves, which was accessible throughout our computer
> network in several format (info, ps, pdf, html). A simple makefile took care
> of bringing up to date the last changes and everything was under version
> control. That was pretty ok for a limited number (some tens) of people more
> confortable with a terminal rather than some flashy GUI.
---------------------^^^^^^^^
> Using texinfo in this case is certainly not viable given the formatting
> prerequisites of our documents, but maybe LaTeX could prove itself a viable
> solution. Main issue is to train 98% of the department to use a markup
> language instead of MS Word (ouch).
> Any ideas/suggestions/remarks? I do realize that even if I get the rational
> basis to put in place a documentation system based on LaTeX, or anything
> similar, I may face irrational obstacles from people who would rather keep
> things as they are instead of 'losing' time with a markup language for nerds
> only.
I can sympathize with your dilemma. A few (disorganized) comments.
> basis to put in place a documentation system based on LaTeX, or anything
> similar, I may face irrational obstacles from people who would rather keep
> things as they are instead of 'losing' time with a markup language for nerds
> only.
MSWord isn't good for anything -- even a one page memorandum! Wait
until you discover that you can't access documents created with
version N-2 or whatever! <frown>
You will probably discover that you need a "Documentation Czar" to
"enforce" policy/consistency in your documents. In reality, this
individual will become the chief grunt -- responsible for FIXING
everyone else's screwups!
GUI's are dangerously seductive. They allow users to focus on the
*appearance* of a document instead of its semantic content. "OK,
that's in italics like it is supposed to be!" (No, italics are used
for several different types of tags in our organization... concentrate
on getting the TAG right, not the appearance of the text rendered for
that tag!)
Long ago, I used Ventura Publisher for my technical documents. But,
abandoned it when Corel bought the product and switched to a
"compiled"/proprietary format for the documents (prior to that,
you could always open the "original document" in a text processor
and apply fancy transformations that the GUI tool would never have
envisioned).
After that, I started using FrameMaker. In some ways, more capable.
In others, more limited. I have recently been contemplating moving
to a full SGML implementation (newer versions of FM support SGML to
some degree so my "conversions" shouldn't be too painful). But,
that's still a fair bit of effort, on my part, and, a fair bit of
*risk* so I have been procrastinating on that decision (and, meanwhile,
accumulating more documents that will eventually have to undergo any
such conversion!)
Beyond the tool(s), by far, the biggest problem will be training
folks for the proper mindset. To treat words, terms, phrases, etc.
as more than just collections of letters/glyphs. IME, this is a
lot tougher nut to crack! :<
Good Luck,
--don
Tim Wescott
Aug 11, 2014, 6:37:27 PM8/11/14
to
If you do adopt LaTeX, I suggest you use LyX as the authoring tool. It's
not WYSIWYG, which is good from a technical standpoint, but it does let
the author type in an environment that's sort of what-you-see-is-what-you-
meant, and it makes it easy to spin off PDFs. It's what I use for
authoring most of my documents here, unless a customer specifically
insists on word-compatible documents.
But LaTeX isn't going to automatically solve your duplicated-info problem,
any more than Word enforces it: what you need is a process, that everyone
signs up to, that makes ONE source for information golden, and insists
that other documents point to that information source.
It means that someone reading a document needs to have the whole pile and
constantly cross-reference, but that's just kind of life.
--
Tim Wescott
Wescott Design Services
http://www.wescottdesign.com
John Larkin
Aug 11, 2014, 7:45:39 PM8/11/14
to
not plain accii text. It's not bad. You can include logos, pictures,
tables, and colors; during doc development, I use blue to highlight
things that are new this edit. I use CutePDF to turn Word docs into
PDFs for things like user manuals.
Going crazy with styles and tricks and macros can make Word unusable.
Change tracking can be a mess, too.
I use Word 2003 and people with later versions don't seem to have
problems with my docs.
Markup languages seem barbaric these days. I say that having written a
few of them myself.
--
John Larkin Highland Technology, Inc
jlarkin att highlandtechnology dott com
http://www.highlandtechnology.com
Don Y
Aug 11, 2014, 8:09:21 PM8/11/14
to
Hi Tim,
On 8/11/2014 3:37 PM, Tim Wescott wrote:
> But LaTeX isn't going to automatically solve your duplicated-info problem,
> any more than Word enforces it: what you need is a process, that everyone
> signs up to, that makes ONE source for information golden, and insists
> that other documents point to that information source.
As I said, a "Documentation Czar". Getting folks to adopt common
writing conventions for *prose* makes adopting consistent CODING
STANDARDS seem like a piece of cake! <frown>
In my case, the documentation is tightly integrated with the code.
This ensures that the documentation and code remain in "sync"
(because the same "source" is used in each place).
Using semantic tags also facilitates "live" links between the code
and the documentation -- so, interactive help (on demand or as a
result of a thrown error) can directly access the actual documentation
instead of hinting at some "error code", etc.
> It means that someone reading a document needs to have the whole pile and
> constantly cross-reference, but that's just kind of life.
Depending on the markup language in use, the cross references can
be somewhat seemlessly provided -- i.e., "point at" what you want
to reference (vs. having to synthesize a unique name for a reference,
insert that at the target, then refer to it as needed).
With something BEYOND a simple "text interface" (to your documents),
you can provide features that would be virtually impossible to
(completely) implement, maintain and verify.
E.g., my gesture interface uses a single representation for a
specific "gesture" in the documentation (which can be "print",
interactive or "otherwise") as well as in the code. So what the
user is *told* about a specific gesture is what the *code*
actually considers that gesture to be! (think about how you
would document a "check mark" gesture in print, graphically,
to a blind user, etc. -- and, ensure that the documentation
agrees with what the *code* actually checks! How do you advise
the user who is having problems getting the system to correctly
recognize a '0' vs. a 'O', etc.)
On 8/11/2014 3:37 PM, Tim Wescott wrote:
> But LaTeX isn't going to automatically solve your duplicated-info problem,
> any more than Word enforces it: what you need is a process, that everyone
> signs up to, that makes ONE source for information golden, and insists
> that other documents point to that information source.
writing conventions for *prose* makes adopting consistent CODING
STANDARDS seem like a piece of cake! <frown>
In my case, the documentation is tightly integrated with the code.
This ensures that the documentation and code remain in "sync"
(because the same "source" is used in each place).
Using semantic tags also facilitates "live" links between the code
and the documentation -- so, interactive help (on demand or as a
result of a thrown error) can directly access the actual documentation
instead of hinting at some "error code", etc.
> It means that someone reading a document needs to have the whole pile and
> constantly cross-reference, but that's just kind of life.
be somewhat seemlessly provided -- i.e., "point at" what you want
to reference (vs. having to synthesize a unique name for a reference,
insert that at the target, then refer to it as needed).
With something BEYOND a simple "text interface" (to your documents),
you can provide features that would be virtually impossible to
(completely) implement, maintain and verify.
E.g., my gesture interface uses a single representation for a
specific "gesture" in the documentation (which can be "print",
interactive or "otherwise") as well as in the code. So what the
user is *told* about a specific gesture is what the *code*
actually considers that gesture to be! (think about how you
would document a "check mark" gesture in print, graphically,
to a blind user, etc. -- and, ensure that the documentation
agrees with what the *code* actually checks! How do you advise
the user who is having problems getting the system to correctly
recognize a '0' vs. a 'O', etc.)
Clifford Heath
Aug 11, 2014, 8:44:04 PM8/11/14
to
On 12/08/14 07:22, alb wrote:
> After all this bla-bla finally I come to a more specific question: is there
> anyone out there who has considered or is using latex in a collaborative
> environment for their product documentation?
A very large percentage of the open source world is using Markdown
> After all this bla-bla finally I come to a more specific question: is there
> anyone out there who has considered or is using latex in a collaborative
> environment for their product documentation?
for this kind of thing. It's much more approachable than LaTeX for
beginners, and is intended to be easily readable as plain text.
There is a number of dialects. Check the Github variant in particular.
I'd also recommend using a central git repository (I deployed GitlabHQ,
which is like a private Github, and trivial to deploy).
Clifford Heath.
Phil Hobbs
Aug 11, 2014, 10:15:28 PM8/11/14
to
be a devotee of WordPerfect 5.1+ for DOS, which I'd still gladly use
except that publishers don't accept WP anymore.
There are various documentation packages for special purposes, e.g. doc++.
Cheers
Phil Hobbs
Cheers
Phil Hobbs
--
Dr Philip C D Hobbs
Principal Consultant
ElectroOptical Innovations LLC
Optics, Electro-optics, Photonics, Analog Electronics
160 North State Road #203
Briarcliff Manor NY 10510
hobbs at electrooptical dot net
http://electrooptical.net
brucevarley
Aug 11, 2014, 11:39:38 PM8/11/14
to
market-majority stuff, typically M$, and there may not be much that
can be done to change the situation. In that case, the challenge
becomes to get the doc control people to minimise the imposition of
complex templates, which can cause endless hours of grief for
documenters who aren't WP gurus.
While on the topic, another observation... where did the tendency come
from to abandon descriptive titles in favour of totally cryptic
document names? I've had enough of trolling through hundreds of
drawings where you have to open up every one to see what it's about.
gyans...@gmail.com
Aug 11, 2014, 11:43:05 PM8/11/14
to
John Larkin
Aug 11, 2014, 11:48:43 PM8/11/14
to
of code, a physical entity, a document, an assembly, an employee. The schematic,
PCB layout, BOM, bare board, assembled board, are all unrelated numbers.
They tend to lose things.
I hate web sites that make you open a zillion PDFs to see what parts they have.
Then they make the file names meaningless.
--
John Larkin Highland Technology Inc
www.highlandtechnology.com jlarkin at highlandtechnology dot com
Precision electronic instrumentation
Don Y
Aug 12, 2014, 12:00:59 AM8/12/14
to
Hi Bruce,
On 8/11/2014 8:39 PM, Bruce Varley wrote:
> While on the topic, another observation... where did the tendency come
> from to abandon descriptive titles in favour of totally cryptic
> document names? I've had enough of trolling through hundreds of
> drawings where you have to open up every one to see what it's about.
Because most firms have other systems for tracking the names of
documents (whereas *you* are just looking for an individual doc).
What conventions should you adopt for naming documents?
What if the name contains upper and lowercase alphabetics -- and
*your* filesystem doesn't distinguish between cases? (i.e., ReadMe
and README can't coexist in the same namespace).
What about the fondness for colons in names (Google: The Missing
Manual)?
Or, forward/back slashes (User I/O Capabilities)?
Or, questionmarks, etc.?
Or, special characters?
Or, embedded whitespace?
Or, filename length limitations? (try copying "An incredibly long name
for the title of a particularly interesting document, 3rd Edition --
by John Doe, 1988.djvu" to "\An equally\long\folder\designation
\downloads\August\Electronics\..." *on* your "Desktop" -- which is
itself a rather lengthy absolute path)
Computers (and computer systems) are very good at remembering things
(like the name, content, keywords, author, publisher, date, etc.)
and associating them with, e.g., files. It's dealing with the
*informal* systems that individuals have/impose that leads to these
sorts of problems.
[Do you tag the file name with a detailed description of it's
content? Or, do you rely on a search tool to index your documents?
Or, do you just read through documents hoping to stumble on what
you need?]
On 8/11/2014 8:39 PM, Bruce Varley wrote:
> While on the topic, another observation... where did the tendency come
> from to abandon descriptive titles in favour of totally cryptic
> document names? I've had enough of trolling through hundreds of
> drawings where you have to open up every one to see what it's about.
documents (whereas *you* are just looking for an individual doc).
What conventions should you adopt for naming documents?
What if the name contains upper and lowercase alphabetics -- and
*your* filesystem doesn't distinguish between cases? (i.e., ReadMe
and README can't coexist in the same namespace).
What about the fondness for colons in names (Google: The Missing
Manual)?
Or, forward/back slashes (User I/O Capabilities)?
Or, questionmarks, etc.?
Or, special characters?
Or, embedded whitespace?
Or, filename length limitations? (try copying "An incredibly long name
for the title of a particularly interesting document, 3rd Edition --
by John Doe, 1988.djvu" to "\An equally\long\folder\designation
\downloads\August\Electronics\..." *on* your "Desktop" -- which is
itself a rather lengthy absolute path)
Computers (and computer systems) are very good at remembering things
(like the name, content, keywords, author, publisher, date, etc.)
and associating them with, e.g., files. It's dealing with the
*informal* systems that individuals have/impose that leads to these
sorts of problems.
[Do you tag the file name with a detailed description of it's
content? Or, do you rely on a search tool to index your documents?
Or, do you just read through documents hoping to stumble on what
you need?]
Robert Baer
Aug 12, 2014, 12:41:46 AM8/12/14
to
Have a number of R/O "block" phrases / references / pictorials, and
the author splices (hyperlink?) them into their document.
This pool of R/O blocks can grow as needed.
Hell, i have seen a few (unreadable by one that does not know the
"code") documents using up to 30% "shortcut" multi-letter contractions.
Just think of a document written with "shortcuts" similar to that but
the "shortcuts" in this case are the "block" phrases (that is to
increase clarity).
Robert Baer
Aug 12, 2014, 12:46:29 AM8/12/14
to
Don Y
Aug 12, 2014, 1:33:28 AM8/12/14
to
On 8/11/2014 9:41 PM, Robert Baer wrote:
> Tim Wescott wrote:
>> On Mon, 11 Aug 2014 21:22:04 +0000, alb wrote:
>>
>>> today I spent nearly 8 hours chasing the very same content in more than
>>> 30 documents in order to bring up to date the entire documentation set.
>>> There must be a more efficient way to structure documents and their
>>> content in order not to duplicate information so wildly.
>>>
>>> Single source of truth is a very basic principle that IMO is necessary
>>> when dealing with hundreds of documents throughout the lifecycle of a
>>> relatively large project.
> Tim Wescott wrote:
>> On Mon, 11 Aug 2014 21:22:04 +0000, alb wrote:
>>
>>> today I spent nearly 8 hours chasing the very same content in more than
>>> 30 documents in order to bring up to date the entire documentation set.
>>> There must be a more efficient way to structure documents and their
>>> content in order not to duplicate information so wildly.
>>>
>>> Single source of truth is a very basic principle that IMO is necessary
>>> when dealing with hundreds of documents throughout the lifecycle of a
>>> relatively large project.
>>> After all this bla-bla finally I come to a more specific question: is
>>> there anyone out there who has considered or is using latex in a
>>> collaborative environment for their product documentation?
>>>
>>> Any ideas/suggestions/remarks? I do realize that even if I get the
>>> rational basis to put in place a documentation system based on LaTeX, or
>>> anything similar, I may face irrational obstacles from people who would
>>> rather keep things as they are instead of 'losing' time with a markup
>>> language for nerds only.
>>> there anyone out there who has considered or is using latex in a
>>> collaborative environment for their product documentation?
>>>
>>> Any ideas/suggestions/remarks? I do realize that even if I get the
>>> rational basis to put in place a documentation system based on LaTeX, or
>>> anything similar, I may face irrational obstacles from people who would
>>> rather keep things as they are instead of 'losing' time with a markup
>>> language for nerds only.
>> If you do adopt LaTeX, I suggest you use LyX as the authoring tool. It's
>> not WYSIWYG, which is good from a technical standpoint, but it does let
>> the author type in an environment that's sort of
>> what-you-see-is-what-you-
>> meant, and it makes it easy to spin off PDFs. It's what I use for
>> authoring most of my documents here, unless a customer specifically
>> insists on word-compatible documents.
>>
>> But LaTeX isn't going to automatically solve your duplicated-info
>> problem,
>> any more than Word enforces it: what you need is a process, that everyone
>> signs up to, that makes ONE source for information golden, and insists
>> that other documents point to that information source.
>>
>> It means that someone reading a document needs to have the whole pile and
>> constantly cross-reference, but that's just kind of life.
>
> Dumb idea.
> Have a number of R/O "block" phrases / references / pictorials, and the
> author splices (hyperlink?) them into their document.
> This pool of R/O blocks can grow as needed.
> Hell, i have seen a few (unreadable by one that does not know the
> "code") documents using up to 30% "shortcut" multi-letter contractions.
> Just think of a document written with "shortcuts" similar to that but
> the "shortcuts" in this case are the "block" phrases (that is to
> increase clarity).
This doesn't work in the real world.
>> not WYSIWYG, which is good from a technical standpoint, but it does let
>> the author type in an environment that's sort of
>> what-you-see-is-what-you-
>> meant, and it makes it easy to spin off PDFs. It's what I use for
>> authoring most of my documents here, unless a customer specifically
>> insists on word-compatible documents.
>>
>> But LaTeX isn't going to automatically solve your duplicated-info
>> problem,
>> any more than Word enforces it: what you need is a process, that everyone
>> signs up to, that makes ONE source for information golden, and insists
>> that other documents point to that information source.
>>
>> It means that someone reading a document needs to have the whole pile and
>> constantly cross-reference, but that's just kind of life.
>
> Dumb idea.
> Have a number of R/O "block" phrases / references / pictorials, and the
> author splices (hyperlink?) them into their document.
> This pool of R/O blocks can grow as needed.
> Hell, i have seen a few (unreadable by one that does not know the
> "code") documents using up to 30% "shortcut" multi-letter contractions.
> Just think of a document written with "shortcuts" similar to that but
> the "shortcuts" in this case are the "block" phrases (that is to
> increase clarity).
How do you reference them? How/where are they stored? Who
creates/enforces the "system" by which they are used? How do
you track down which "documents" reference which objects?
And, you STILL "need to have the whole pile and constantly
cross-reference" (else the writer can never render the document he is
authoring)
As annoying as GUI/WYSIWYG i/f's can be, there is real value in
being able to call up some *other* document and POINT to the thing
you want to reference. And, let the *tool* sort out how to encode
this reference for you.
For example, I may want to refer to a "section" as:
(See "Troubleshooting tips" on page X-x)
note that the *title* of the section will be filled in by the DTP
tool -- so, if I change it to "When all else fails..." the text
above will be replaced with:
(See "When all else fails..." on page X-x)
everywhere in *my* document that references this -- along with every
other document that similarly references it!
*And*, I may even want to reference my *reference*. I.e., take all
of the above and paste it into documents as an entity. So, if I
change this to reference a *different* section -- perhaps the section
on ADVANCED Diagnostics -- then my *reference* to that section gets
pasted into those places where I reference the reference!
(I find myself using this often with footnotes, etc. So, the one
"Gold Standard" is automatically repeated instead of me having to
remember to consistently express it in the same way each time I
need to use/insert it.)
What's really needed is a programming language for structured
documents... that isn't so intimidating that it precludes large
numbers of people from adopting it comfortably!
David Brown
Aug 12, 2014, 3:53:57 AM8/12/14
to
But I use it at home.
Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
that's the best plan - it gives you better quality typesetting, but it
is hard to use the more advanced features of LaTeX. Personally, I
usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
programming. Another front-end I have heard nice things about is
TeXstudio. Getting a good front-end that users are happy with will make
all the difference here.
LaTeX has several advantages over a word processor, but also some
disadvantages. If you are going to convert to it, you will need someone
(possibly you) who is the "expert" to help with more advanced uses.
1. LaTeX generates much nicer and clearer output. In particular,
documents are consistent - you will never again get inconsistent spacing
or fonts.
2. LaTeX documents are far more amenable to version control. And LaTeX
will never corrupt your source files, unlike certain word processors.
3. Your output is in pdf. Anyone can read the output, on any device,
without worrying about formatting and layout differences on different
computers. The output is more advanced pdf (indexes, cross-links, etc.)
than you can get from MS Word and expensive Adobe products, and is
generated automatically and simply.
4. You can automate it, and use macros. The possibilities here are endless.
5. You can easily include different files and document sections. This
could be an answer to having a "single source of truth" while still
having duplicate information available in different documents. Have
parts of the documentation in separate files, and include those parts
when generating the full set of output documents.
6. If you are working with source code, you can include formatted source
code in your documents, knowing that a "make" will get the latest code.
7. Your customers will have to come back to you when they want a change
to the documentation, because they can't fix it themselves.
If you do stick to a word processor, I recommend LibreOffice over MS
Office. I think it does a better job of encouraging the use of styles
rather than ad-hoc formatting, and it can generate nice pdf documents
(not as nice as with LaTeX, but better than anything you can get with
Word and external pdf converters). And it's cross-platform.
Jasen Betts
Aug 12, 2014, 4:29:53 AM8/12/14
to
On 2014-08-11, alb <al.b...@gmail.com> wrote:
> Hi everyone,
>
> today I spent nearly 8 hours chasing the very same content in more than 30
> documents in order to bring up to date the entire documentation set. There
> must be a more efficient way to structure documents and their content in order
> not to duplicate information so wildly.
>
> Single source of truth is a very basic principle that IMO is necessary when
> dealing with hundreds of documents throughout the lifecycle of a relatively
> large project.
Can you separate the authoritative sources of information and link
> Hi everyone,
>
> today I spent nearly 8 hours chasing the very same content in more than 30
> documents in order to bring up to date the entire documentation set. There
> must be a more efficient way to structure documents and their content in order
> not to duplicate information so wildly.
>
> Single source of truth is a very basic principle that IMO is necessary when
> dealing with hundreds of documents throughout the lifecycle of a relatively
> large project.
them into the main document.
It used to be that word would let you link an external source that
would be referenced when printing the document.
OTOH if formattign is actually important then latex is a win,
but you need a way to reference the autoritative source rather
than duplicating it, myabe lyx can help there, I'm not sure.
lyx/latex being text based are more amenable to merging multiple
simultaneous edits automatically use some sore of revision control
--
umop apisdn
--- news://freenews.netfront.net/ - complaints: ne...@netfront.net ---
alb
Aug 12, 2014, 7:01:19 AM8/12/14
to
Hi Don,
Don Y <th...@is.not.me.com> wrote:
[]
our processes and workflow in order to get a better product in less time and
we pin point how important it is to check, verify, validate each technical
step through the project's lifetime. Aside to that we have to deliver
documentation, indeed a document is a component no less important than any
other component in our system, is a part of it without which you cannot:
A. prove you are doing it right
B. prove you are doing it in time
Then why there's such a large gap in process development applied to
documentation? How can the stakeholders be at the mercy of tools like MS Word?
I personally found that in our customer set of applicable documents there was
some degree of inconsistency (24 requirements out of 2019) which may have been
potentially costly if found at a later stage in the development.
> You will probably discover that you need a "Documentation Czar" to
> "enforce" policy/consistency in your documents. In reality, this
> individual will become the chief grunt -- responsible for FIXING
> everyone else's screwups!
We have 'Czars' [1] around, we call them PAEs (product assurance engineers)
and they tell us what we have screwed up with respect to norms, standards,
versions, ... But it's not enough to guarantee links are not broken.
Relying on multiple eyes is not bad per se, but the quirk of it is that we
tend to silently accept that if a mistake passed a review than is not a
mistake anymore, until two different tables report defferent numbers and the
developer does not know which to pick (neither his/her manager).
> GUI's are dangerously seductive. They allow users to focus on the
> *appearance* of a document instead of its semantic content. "OK,
> that's in italics like it is supposed to be!" (No, italics are used
> for several different types of tags in our organization... concentrate
> on getting the TAG right, not the appearance of the text rendered for
> that tag!)
On top of that, tools like Reqtify, used to trace requirements, may analyze
text based on some formatting styles which *may* look the same even if they
*are* different, so the resulting document may have a set of requirements
which are not 'captured' by the tool and go silently untraced until God knows
when (typically at CDR, where you are ready to launch your flight
production!).
[]
are facing (daily) and an innate inertia to refuse change, too often
considered destabilizing. Some three years ago a revision control system was
introduced (svn) and currently we are still facing 'acceptance' issues.
Another issue I currently see in front of my long revolutionary journey is the
transition phase. Even imagining a ready to deploy documentation system (which
do not have yet), we can only deploy it on newly coming projects, since old
ones are already infected by the MS virus. Engineers who are then working on
several projects will need to continue in two different ways...kinda confusing
if not unsustainable.
The system I have in mind is a hierarchy of units, where information is
*clearly* defined in one single place. Tables (spreadsheets) and diagrams can
live in a common directory, while ad-hoc ones can be in the specific document
folder:
main # handles the data set with Makefiles
├── common # dedicated to all common parts
│  ├── acronyms # needless to explain
│  ├── applicables # list of applicable documents included in all docs
│  ├── diagrams # technical diagrams (dataflow, state machine diagrams, ...)
│  ├── drawings # technical drawings (mechanics, pcbs, schematics)
│  ├── intro # introduction, often present in several docs
│  ├── references # reference documents, with issues and revisions
│  └── tables # budget tables (power, resources, memory structure, ...)
├── lists # list of documents, components, units
├── notes # technical notes (potentially linked to change requests)
├── plans # development plans,
└── specs # subsystem specs
└── ABC-DEF-0120-R # with textual sources as well as tables and diagrams
# unique to this subsystem
...
I forgot to add an 'output' folder which will contain the whole set of
documents produced by the latest build. In an ideal world LaTeX2HTML [2] could
be used to export the whole set of docs in html and allow to browse document
content with a browser instead, where hyperlinks are a much faster way to
reach the information.
Each directory shall have a makefile in order to handle word processing and
bring up to date the current directory. Documents shall have a template (or
class), or potentially a set of templates, in order to provide a uniform and
coherent typeset throughout the project and also between projects.
The structure (just a draft) shall not evolve too much otherwise it becomes
unclear where does a piece of information belong to, but shall take into
account all needs (I just sketched some of the top of my head).
Scripts and macros may facilitate the generation of chapters, especially
tables starting from spreadsheets which are then included into a document.A
Makefile would then be a perfect fit for handling dependencies.
The main idea here is to remove two issues from the current situation:
1. information duplication
2. formatting
While 1. can be addressed with a hierarchical structure, it is certain that
people have to know where information is and what is considered to be sharable
and what is unique to a document. As in programming, is not always clear at
the beginning which subset of your main program will end up in a library
function (especially if you start coding without knowing where you need to
end).
Secondly 2. shall not be a problem of the engineer who's inputing technical
information. He should provide correct data, while data rapresentation shall
be done by the typesetter. Luckily there are a couple of guys in the room who
have the skills to take care about 2.
Don Y <th...@is.not.me.com> wrote:
[]
> I can sympathize with your dilemma. A few (disorganized) comments.
>
> MSWord isn't good for anything -- even a one page memorandum! Wait
> until you discover that you can't access documents created with
> version N-2 or whatever! <frown>
This is something I do not understand. As a company we are trying to improve
>
> MSWord isn't good for anything -- even a one page memorandum! Wait
> until you discover that you can't access documents created with
> version N-2 or whatever! <frown>
our processes and workflow in order to get a better product in less time and
we pin point how important it is to check, verify, validate each technical
step through the project's lifetime. Aside to that we have to deliver
documentation, indeed a document is a component no less important than any
other component in our system, is a part of it without which you cannot:
A. prove you are doing it right
B. prove you are doing it in time
Then why there's such a large gap in process development applied to
documentation? How can the stakeholders be at the mercy of tools like MS Word?
I personally found that in our customer set of applicable documents there was
some degree of inconsistency (24 requirements out of 2019) which may have been
potentially costly if found at a later stage in the development.
> You will probably discover that you need a "Documentation Czar" to
> "enforce" policy/consistency in your documents. In reality, this
> individual will become the chief grunt -- responsible for FIXING
> everyone else's screwups!
and they tell us what we have screwed up with respect to norms, standards,
versions, ... But it's not enough to guarantee links are not broken.
Relying on multiple eyes is not bad per se, but the quirk of it is that we
tend to silently accept that if a mistake passed a review than is not a
mistake anymore, until two different tables report defferent numbers and the
developer does not know which to pick (neither his/her manager).
> GUI's are dangerously seductive. They allow users to focus on the
> *appearance* of a document instead of its semantic content. "OK,
> that's in italics like it is supposed to be!" (No, italics are used
> for several different types of tags in our organization... concentrate
> on getting the TAG right, not the appearance of the text rendered for
> that tag!)
text based on some formatting styles which *may* look the same even if they
*are* different, so the resulting document may have a set of requirements
which are not 'captured' by the tool and go silently untraced until God knows
when (typically at CDR, where you are ready to launch your flight
production!).
[]
> Beyond the tool(s), by far, the biggest problem will be training
> folks for the proper mindset. To treat words, terms, phrases, etc.
> as more than just collections of letters/glyphs. IME, this is a
> lot tougher nut to crack! :<
I totally agree with you. There's a tendency to deny the current problems we
> folks for the proper mindset. To treat words, terms, phrases, etc.
> as more than just collections of letters/glyphs. IME, this is a
> lot tougher nut to crack! :<
are facing (daily) and an innate inertia to refuse change, too often
considered destabilizing. Some three years ago a revision control system was
introduced (svn) and currently we are still facing 'acceptance' issues.
Another issue I currently see in front of my long revolutionary journey is the
transition phase. Even imagining a ready to deploy documentation system (which
do not have yet), we can only deploy it on newly coming projects, since old
ones are already infected by the MS virus. Engineers who are then working on
several projects will need to continue in two different ways...kinda confusing
if not unsustainable.
The system I have in mind is a hierarchy of units, where information is
*clearly* defined in one single place. Tables (spreadsheets) and diagrams can
live in a common directory, while ad-hoc ones can be in the specific document
folder:
main # handles the data set with Makefiles
├── common # dedicated to all common parts
│  ├── acronyms # needless to explain
│  ├── applicables # list of applicable documents included in all docs
│  ├── diagrams # technical diagrams (dataflow, state machine diagrams, ...)
│  ├── drawings # technical drawings (mechanics, pcbs, schematics)
│  ├── intro # introduction, often present in several docs
│  ├── references # reference documents, with issues and revisions
│  └── tables # budget tables (power, resources, memory structure, ...)
├── lists # list of documents, components, units
├── notes # technical notes (potentially linked to change requests)
├── plans # development plans,
└── specs # subsystem specs
└── ABC-DEF-0120-R # with textual sources as well as tables and diagrams
# unique to this subsystem
...
I forgot to add an 'output' folder which will contain the whole set of
documents produced by the latest build. In an ideal world LaTeX2HTML [2] could
be used to export the whole set of docs in html and allow to browse document
content with a browser instead, where hyperlinks are a much faster way to
reach the information.
Each directory shall have a makefile in order to handle word processing and
bring up to date the current directory. Documents shall have a template (or
class), or potentially a set of templates, in order to provide a uniform and
coherent typeset throughout the project and also between projects.
The structure (just a draft) shall not evolve too much otherwise it becomes
unclear where does a piece of information belong to, but shall take into
account all needs (I just sketched some of the top of my head).
Scripts and macros may facilitate the generation of chapters, especially
tables starting from spreadsheets which are then included into a document.A
Makefile would then be a perfect fit for handling dependencies.
The main idea here is to remove two issues from the current situation:
1. information duplication
2. formatting
While 1. can be addressed with a hierarchical structure, it is certain that
people have to know where information is and what is considered to be sharable
and what is unique to a document. As in programming, is not always clear at
the beginning which subset of your main program will end up in a library
function (especially if you start coding without knowing where you need to
end).
Secondly 2. shall not be a problem of the engineer who's inputing technical
information. He should provide correct data, while data rapresentation shall
be done by the typesetter. Luckily there are a couple of guys in the room who
have the skills to take care about 2.
alb
Aug 12, 2014, 7:15:20 AM8/12/14
to
Hi Tim,
Tim Wescott <seemyw...@myfooter.really> wrote:
[]
I've successfully converted some files, but some others missed completely the
images in the original one... I'm not sure why.
W.r.t LyX it may be a good idea to provide a GUI to people who are accustomed
to use one (Word) and it may potentially hide the nuances of the set of
Makefiles behind.
> But LaTeX isn't going to automatically solve your duplicated-info problem,
> any more than Word enforces it: what you need is a process, that everyone
> signs up to, that makes ONE source for information golden, and insists
> that other documents point to that information source.
Agreed, that's the most difficult part, as also noticed by Don. Is not only a
problem of acceptance, is also a problem of costume. While software guys are
kind of keen to switch to something like LaTeX because the sole mentioning of
Word gives them the creeps, other engineering disciplines are less open to it
and stuck with their Windows/Word environment.
> It means that someone reading a document needs to have the whole pile and
> constantly cross-reference, but that's just kind of life.
There must be a list of common 'functions', a library definition which
everyone needs to look up first. The issue is not for who's reading, while
who's writing. Reading unique information is guaranteed by using the same
'library', pretty much as function reuse in software/firmware practice.
Tim Wescott <seemyw...@myfooter.really> wrote:
[]
> If you do adopt LaTeX, I suggest you use LyX as the authoring tool. It's
> not WYSIWYG, which is good from a technical standpoint, but it does let
> the author type in an environment that's sort of what-you-see-is-what-you-
> meant, and it makes it easy to spin off PDFs. It's what I use for
> authoring most of my documents here, unless a customer specifically
> insists on word-compatible documents.
LaTeX -> Open Document Format -> doc
> not WYSIWYG, which is good from a technical standpoint, but it does let
> the author type in an environment that's sort of what-you-see-is-what-you-
> meant, and it makes it easy to spin off PDFs. It's what I use for
> authoring most of my documents here, unless a customer specifically
> insists on word-compatible documents.
I've successfully converted some files, but some others missed completely the
images in the original one... I'm not sure why.
W.r.t LyX it may be a good idea to provide a GUI to people who are accustomed
to use one (Word) and it may potentially hide the nuances of the set of
Makefiles behind.
> But LaTeX isn't going to automatically solve your duplicated-info problem,
> any more than Word enforces it: what you need is a process, that everyone
> signs up to, that makes ONE source for information golden, and insists
> that other documents point to that information source.
problem of acceptance, is also a problem of costume. While software guys are
kind of keen to switch to something like LaTeX because the sole mentioning of
Word gives them the creeps, other engineering disciplines are less open to it
and stuck with their Windows/Word environment.
> It means that someone reading a document needs to have the whole pile and
> constantly cross-reference, but that's just kind of life.
everyone needs to look up first. The issue is not for who's reading, while
who's writing. Reading unique information is guaranteed by using the same
'library', pretty much as function reuse in software/firmware practice.
alb
Aug 12, 2014, 7:18:20 AM8/12/14
to
Forgot my notes:
alb <al.b...@gmail.com> wrote:
[1] is Czars plural for Czar???
[2] I've head a great deal of troubles with LaTeX2HTML and switched to texinfo
for that kind of need.
alb <al.b...@gmail.com> wrote:
[1] is Czars plural for Czar???
[2] I've head a great deal of troubles with LaTeX2HTML and switched to texinfo
for that kind of need.
alb
Aug 12, 2014, 8:18:41 AM8/12/14
to
Hi Bruce,
[]
compatibility issues and many others...
> In that case, the challenge
> becomes to get the doc control people to minimise the imposition of
> complex templates, which can cause endless hours of grief for
> documenters who aren't WP gurus.
The deadliest part of Word indeed is not related to its - lack of - logic, but
rather to the very small benefit it provides to casual writers, instilling a
rather vicious belief that formatting a document is a simple task.
As soon as you start to have your document falling apart you realize how
difficult would be to manage formatting with a tool like Word.
> While on the topic, another observation... where did the tendency come
> from to abandon descriptive titles in favour of totally cryptic
> document names? I've had enough of trolling through hundreds of
> drawings where you have to open up every one to see what it's about.
An appropriate documents db will allow you to set the title, as well as its
document number (usually automatically selected for a specific type of
document), according to agreement with the customer.
We separate the document number from the file(s) itself, since we reserve the
number well ahead of writing the file. The 'object' document is indeed rather
more complex than a simple 'document title' and can be classified as a report,
note, spec...
If you get only the file, without the rest of the information, you'll likely
find yourself lost in the docs. Anyway, whenever we store the file we save it
like this: crypticname_issue#_descriptivename.extension. In this way we have
the best from both world.
BTW, cryptic names usually *do* have a logic, since they are automatically
assigned and classified according to some *rules*. Once you understand them
you will likely find more information than with a more 'human readable' title.
[]
> IME, many (most?) large corporations and consortiums go for
> market-majority stuff, typically M$, and there may not be much that
> can be done to change the situation.
At a non negligeable license cost, as well as installation efforts,
> market-majority stuff, typically M$, and there may not be much that
> can be done to change the situation.
compatibility issues and many others...
> In that case, the challenge
> becomes to get the doc control people to minimise the imposition of
> complex templates, which can cause endless hours of grief for
> documenters who aren't WP gurus.
rather to the very small benefit it provides to casual writers, instilling a
rather vicious belief that formatting a document is a simple task.
As soon as you start to have your document falling apart you realize how
difficult would be to manage formatting with a tool like Word.
> While on the topic, another observation... where did the tendency come
> from to abandon descriptive titles in favour of totally cryptic
> document names? I've had enough of trolling through hundreds of
> drawings where you have to open up every one to see what it's about.
document number (usually automatically selected for a specific type of
document), according to agreement with the customer.
We separate the document number from the file(s) itself, since we reserve the
number well ahead of writing the file. The 'object' document is indeed rather
more complex than a simple 'document title' and can be classified as a report,
note, spec...
If you get only the file, without the rest of the information, you'll likely
find yourself lost in the docs. Anyway, whenever we store the file we save it
like this: crypticname_issue#_descriptivename.extension. In this way we have
the best from both world.
BTW, cryptic names usually *do* have a logic, since they are automatically
assigned and classified according to some *rules*. Once you understand them
you will likely find more information than with a more 'human readable' title.
Don Y
Aug 12, 2014, 10:31:52 AM8/12/14
to
Hi Al,
On 8/12/2014 4:01 AM, alb wrote:
Have documentation? YES NO
Many people/organizations don't produce formal specifications, test
plans, test results, etc. They just have some "random" collection
of paper that they can point at when asked about "documentation"...
and, no one has much interest in checking to see if any of it is correct
or USEFUL!
> I personally found that in our customer set of applicable documents there was
> some degree of inconsistency (24 requirements out of 2019) which may have been
> potentially costly if found at a later stage in the development.
I have long adopted the approach of writing a User's Manual before
beginning a design. It forms an informal specification -- in terms
that a user can understand (instead of "stuffy tech-speak"). And,
it helps me think about a *unified* approach to a design -- rather than
letting the design "evolve" (which seems to be the design methodology
du jour!) in unconstrained directions.
When that is done, a customer/client *knows* what the end product
will be like and can critique each design decision that the document
presents "as fact". It lets hypothetical users ask, "How do I..."
and "What if..." questions -- all of which SHOULD be covered in the
document.
At that point, the actual *implementation* is a piece of cake! All
of the decisions have already been made -- no fear of coming up with
two DIFFERENT approaches to two *similar* problems in the user
interface because "you got a better idea when working on the second".
>> You will probably discover that you need a "Documentation Czar" to
>> "enforce" policy/consistency in your documents. In reality, this
>> individual will become the chief grunt -- responsible for FIXING
>> everyone else's screwups!
>
> We have 'Czars' [1] around, we call them PAEs (product assurance engineers)
> and they tell us what we have screwed up with respect to norms, standards,
> versions, ... But it's not enough to guarantee links are not broken.
Yup. First, they need to be able to stop "delivery" of the product
(in order for their efforts to have any "weight"). Second, they
need to be "nit-pickers" to ensure they have the requisite skills
to *catch* ALL discrepancies.
I'm "too small" to take on many of the projects that I do undertake.
And, too "lazy" (unwilling to put in extra effort that shouldn't be
necessary). So, I try to design mechanisms that amplify my efforts;
do more by doing less.
Tying the documents to the actual implementation is one such example.
The documents and the implementation are always in sync (if you
let the makefiles do their thing!). It's also a carrot for future
developers (maintainers) as the documents provide a friendlier way
of viewing and entering changes to the codebase.
For example, a recent document explains and tabulates the rules by
which I convert letters to sounds (part of a TTS). The document
organizes the rules in a nice, easy to read format. A piece of
code that I wrote extracts the rules from the document, rearranges
them to satisfy the optimizations that the run-time implements,
then encodes them for inclusion in the actual run-time.
A developer *could* insert himself into the middle of that process
if he chose to. I.e., take the encoded output from version X of
the ruleset and manually introduce changes to advance it to version
Y -- without updating the documentation. But, it's almost certain
that he will introduce a bug/typo in the process. And, will have
to manually revise the regression suite to cover his changes (another
opportunity for errors).
Expecting developers to be "lazy", the *intended* way of modifying
the rules -- by altering the documentation -- is so much easier (and
robust) that it is unlikely anyone will *try* to circumvent it!
> Relying on multiple eyes is not bad per se, but the quirk of it is that we
> tend to silently accept that if a mistake passed a review than is not a
> mistake anymore, until two different tables report defferent numbers and the
> developer does not know which to pick (neither his/her manager).
Don't discount the fact that many people are not invested in the
process. And, others may not be familiar enough with the technology
to be *competent* to recognize a subtle mistake! Or, leary of
expressing their uncertainty ("Surely Bob would have commented on
this *if* it was a genuine mistake...").
One legacy letter-to-sound algorithm often implemented "wildcards"
to represent letter patterns of interest. E.g., "any number of
voiced consonants". But, the original implementation language was
SNOBOL. Folks recoding the algorithm (into C, most often) would
carelessly interpret the implementation as, literally, "any number
of voiced consonants". And, naively implement a greedy matching
algorithm (common in C):
while (char in {L, J, V, D, ...})
pointer++
This *looks* correct. Until it is applied in particular contexts:
%D
(where % is the aforementioned wildcard). Obviously, "%D" should
match "coLD", "aDDed", etc. I.e., the % matches the first (and ONLY
the first) of these voiced consonants and the explicit 'D' matches
the immediately following 'D' -- even though it, too, is a voiced
consonant.
But, the above implementation will fail -- due to its greed!
This is a common latent bug in implementations of this particular
algorithm. Because the folks re-implementing it (in C) failed to
understand how the original SNOBOL implementation operated.
>> GUI's are dangerously seductive. They allow users to focus on the
>> *appearance* of a document instead of its semantic content. "OK,
>> that's in italics like it is supposed to be!" (No, italics are used
>> for several different types of tags in our organization... concentrate
>> on getting the TAG right, not the appearance of the text rendered for
>> that tag!)
>
> On top of that, tools like Reqtify, used to trace requirements, may analyze
> text based on some formatting styles which *may* look the same even if they
> *are* different, so the resulting document may have a set of requirements
> which are not 'captured' by the tool and go silently untraced until God knows
> when (typically at CDR, where you are ready to launch your flight
> production!).
Tools like MSWord appeal to folks who think "pretty printing" is a
goal. Or, who are tickled with the prospect of embedding a picture
or a scope trace in a document.
Lately, my documents have been interactive. E.g., the document I
am working on presently allows the user (i.e., reader) to explore
how various glottal waveform parameters affect the *sound* of the
spoken voice -- by adjusting them and *listening* to the resulting
pronunciation of (canned) words.
[You could spend paragraphs trying to explain these sound qualities
and never be certain the reader understands; but, give him an actual
sound sample to evaluate -- and contrast -- and your confidence in
his understanding goes up markedly!]
>> Beyond the tool(s), by far, the biggest problem will be training
>> folks for the proper mindset. To treat words, terms, phrases, etc.
>> as more than just collections of letters/glyphs. IME, this is a
>> lot tougher nut to crack! :<
>
> I totally agree with you. There's a tendency to deny the current problems we
> are facing (daily) and an innate inertia to refuse change, too often
> considered destabilizing. Some three years ago a revision control system was
> introduced (svn) and currently we are still facing 'acceptance' issues.
In my case, I opted for Perforce -- much to the chagrin of all who
advised me on the subject! A big part of that, IMO, was a desire
to operate in their own little isolated fiefdoms, detached from
The Organization. And, failing to perceive the needs of others
in that organization!
> Another issue I currently see in front of my long revolutionary journey is the
> transition phase. Even imagining a ready to deploy documentation system (which
> do not have yet), we can only deploy it on newly coming projects, since old
> ones are already infected by the MS virus. Engineers who are then working on
> several projects will need to continue in two different ways...kinda confusing
> if not unsustainable.
Sorry, change is always painful. :( That's often why folks cling
desperately to old ways of doing things and "wetware systems" (in
which the "system" has been designed to fit in someone's braincase
early on -- and never revised when the constraints of that braincase
were exceeded!).
An exec at a Fortune 500 company ($10B/sales) once quizzed me on
the design of part numbering systems. I gave the typical reply:
"Numbers beginning with 1 for vegetables; 2 for fruits; 3 for meats;
4 for cereals; etc. The next digit could refine this further:
11 for leafy vegetables; 12 for legumes; etc."
He took a tomato out of his desk drawer: "Vegetable! 1XXXX"
"No, it's a *fruit*!" (how many folks trying to rely on this
"wetware" system would make a similar mistake?)
"Hmmm... What about berries? Strawberries, blueberries...?"
"... tomatoes, avocados, grapes..."
"Huh? Aren't those fruit?"
<knowing grin>
"And, where do we put *candy*? And vitamins? And..."
"All those oddball things can go in the 9's!"
I.e., systems that appear simplistic usually are... too simplistic!
The conversation ended with him arranging the items on his desk in
a haphazard order and "identifying" them in exaggerated fashion:
"1, 2, 3, 4, 5, 6... get the picture?"
"Then, how do you know what a 62347 is?"
"I type the part number into this computer and it tells me everything
I want to know about it! What it is, what it costs in materials,
labor, how many we have on hand, how many we have active orders for,
how many we sold last year, what time of year has the greatest demand,
where (geographically) that demand is located, etc. To *someone*
in this organization, each of those items are THE MOST significant
aspect of this product. If *that* person was designing a part numbering
system, he would choose to encode *that* data in the part number and
care little about the criteria *you* chose!!"
[I can't resist quoting Earl Sinclair:
"As you can see, I have separated all known dinosaur wisdom into
three categories: animal, vegetable, rocks."
"Water is the opposite of fire, which we have previously established
as a vegetable. What's the opposite of a vegetable? Fruit. So, water
is a fruit! Fruit is not a vegetable, so it has to be either an
animal or a rock. We know it's not an animal. Therefore, fruit is
a rock."]
> The system I have in mind is a hierarchy of units, where information is
> *clearly* defined in one single place. Tables (spreadsheets) and diagrams can
> live in a common directory, while ad-hoc ones can be in the specific document
> folder:
>
> main # handles the data set with Makefiles
> ├── common # dedicated to all common parts
> │ ├── acronyms # needless to explain
> │ ├── applicables # list of applicable documents included in all docs
> │ ├── diagrams # technical diagrams (dataflow, state machine diagrams, ...)
> │ ├── drawings # technical drawings (mechanics, pcbs, schematics)
> │ ├── intro # introduction, often present in several docs
> │ ├── references # reference documents, with issues and revisions
> │ └── tables # budget tables (power, resources, memory structure, ...)
> ├── lists # list of documents, components, units
> ├── notes # technical notes (potentially linked to change requests)
> ├── plans # development plans,
> └── specs # subsystem specs
> └── ABC-DEF-0120-R # with textual sources as well as tables and diagrams
> # unique to this subsystem
> ....
Sooner or later, you will end up with huge directories and shrinking
namespaces. Why not let things live where they "should" live -- just
ensure they are accessible from everywhere that they should be
accessed?
E.g., if I embed a particular object in a particular document...
then, at a later date, decide that the object can also be used
in some other document, I don't refactor the original document
to extract the object and move it to some "shared" location.
I just reference it where it was.
[I am becoming a huge fan of relational databases! Letting
objects reside in the DBMS instead of as files in a filesystem.
It makes it easier to see dependencies]
> Each directory shall have a makefile in order to handle word processing and
> bring up to date the current directory. Documents shall have a template (or
> class), or potentially a set of templates, in order to provide a uniform and
> coherent typeset throughout the project and also between projects.
>
> The structure (just a draft) shall not evolve too much otherwise it becomes
> unclear where does a piece of information belong to, but shall take into
> account all needs (I just sketched some of the top of my head).
>
> Scripts and macros may facilitate the generation of chapters, especially
> tables starting from spreadsheets which are then included into a document.A
> Makefile would then be a perfect fit for handling dependencies.
Your goals are far more ambitious than mine -- I just want to keep
my docs synchronized with the objects they describe. I count on
the VCS to handle much of that "make" overhead, currently.
> The main idea here is to remove two issues from the current situation:
>
> 1. information duplication
> 2. formatting
>
> While 1. can be addressed with a hierarchical structure, it is certain that
> people have to know where information is and what is considered to be sharable
> and what is unique to a document. As in programming, is not always clear at
> the beginning which subset of your main program will end up in a library
> function (especially if you start coding without knowing where you need to
> end).
>
> Secondly 2. shall not be a problem of the engineer who's inputing technical
> information. He should provide correct data, while data rapresentation shall
> be done by the typesetter. Luckily there are a couple of guys in the room who
> have the skills to take care about 2.
You can also opt to not be concerned with "presentation" (depends on
where your docs will be consumed). E.g., web pages tend to be
content driven; PDFs are layout driven.
Also, consider what you will want *in* those documents. I think
(as evidenced from my current efforts) that documents will become
much more "active" than "dead tree products". So, you may find
that "text's" role decreases over time to other media forms.
Good luck!
On 8/12/2014 4:01 AM, alb wrote:
> Don Y<th...@is.not.me.com> wrote:
>
>> MSWord isn't good for anything -- even a one page memorandum! Wait
>> until you discover that you can't access documents created with
>> version N-2 or whatever!<frown>
>
> This is something I do not understand. As a company we are trying to improve
> our processes and workflow in order to get a better product in less time and
> we pin point how important it is to check, verify, validate each technical
> step through the project's lifetime. Aside to that we have to deliver
> documentation, indeed a document is a component no less important than any
> other component in our system, is a part of it without which you cannot:
>
> A. prove you are doing it right
> B. prove you are doing it in time
>
> Then why there's such a large gap in process development applied to
> documentation? How can the stakeholders be at the mercy of tools like MS Word?
Because folks treat documentation as a "checkoff" item:
>
>> MSWord isn't good for anything -- even a one page memorandum! Wait
>> until you discover that you can't access documents created with
>> version N-2 or whatever!<frown>
>
> This is something I do not understand. As a company we are trying to improve
> our processes and workflow in order to get a better product in less time and
> we pin point how important it is to check, verify, validate each technical
> step through the project's lifetime. Aside to that we have to deliver
> documentation, indeed a document is a component no less important than any
> other component in our system, is a part of it without which you cannot:
>
> A. prove you are doing it right
> B. prove you are doing it in time
>
> Then why there's such a large gap in process development applied to
> documentation? How can the stakeholders be at the mercy of tools like MS Word?
Have documentation? YES NO
Many people/organizations don't produce formal specifications, test
plans, test results, etc. They just have some "random" collection
of paper that they can point at when asked about "documentation"...
and, no one has much interest in checking to see if any of it is correct
or USEFUL!
> I personally found that in our customer set of applicable documents there was
> some degree of inconsistency (24 requirements out of 2019) which may have been
> potentially costly if found at a later stage in the development.
beginning a design. It forms an informal specification -- in terms
that a user can understand (instead of "stuffy tech-speak"). And,
it helps me think about a *unified* approach to a design -- rather than
letting the design "evolve" (which seems to be the design methodology
du jour!) in unconstrained directions.
When that is done, a customer/client *knows* what the end product
will be like and can critique each design decision that the document
presents "as fact". It lets hypothetical users ask, "How do I..."
and "What if..." questions -- all of which SHOULD be covered in the
document.
At that point, the actual *implementation* is a piece of cake! All
of the decisions have already been made -- no fear of coming up with
two DIFFERENT approaches to two *similar* problems in the user
interface because "you got a better idea when working on the second".
>> You will probably discover that you need a "Documentation Czar" to
>> "enforce" policy/consistency in your documents. In reality, this
>> individual will become the chief grunt -- responsible for FIXING
>> everyone else's screwups!
>
> We have 'Czars' [1] around, we call them PAEs (product assurance engineers)
> and they tell us what we have screwed up with respect to norms, standards,
> versions, ... But it's not enough to guarantee links are not broken.
(in order for their efforts to have any "weight"). Second, they
need to be "nit-pickers" to ensure they have the requisite skills
to *catch* ALL discrepancies.
I'm "too small" to take on many of the projects that I do undertake.
And, too "lazy" (unwilling to put in extra effort that shouldn't be
necessary). So, I try to design mechanisms that amplify my efforts;
do more by doing less.
Tying the documents to the actual implementation is one such example.
The documents and the implementation are always in sync (if you
let the makefiles do their thing!). It's also a carrot for future
developers (maintainers) as the documents provide a friendlier way
of viewing and entering changes to the codebase.
For example, a recent document explains and tabulates the rules by
which I convert letters to sounds (part of a TTS). The document
organizes the rules in a nice, easy to read format. A piece of
code that I wrote extracts the rules from the document, rearranges
them to satisfy the optimizations that the run-time implements,
then encodes them for inclusion in the actual run-time.
A developer *could* insert himself into the middle of that process
if he chose to. I.e., take the encoded output from version X of
the ruleset and manually introduce changes to advance it to version
Y -- without updating the documentation. But, it's almost certain
that he will introduce a bug/typo in the process. And, will have
to manually revise the regression suite to cover his changes (another
opportunity for errors).
Expecting developers to be "lazy", the *intended* way of modifying
the rules -- by altering the documentation -- is so much easier (and
robust) that it is unlikely anyone will *try* to circumvent it!
> Relying on multiple eyes is not bad per se, but the quirk of it is that we
> tend to silently accept that if a mistake passed a review than is not a
> mistake anymore, until two different tables report defferent numbers and the
> developer does not know which to pick (neither his/her manager).
process. And, others may not be familiar enough with the technology
to be *competent* to recognize a subtle mistake! Or, leary of
expressing their uncertainty ("Surely Bob would have commented on
this *if* it was a genuine mistake...").
One legacy letter-to-sound algorithm often implemented "wildcards"
to represent letter patterns of interest. E.g., "any number of
voiced consonants". But, the original implementation language was
SNOBOL. Folks recoding the algorithm (into C, most often) would
carelessly interpret the implementation as, literally, "any number
of voiced consonants". And, naively implement a greedy matching
algorithm (common in C):
while (char in {L, J, V, D, ...})
pointer++
This *looks* correct. Until it is applied in particular contexts:
%D
(where % is the aforementioned wildcard). Obviously, "%D" should
match "coLD", "aDDed", etc. I.e., the % matches the first (and ONLY
the first) of these voiced consonants and the explicit 'D' matches
the immediately following 'D' -- even though it, too, is a voiced
consonant.
But, the above implementation will fail -- due to its greed!
This is a common latent bug in implementations of this particular
algorithm. Because the folks re-implementing it (in C) failed to
understand how the original SNOBOL implementation operated.
>> GUI's are dangerously seductive. They allow users to focus on the
>> *appearance* of a document instead of its semantic content. "OK,
>> that's in italics like it is supposed to be!" (No, italics are used
>> for several different types of tags in our organization... concentrate
>> on getting the TAG right, not the appearance of the text rendered for
>> that tag!)
>
> On top of that, tools like Reqtify, used to trace requirements, may analyze
> text based on some formatting styles which *may* look the same even if they
> *are* different, so the resulting document may have a set of requirements
> which are not 'captured' by the tool and go silently untraced until God knows
> when (typically at CDR, where you are ready to launch your flight
> production!).
goal. Or, who are tickled with the prospect of embedding a picture
or a scope trace in a document.
Lately, my documents have been interactive. E.g., the document I
am working on presently allows the user (i.e., reader) to explore
how various glottal waveform parameters affect the *sound* of the
spoken voice -- by adjusting them and *listening* to the resulting
pronunciation of (canned) words.
[You could spend paragraphs trying to explain these sound qualities
and never be certain the reader understands; but, give him an actual
sound sample to evaluate -- and contrast -- and your confidence in
his understanding goes up markedly!]
>> Beyond the tool(s), by far, the biggest problem will be training
>> folks for the proper mindset. To treat words, terms, phrases, etc.
>> as more than just collections of letters/glyphs. IME, this is a
>> lot tougher nut to crack! :<
>
> I totally agree with you. There's a tendency to deny the current problems we
> are facing (daily) and an innate inertia to refuse change, too often
> considered destabilizing. Some three years ago a revision control system was
> introduced (svn) and currently we are still facing 'acceptance' issues.
advised me on the subject! A big part of that, IMO, was a desire
to operate in their own little isolated fiefdoms, detached from
The Organization. And, failing to perceive the needs of others
in that organization!
> Another issue I currently see in front of my long revolutionary journey is the
> transition phase. Even imagining a ready to deploy documentation system (which
> do not have yet), we can only deploy it on newly coming projects, since old
> ones are already infected by the MS virus. Engineers who are then working on
> several projects will need to continue in two different ways...kinda confusing
> if not unsustainable.
desperately to old ways of doing things and "wetware systems" (in
which the "system" has been designed to fit in someone's braincase
early on -- and never revised when the constraints of that braincase
were exceeded!).
An exec at a Fortune 500 company ($10B/sales) once quizzed me on
the design of part numbering systems. I gave the typical reply:
"Numbers beginning with 1 for vegetables; 2 for fruits; 3 for meats;
4 for cereals; etc. The next digit could refine this further:
11 for leafy vegetables; 12 for legumes; etc."
He took a tomato out of his desk drawer: "Vegetable! 1XXXX"
"No, it's a *fruit*!" (how many folks trying to rely on this
"wetware" system would make a similar mistake?)
"Hmmm... What about berries? Strawberries, blueberries...?"
"... tomatoes, avocados, grapes..."
"Huh? Aren't those fruit?"
<knowing grin>
"And, where do we put *candy*? And vitamins? And..."
"All those oddball things can go in the 9's!"
I.e., systems that appear simplistic usually are... too simplistic!
The conversation ended with him arranging the items on his desk in
a haphazard order and "identifying" them in exaggerated fashion:
"1, 2, 3, 4, 5, 6... get the picture?"
"Then, how do you know what a 62347 is?"
"I type the part number into this computer and it tells me everything
I want to know about it! What it is, what it costs in materials,
labor, how many we have on hand, how many we have active orders for,
how many we sold last year, what time of year has the greatest demand,
where (geographically) that demand is located, etc. To *someone*
in this organization, each of those items are THE MOST significant
aspect of this product. If *that* person was designing a part numbering
system, he would choose to encode *that* data in the part number and
care little about the criteria *you* chose!!"
[I can't resist quoting Earl Sinclair:
"As you can see, I have separated all known dinosaur wisdom into
three categories: animal, vegetable, rocks."
"Water is the opposite of fire, which we have previously established
as a vegetable. What's the opposite of a vegetable? Fruit. So, water
is a fruit! Fruit is not a vegetable, so it has to be either an
animal or a rock. We know it's not an animal. Therefore, fruit is
a rock."]
> The system I have in mind is a hierarchy of units, where information is
> *clearly* defined in one single place. Tables (spreadsheets) and diagrams can
> live in a common directory, while ad-hoc ones can be in the specific document
> folder:
>
> main # handles the data set with Makefiles
> ├── common # dedicated to all common parts
> │ ├── acronyms # needless to explain
> │ ├── applicables # list of applicable documents included in all docs
> │ ├── diagrams # technical diagrams (dataflow, state machine diagrams, ...)
> │ ├── drawings # technical drawings (mechanics, pcbs, schematics)
> │ ├── intro # introduction, often present in several docs
> │ ├── references # reference documents, with issues and revisions
> │ └── tables # budget tables (power, resources, memory structure, ...)
> ├── lists # list of documents, components, units
> ├── notes # technical notes (potentially linked to change requests)
> ├── plans # development plans,
> └── specs # subsystem specs
> └── ABC-DEF-0120-R # with textual sources as well as tables and diagrams
> # unique to this subsystem
>
> I forgot to add an 'output' folder which will contain the whole set of
> documents produced by the latest build. In an ideal world LaTeX2HTML [2] could
> be used to export the whole set of docs in html and allow to browse document
> content with a browser instead, where hyperlinks are a much faster way to
> reach the information.
Why the need for specific folders/directories for each item type?
> I forgot to add an 'output' folder which will contain the whole set of
> documents produced by the latest build. In an ideal world LaTeX2HTML [2] could
> be used to export the whole set of docs in html and allow to browse document
> content with a browser instead, where hyperlinks are a much faster way to
> reach the information.
Sooner or later, you will end up with huge directories and shrinking
namespaces. Why not let things live where they "should" live -- just
ensure they are accessible from everywhere that they should be
accessed?
E.g., if I embed a particular object in a particular document...
then, at a later date, decide that the object can also be used
in some other document, I don't refactor the original document
to extract the object and move it to some "shared" location.
I just reference it where it was.
[I am becoming a huge fan of relational databases! Letting
objects reside in the DBMS instead of as files in a filesystem.
It makes it easier to see dependencies]
> Each directory shall have a makefile in order to handle word processing and
> bring up to date the current directory. Documents shall have a template (or
> class), or potentially a set of templates, in order to provide a uniform and
> coherent typeset throughout the project and also between projects.
>
> The structure (just a draft) shall not evolve too much otherwise it becomes
> unclear where does a piece of information belong to, but shall take into
> account all needs (I just sketched some of the top of my head).
>
> Scripts and macros may facilitate the generation of chapters, especially
> tables starting from spreadsheets which are then included into a document.A
> Makefile would then be a perfect fit for handling dependencies.
my docs synchronized with the objects they describe. I count on
the VCS to handle much of that "make" overhead, currently.
> The main idea here is to remove two issues from the current situation:
>
> 1. information duplication
> 2. formatting
>
> While 1. can be addressed with a hierarchical structure, it is certain that
> people have to know where information is and what is considered to be sharable
> and what is unique to a document. As in programming, is not always clear at
> the beginning which subset of your main program will end up in a library
> function (especially if you start coding without knowing where you need to
> end).
>
> Secondly 2. shall not be a problem of the engineer who's inputing technical
> information. He should provide correct data, while data rapresentation shall
> be done by the typesetter. Luckily there are a couple of guys in the room who
> have the skills to take care about 2.
where your docs will be consumed). E.g., web pages tend to be
content driven; PDFs are layout driven.
Also, consider what you will want *in* those documents. I think
(as evidenced from my current efforts) that documents will become
much more "active" than "dead tree products". So, you may find
that "text's" role decreases over time to other media forms.
Good luck!
John Larkin
Aug 12, 2014, 11:23:14 AM8/12/14
to
On 12 Aug 2014 11:01:19 GMT, al.b...@gmail.com (alb) wrote:
>Hi Don,
>
>Don Y <th...@is.not.me.com> wrote:
>[]
>> I can sympathize with your dilemma. A few (disorganized) comments.
>>
>> MSWord isn't good for anything -- even a one page memorandum! Wait
>> until you discover that you can't access documents created with
>> version N-2 or whatever! <frown>
>
>This is something I do not understand. As a company we are trying to improve
>our processes and workflow in order to get a better product in less time and
>we pin point how important it is to check, verify, validate each technical
>step through the project's lifetime. Aside to that we have to deliver
>documentation, indeed a document is a component no less important than any
>other component in our system, is a part of it without which you cannot:
>
>A. prove you are doing it right
>B. prove you are doing it in time
>
>Then why there's such a large gap in process development applied to
>documentation? How can the stakeholders be at the mercy of tools like MS Word?
You're at the mercy of all sorts of tools, from oscilloscopes to paper
>Hi Don,
>
>Don Y <th...@is.not.me.com> wrote:
>[]
>> I can sympathize with your dilemma. A few (disorganized) comments.
>>
>> MSWord isn't good for anything -- even a one page memorandum! Wait
>> until you discover that you can't access documents created with
>> version N-2 or whatever! <frown>
>
>This is something I do not understand. As a company we are trying to improve
>our processes and workflow in order to get a better product in less time and
>we pin point how important it is to check, verify, validate each technical
>step through the project's lifetime. Aside to that we have to deliver
>documentation, indeed a document is a component no less important than any
>other component in our system, is a part of it without which you cannot:
>
>A. prove you are doing it right
>B. prove you are doing it in time
>
>Then why there's such a large gap in process development applied to
>documentation? How can the stakeholders be at the mercy of tools like MS Word?
shredders. Word is reasonably efficient and reliable if you use it sensibly.
>
>I personally found that in our customer set of applicable documents there was
>some degree of inconsistency (24 requirements out of 2019) which may have been
>potentially costly if found at a later stage in the development.
("can you build us an LVDT simulator?") to voluminous and mainly wrong. I have
one that says, literally, "blah blah" and "not sure - ask Olav" where Olav quit
and went to work for Qualcomm. TBD is the most common TLA in lots of these.
We just design what we figure they actually need. Sometimes I lie to my
customers so that I can include things that I know they will eventually need.
>
>> You will probably discover that you need a "Documentation Czar" to
>> "enforce" policy/consistency in your documents. In reality, this
>> individual will become the chief grunt -- responsible for FIXING
>> everyone else's screwups!
>
>We have 'Czars' [1] around, we call them PAEs (product assurance engineers)
>and they tell us what we have screwed up with respect to norms, standards,
>versions, ... But it's not enough to guarantee links are not broken.
>
>Relying on multiple eyes is not bad per se, but the quirk of it is that we
>tend to silently accept that if a mistake passed a review than is not a
>mistake anymore, until two different tables report defferent numbers and the
>developer does not know which to pick (neither his/her manager).
obvious mistakes, TBDs, and blank sections. One requirement, supported by
drawings, shows grounded BNC connector inputs; not far away it is forbidden to
use single-ended coaxial inputs. What's a boy to do?
Content, correct and complete content, matters a lot more than form or editing
tools. We document some things with photos of whiteboard sketches.
alb
Aug 12, 2014, 11:27:47 AM8/12/14
to
Hi David,
David Brown <david...@hesbynett.no> wrote:
[]
> Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
> that's the best plan - it gives you better quality typesetting, but it
> is hard to use the more advanced features of LaTeX. Personally, I
> usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
> programming. Another front-end I have heard nice things about is
> TeXstudio. Getting a good front-end that users are happy with will make
> all the difference here.
As I said in an earlier post, people used to GUI will likely expect another
GUI to do the same job. On top of that whenever people see my 'green on black'
terminals the first they think about is Matrix (just to explain the kind of
environment I work in)!
A friendly editor for latex sources may be a viable option, I believe there's
a plethora of opensource packages doing that and tipically they are highly
configurable expecially when it comes to 'building'.
> LaTeX has several advantages over a word processor, but also some
> disadvantages. If you are going to convert to it, you will need someone
> (possibly you) who is the "expert" to help with more advanced uses.
We have a couple of guys who have quite some experience with it (one has
amused himself with describing all his master thesis state machines with
latex) so there shouldn't be a problem in having the expert available. OTOH a
documenting system should be less permissive in terms of formatting and reduce
the amount of 'clutter' a user may introduce.
> 1. LaTeX generates much nicer and clearer output. In particular,
> documents are consistent - you will never again get inconsistent spacing
> or fonts.
inconsistent spacing or font is not the main issue, while having the document
name not properly propagated on the 56th page header is rather annoying.
> 2. LaTeX documents are far more amenable to version control. And LaTeX
> will never corrupt your source files, unlike certain word processors.
I used to co-author scientific papers with latex and svn and even right before
submission merging was extremely simple.
> 3. Your output is in pdf. Anyone can read the output, on any device,
> without worrying about formatting and layout differences on different
> computers. The output is more advanced pdf (indexes, cross-links, etc.)
> than you can get from MS Word and expensive Adobe products, and is
> generated automatically and simply.
So far I envy only one thing to Adobe products: pdf annotations. There's no
free equivalent and the lack of standard make it very difficult to be portable
through programs. I find pdf annotations quite useful when reviewing docs.
> 4. You can automate it, and use macros. The possibilities here are endless.
We have defined a class to format the document as a standard company's
document, it worked like a charm and has a bunch of nice commands already
built in. The difficult part is to get it widely and coherently used. Maybe we
should come up with a plan and an example on a tutorial project.
>
> 5. You can easily include different files and document sections. This
> could be an answer to having a "single source of truth" while still
> having duplicate information available in different documents. Have
> parts of the documentation in separate files, and include those parts
> when generating the full set of output documents.
including file is a piece of cake, a lesser simple problem is to define the
structure that holds the common parts and what kind of parts shall be common.
> 6. If you are working with source code, you can include formatted source
> code in your documents, knowing that a "make" will get the latest code.
some time we are asked also to include reports coming out from CAD tools (see
FPGA timing reports, ...). Luckily those reports are often spit out as text
file and are easy to embed in a latex document.
> 7. Your customers will have to come back to you when they want a change
> to the documentation, because they can't fix it themselves.
This is not common practice in space industry. A configured item (document)
cannot be edited and only pdf files are contractually binding. I recently had
an issue with one of our client's speicification requirement where there was
no clear label for each req. (marked with a bold *R*). In order to be able to
trace the requirement I asked to change the document, they did not do it and I
found myself in the unconfortable situation where I had to modify my client's
document in order to be sure to cover all requirements.
> If you do stick to a word processor, I recommend LibreOffice over MS
> Office. I think it does a better job of encouraging the use of styles
> rather than ad-hoc formatting, and it can generate nice pdf documents
> (not as nice as with LaTeX, but better than anything you can get with
> Word and external pdf converters). And it's cross-platform.
For licensing issues, we are slowly moving towards libreoffice. I find it much
better than Word, but I have to understand how I can put in place my
hierarchical structure.
David Brown <david...@hesbynett.no> wrote:
[]
> I don't use much LaTeX at work - I haven't yet converted others here.
sigh...
> Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
> that's the best plan - it gives you better quality typesetting, but it
> is hard to use the more advanced features of LaTeX. Personally, I
> usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
> programming. Another front-end I have heard nice things about is
> TeXstudio. Getting a good front-end that users are happy with will make
> all the difference here.
GUI to do the same job. On top of that whenever people see my 'green on black'
terminals the first they think about is Matrix (just to explain the kind of
environment I work in)!
A friendly editor for latex sources may be a viable option, I believe there's
a plethora of opensource packages doing that and tipically they are highly
configurable expecially when it comes to 'building'.
> LaTeX has several advantages over a word processor, but also some
> disadvantages. If you are going to convert to it, you will need someone
> (possibly you) who is the "expert" to help with more advanced uses.
amused himself with describing all his master thesis state machines with
latex) so there shouldn't be a problem in having the expert available. OTOH a
documenting system should be less permissive in terms of formatting and reduce
the amount of 'clutter' a user may introduce.
> 1. LaTeX generates much nicer and clearer output. In particular,
> documents are consistent - you will never again get inconsistent spacing
> or fonts.
name not properly propagated on the 56th page header is rather annoying.
> 2. LaTeX documents are far more amenable to version control. And LaTeX
> will never corrupt your source files, unlike certain word processors.
submission merging was extremely simple.
> 3. Your output is in pdf. Anyone can read the output, on any device,
> without worrying about formatting and layout differences on different
> computers. The output is more advanced pdf (indexes, cross-links, etc.)
> than you can get from MS Word and expensive Adobe products, and is
> generated automatically and simply.
free equivalent and the lack of standard make it very difficult to be portable
through programs. I find pdf annotations quite useful when reviewing docs.
> 4. You can automate it, and use macros. The possibilities here are endless.
document, it worked like a charm and has a bunch of nice commands already
built in. The difficult part is to get it widely and coherently used. Maybe we
should come up with a plan and an example on a tutorial project.
>
> 5. You can easily include different files and document sections. This
> could be an answer to having a "single source of truth" while still
> having duplicate information available in different documents. Have
> parts of the documentation in separate files, and include those parts
> when generating the full set of output documents.
structure that holds the common parts and what kind of parts shall be common.
> 6. If you are working with source code, you can include formatted source
> code in your documents, knowing that a "make" will get the latest code.
FPGA timing reports, ...). Luckily those reports are often spit out as text
file and are easy to embed in a latex document.
> 7. Your customers will have to come back to you when they want a change
> to the documentation, because they can't fix it themselves.
cannot be edited and only pdf files are contractually binding. I recently had
an issue with one of our client's speicification requirement where there was
no clear label for each req. (marked with a bold *R*). In order to be able to
trace the requirement I asked to change the document, they did not do it and I
found myself in the unconfortable situation where I had to modify my client's
document in order to be sure to cover all requirements.
> If you do stick to a word processor, I recommend LibreOffice over MS
> Office. I think it does a better job of encouraging the use of styles
> rather than ad-hoc formatting, and it can generate nice pdf documents
> (not as nice as with LaTeX, but better than anything you can get with
> Word and external pdf converters). And it's cross-platform.
better than Word, but I have to understand how I can put in place my
hierarchical structure.
John Larkin
Aug 12, 2014, 11:28:41 AM8/12/14
to
a manual eventually anyhow. Writing the manual first uncovers all sorts of
issues that the usual requirements doc wouldn't. We sometimes put stuff into the
preliminary manual that is really design related, and edit it out for the user
versions.
>
>When that is done, a customer/client *knows* what the end product
>will be like and can critique each design decision that the document
>presents "as fact". It lets hypothetical users ask, "How do I..."
>and "What if..." questions -- all of which SHOULD be covered in the
>document.
>
>At that point, the actual *implementation* is a piece of cake! All
>of the decisions have already been made -- no fear of coming up with
>two DIFFERENT approaches to two *similar* problems in the user
>interface because "you got a better idea when working on the second".
David Brown
Aug 12, 2014, 3:45:44 PM8/12/14
to
On 12/08/14 17:27, alb wrote:
> Hi David,
>
> David Brown <david...@hesbynett.no> wrote:
> []
>> I don't use much LaTeX at work - I haven't yet converted others here.
>
> sigh...
>
>> Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
>> that's the best plan - it gives you better quality typesetting, but it
>> is hard to use the more advanced features of LaTeX. Personally, I
>> usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
>> programming. Another front-end I have heard nice things about is
>> TeXstudio. Getting a good front-end that users are happy with will make
>> all the difference here.
>
> As I said in an earlier post, people used to GUI will likely expect another
> GUI to do the same job. On top of that whenever people see my 'green on black'
> terminals the first they think about is Matrix (just to explain the kind of
> environment I work in)!
>
> A friendly editor for latex sources may be a viable option, I believe there's
> a plethora of opensource packages doing that and tipically they are highly
> configurable expecially when it comes to 'building'.
Both TeXclipse and TeXstudio are LaTeX-friendly text editors, while LyX
> Hi David,
>
> David Brown <david...@hesbynett.no> wrote:
> []
>> I don't use much LaTeX at work - I haven't yet converted others here.
>
> sigh...
>
>> Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
>> that's the best plan - it gives you better quality typesetting, but it
>> is hard to use the more advanced features of LaTeX. Personally, I
>> usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
>> programming. Another front-end I have heard nice things about is
>> TeXstudio. Getting a good front-end that users are happy with will make
>> all the difference here.
>
> As I said in an earlier post, people used to GUI will likely expect another
> GUI to do the same job. On top of that whenever people see my 'green on black'
> terminals the first they think about is Matrix (just to explain the kind of
> environment I work in)!
>
> A friendly editor for latex sources may be a viable option, I believe there's
> a plethora of opensource packages doing that and tipically they are highly
> configurable expecially when it comes to 'building'.
is a sort of half-WYSIWIG editor. TeXclipse is fine if you are used to
Eclipse, but would probably be very strange to people not used to that
sort of program development tool. TeXstudio is a text editor that is
dedicated to LaTeX, and thus has lots of toolbars full of symbols, etc.,
while not being as big and intimidating as Eclipse + TeXclipse. LyX
tries to be more WYSIWG, and makes some effort to make the document look
like the final output even while editing.
But as you say, there are lots of such packages and editors - you'll
have to try out a few to see what will suit best.
>
>> LaTeX has several advantages over a word processor, but also some
>> disadvantages. If you are going to convert to it, you will need someone
>> (possibly you) who is the "expert" to help with more advanced uses.
>
> We have a couple of guys who have quite some experience with it (one has
> amused himself with describing all his master thesis state machines with
> latex) so there shouldn't be a problem in having the expert available. OTOH a
> documenting system should be less permissive in terms of formatting and reduce
> the amount of 'clutter' a user may introduce.
state machines in graphviz (dot) these days. Long ago I did some using
MetaPost, but while it is a fascinating tool, it is not easy to learn.
As for getting consistent formatting, that's just a matter of making
sure everyone uses the same document class, which one of your experts
should set up including a set of standard packages. It is vastly easier
than trying to enforce consistency in word processor files.
>
>> 1. LaTeX generates much nicer and clearer output. In particular,
>> documents are consistent - you will never again get inconsistent spacing
>> or fonts.
>
> inconsistent spacing or font is not the main issue, while having the document
> name not properly propagated on the 56th page header is rather annoying.
I'm sure people with Word can manage it! Yes, LaTeX will help get that
sort of thing right.
>
>> 2. LaTeX documents are far more amenable to version control. And LaTeX
>> will never corrupt your source files, unlike certain word processors.
>
> I used to co-author scientific papers with latex and svn and even right before
> submission merging was extremely simple.
>
>> 3. Your output is in pdf. Anyone can read the output, on any device,
>> without worrying about formatting and layout differences on different
>> computers. The output is more advanced pdf (indexes, cross-links, etc.)
>> than you can get from MS Word and expensive Adobe products, and is
>> generated automatically and simply.
>
> So far I envy only one thing to Adobe products: pdf annotations. There's no
> free equivalent and the lack of standard make it very difficult to be portable
> through programs. I find pdf annotations quite useful when reviewing docs.
pdf reader on Windows, but haven't made much use of annotations).
Evince and Ocular do annotations in Linux, but with some limitations
(again, I haven't used annotations with these programs).
>
>> 4. You can automate it, and use macros. The possibilities here are endless.
>
> We have defined a class to format the document as a standard company's
> document, it worked like a charm and has a bunch of nice commands already
> built in. The difficult part is to get it widely and coherently used. Maybe we
> should come up with a plan and an example on a tutorial project.
>
>>
>> 5. You can easily include different files and document sections. This
>> could be an answer to having a "single source of truth" while still
>> having duplicate information available in different documents. Have
>> parts of the documentation in separate files, and include those parts
>> when generating the full set of output documents.
>
> including file is a piece of cake, a lesser simple problem is to define the
> structure that holds the common parts and what kind of parts shall be common.
Tim Williams
Aug 12, 2014, 4:00:32 PM8/12/14
to
"David Brown" <david...@hesbynett.no> wrote in message
news:lsdqt8$uja$1...@dont-email.me...
graphviz is newer; I haven't heard of it.
There's also a schematic drawing package out there, which I haven't tried.
Hmm, y'know, it should be possible to parse simple formats like LTSpice
.ASC into TeX'able code. Maybe there's a Package For That already, too?
Tim
--
Seven Transistor Labs
Electrical Engineering Consultation
Website: http://seventransistorlabs.com
news:lsdqt8$uja$1...@dont-email.me...
> It can be fun doing diagrams in "pure" LaTeX, but I would probably do
> state machines in graphviz (dot) these days. Long ago I did some using
> MetaPost, but while it is a fascinating tool, it is not easy to learn.
TikZ (and related) seems to be the popular tool these days. Unless
> state machines in graphviz (dot) these days. Long ago I did some using
> MetaPost, but while it is a fascinating tool, it is not easy to learn.
graphviz is newer; I haven't heard of it.
There's also a schematic drawing package out there, which I haven't tried.
Hmm, y'know, it should be possible to parse simple formats like LTSpice
.ASC into TeX'able code. Maybe there's a Package For That already, too?
Tim
--
Seven Transistor Labs
Electrical Engineering Consultation
Website: http://seventransistorlabs.com
Joe Gwinn
Aug 13, 2014, 9:47:33 AM8/13/14
to
In article <lsbeeu$ueu$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
[big snip]
standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
SGML at least ten years ago. The reason for the SGML requirement was
to ensure to proof against the disappearance of data held only in a
proprietary format. And FrameMaker is suited to the generation of huge
complex documents, documents that will choke MS Word.
Joe Gwinn
wrote:
[big snip]
>
> After that, I started using FrameMaker. In some ways, more capable.
> In others, more limited. I have recently been contemplating moving
> to a full SGML implementation (newer versions of FM support SGML to
> some degree so my "conversions" shouldn't be too painful). But,
> that's still a fair bit of effort, on my part, and, a fair bit of
> *risk* so I have been procrastinating on that decision (and, meanwhile,
> accumulating more documents that will eventually have to undergo any
> such conversion!)
The IEEE Standards Association, the source of things like the Ethernet
> After that, I started using FrameMaker. In some ways, more capable.
> In others, more limited. I have recently been contemplating moving
> to a full SGML implementation (newer versions of FM support SGML to
> some degree so my "conversions" shouldn't be too painful). But,
> that's still a fair bit of effort, on my part, and, a fair bit of
> *risk* so I have been procrastinating on that decision (and, meanwhile,
> accumulating more documents that will eventually have to undergo any
> such conversion!)
standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
SGML at least ten years ago. The reason for the SGML requirement was
to ensure to proof against the disappearance of data held only in a
proprietary format. And FrameMaker is suited to the generation of huge
complex documents, documents that will choke MS Word.
Joe Gwinn
Phil Hobbs
Aug 13, 2014, 2:21:18 PM8/13/14
to
On 8/12/2014 11:27 AM, alb wrote:
> Hi David,
>
> David Brown <david...@hesbynett.no> wrote:
> []
>> I don't use much LaTeX at work - I haven't yet converted others here.
>
> sigh...
>
>> Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
>> that's the best plan - it gives you better quality typesetting, but it
>> is hard to use the more advanced features of LaTeX. Personally, I
>> usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
>> programming. Another front-end I have heard nice things about is
>> TeXstudio. Getting a good front-end that users are happy with will make
>> all the difference here.
>
> As I said in an earlier post, people used to GUI will likely expect another
> GUI to do the same job. On top of that whenever people see my 'green on black'
> terminals the first they think about is Matrix (just to explain the kind of
> environment I work in)!
>
> A friendly editor for latex sources may be a viable option, I believe there's
> a plethora of opensource packages doing that and tipically they are highly
> configurable expecially when it comes to 'building'.
I've tried a couple of these things, and always got stymied by conflicts
> Hi David,
>
> David Brown <david...@hesbynett.no> wrote:
> []
>> I don't use much LaTeX at work - I haven't yet converted others here.
>
> sigh...
>
>> Someone suggested LyX as a WYSIWYG front-end to LaTeX. I'm not sure
>> that's the best plan - it gives you better quality typesetting, but it
>> is hard to use the more advanced features of LaTeX. Personally, I
>> usually use TeXclipse with Eclipse, which suits me as I use Eclipse for
>> programming. Another front-end I have heard nice things about is
>> TeXstudio. Getting a good front-end that users are happy with will make
>> all the difference here.
>
> As I said in an earlier post, people used to GUI will likely expect another
> GUI to do the same job. On top of that whenever people see my 'green on black'
> terminals the first they think about is Matrix (just to explain the kind of
> environment I work in)!
>
> A friendly editor for latex sources may be a viable option, I believe there's
> a plethora of opensource packages doing that and tipically they are highly
> configurable expecially when it comes to 'building'.
between the macro sets they require to get the GUI part, and the ones I
need to get the document done. (Publishers' macro sets, for instance.)
So I just went back to writing markup with a programmer's editor that
does syntax highlighting and bracket matching.
I do use makefiles for LaTeX documents, but then I used to use one to
automate Wordperfect for DOS as well. ;)
Cheers from the Galerie de la Reine in Brussels. Ypres tomorrow.
Don Y
Aug 13, 2014, 2:25:44 PM8/13/14
to
Hi Joe,
MSWord chokes on *any* document of substance! I was COMFORTABLY
editing 500 page documents with VP3 more than 20 years ago... on
a 25MHz machine! Those same documents would bring Word to its
knees, today, on a 3GHz machine!
FM's .mif format, AFAICT, is still supported in current releases
*and* well documented. But, the SGML approach would *guarantee*
that the content could be extracted even if some proprietary
format was used internally.
In my case, the appeal of SGML is that it lets me tag "objects"
in the document and access them with other tools. Currently, I
am doing that by adopting conventions for appropriate tags and
their hierarchy within a (regular) FM document -- in much the
same way that a formally structured SGML document might.
I've just got too many (thousands of) pages to be eager to try
to convert/restructure them under SGML though the nonSGML
"mode" of FM still handles them -- many versions later than the
FM version of their original composition! (can't say that of
anything with MS in the title!)
Wile ther4e are many things in VP that I miss (mostly, clever hacks),
the move to FM has been a pleasant and rewarding one! (I think
I moved at about FM4 or so)
editing 500 page documents with VP3 more than 20 years ago... on
a 25MHz machine! Those same documents would bring Word to its
knees, today, on a 3GHz machine!
FM's .mif format, AFAICT, is still supported in current releases
*and* well documented. But, the SGML approach would *guarantee*
that the content could be extracted even if some proprietary
format was used internally.
In my case, the appeal of SGML is that it lets me tag "objects"
in the document and access them with other tools. Currently, I
am doing that by adopting conventions for appropriate tags and
their hierarchy within a (regular) FM document -- in much the
same way that a formally structured SGML document might.
I've just got too many (thousands of) pages to be eager to try
to convert/restructure them under SGML though the nonSGML
"mode" of FM still handles them -- many versions later than the
FM version of their original composition! (can't say that of
anything with MS in the title!)
Wile ther4e are many things in VP that I miss (mostly, clever hacks),
the move to FM has been a pleasant and rewarding one! (I think
I moved at about FM4 or so)
Lasse Langwadt Christensen
Aug 13, 2014, 2:38:03 PM8/13/14
to
-Lasse
alb
Aug 14, 2014, 2:28:01 AM8/14/14
to
Hi Lasse,
Lasse Langwadt Christensen <lang...@fonz.dk> wrote:
[]
oriented and no introduction of whatsoever was dedicated to *nix systems and
everything that comes with it.
IMHO *nix systems encourage the user to explore and learn, he/she can go as
deep as he/she wants without any limitation. This approach changes your way to
see a machine and suddenly you realize how much freedom you have.
LaTeX is just another piece of a large infrastructure that has put a lot of
efforts in separating mechanisms from policies (R.Raymond), but when you grew
up believing that there's little alternative to 'MS Word' you start to adapt
to it, developing habits and beliefs that are hard to crack.
Al
Lasse Langwadt Christensen <lang...@fonz.dk> wrote:
[]
> When I was at uni we all used AUCTeX for emacs
unfortunately most of the courses I've followed (some 15 years ago) were MS
oriented and no introduction of whatsoever was dedicated to *nix systems and
everything that comes with it.
IMHO *nix systems encourage the user to explore and learn, he/she can go as
deep as he/she wants without any limitation. This approach changes your way to
see a machine and suddenly you realize how much freedom you have.
LaTeX is just another piece of a large infrastructure that has put a lot of
efforts in separating mechanisms from policies (R.Raymond), but when you grew
up believing that there's little alternative to 'MS Word' you start to adapt
to it, developing habits and beliefs that are hard to crack.
Al
k...@attt.bizz
Aug 14, 2014, 9:04:41 PM8/14/14
to
On Wed, 13 Aug 2014 09:47:33 -0400, Joe Gwinn <joeg...@comcast.net>
wrote:
When I was at IBM, all of our documents were written in Frame. I liked
using Frame, a lot (I once had a Win Version but I don't know what I
did with the disks). OTOH, trying to force MS Word to do what I want
it to do is a PITA.
Before Frame, going back at least 40 years, and probably ten before
that, they used an internal markup language ("Script"). At one time
IBM was the largest publisher in the world. That's a lot of bits.
wrote:
using Frame, a lot (I once had a Win Version but I don't know what I
did with the disks). OTOH, trying to force MS Word to do what I want
it to do is a PITA.
Before Frame, going back at least 40 years, and probably ten before
that, they used an internal markup language ("Script"). At one time
IBM was the largest publisher in the world. That's a lot of bits.
John G
Aug 15, 2014, 12:02:49 AM8/15/14
to
After serious thinking k...@attt.bizz wrote :
And if I remember correctly they mainly used a printer in Poughkeepsie
who also printed a lot of comic books. (Hard to tell the difference)
lol
who also printed a lot of comic books. (Hard to tell the difference)
lol
Reinhardt Behm
Aug 15, 2014, 12:42:15 AM8/15/14
to
We got it just after I had done my masters thesis using runnoff. We even had
a laser printer driven by it - price range 70k$.
Some year later I wrote my own version of Script running on a Z80 CP/M
system.
--
Reinhardt
Tim Williams
Aug 15, 2014, 1:00:40 AM8/15/14
to
"Reinhardt Behm" <rb...@hushmail.com> wrote in message
news:lsk33g$lk8$1...@dont-email.me...
https://www.youtube.com/watch?v=XvwNKpDUkiE
news:lsk33g$lk8$1...@dont-email.me...
> VS-Script - Old memories...
>
> We got it just after I had done my masters thesis using runnoff. We even
> had
> a laser printer driven by it - price range 70k$.
> Some year later I wrote my own version of Script running on a Z80 CP/M
> system.
80s laser printer:
>
> We got it just after I had done my masters thesis using runnoff. We even
> had
> a laser printer driven by it - price range 70k$.
> Some year later I wrote my own version of Script running on a Z80 CP/M
> system.
https://www.youtube.com/watch?v=XvwNKpDUkiE
josephkk
Aug 15, 2014, 2:11:33 AM8/15/14
to
?-)
Joe Gwinn
Aug 15, 2014, 9:53:15 AM8/15/14
to
In article <lsgaj4$809$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
flailing with a 300-page requirements document that contained many
equations and tables and figures. On symptom was that the live links
in the text to those equations and figures and tables became hopelessly
scrambled. Another symptom was that the numbering of the figures et al
became random. I worked for a very large company, so the IT department
queried Microsoft, only to be told that MS Word was intended only for
documents of up to thirty pages. Gee, it didn't say *that* on the box.
I did suggest Frame, but nobody knew how to use it and didn't want to
learn in the middle of the project, and the customer had specified Word
anyway.
Frame was also a factor more expensive than MS Word. That didn't come
up, but it would have. The obvious counter argument is that Notepad is
cheaper than Word, but neither of them can do the job, so the
comparison is flawed.
So we just struggled on, and became expert in the coddling of MS Word.
For one thing, all those live links were eliminated.
> FM's .mif format, AFAICT, is still supported in current releases
> *and* well documented. But, the SGML approach would *guarantee*
> that the content could be extracted even if some proprietary
> format was used internally.
Yes, and the mere existence of this escape route helps maintain
discipline and competition in the vendor community.
> In my case, the appeal of SGML is that it lets me tag "objects"
> in the document and access them with other tools. Currently, I
> am doing that by adopting conventions for appropriate tags and
> their hierarchy within a (regular) FM document -- in much the
> same way that a formally structured SGML document might.
I don't think that IEEE does this, precisely to protect their escape
route. And because IEEE Editors are technical writers, not
programmers.
> I've just got too many (thousands of) pages to be eager to try
> to convert/restructure them under SGML though the nonSGML
> "mode" of FM still handles them -- many versions later than the
> FM version of their original composition! (can't say that of
> anything with MS in the title!)
>
> While there are many things in VP that I miss (mostly, clever hacks),
Joe Gwinn
wrote:
> Hi Joe,
>
> On 8/13/2014 6:47 AM, Joe Gwinn wrote:
> > In article<lsbeeu$ueu$1...@speranza.aioe.org>, Don Y<th...@is.not.me.com>
> > wrote:
> >
> >> After that, I started using FrameMaker. In some ways, more capable.
> >> In others, more limited. I have recently been contemplating moving
> >> to a full SGML implementation (newer versions of FM support SGML to
> >> some degree so my "conversions" shouldn't be too painful). But,
> >> that's still a fair bit of effort, on my part, and, a fair bit of
> >> *risk* so I have been procrastinating on that decision (and, meanwhile,
> >> accumulating more documents that will eventually have to undergo any
> >> such conversion!)
> >
> > The IEEE Standards Association, the source of things like the Ethernet
> > standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
> > SGML at least ten years ago. The reason for the SGML requirement was
> > to ensure to against the disappearance of data held only in a
> Hi Joe,
>
> On 8/13/2014 6:47 AM, Joe Gwinn wrote:
> > In article<lsbeeu$ueu$1...@speranza.aioe.org>, Don Y<th...@is.not.me.com>
> > wrote:
> >
> >> After that, I started using FrameMaker. In some ways, more capable.
> >> In others, more limited. I have recently been contemplating moving
> >> to a full SGML implementation (newer versions of FM support SGML to
> >> some degree so my "conversions" shouldn't be too painful). But,
> >> that's still a fair bit of effort, on my part, and, a fair bit of
> >> *risk* so I have been procrastinating on that decision (and, meanwhile,
> >> accumulating more documents that will eventually have to undergo any
> >> such conversion!)
> >
> > The IEEE Standards Association, the source of things like the Ethernet
> > standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
> > SGML at least ten years ago. The reason for the SGML requirement was
> > proprietary format. And FrameMaker is suited to the generation of huge
> > complex documents, documents that will choke MS Word.
>
> MSWord chokes on *any* document of substance! I was COMFORTABLY
> editing 500 page documents with VP3 more than 20 years ago... on
> a 25MHz machine! Those same documents would bring Word to its
> knees, today, on a 3GHz machine!
On a project some years ago, we were having big problems with MS Word
> > complex documents, documents that will choke MS Word.
>
> MSWord chokes on *any* document of substance! I was COMFORTABLY
> editing 500 page documents with VP3 more than 20 years ago... on
> a 25MHz machine! Those same documents would bring Word to its
> knees, today, on a 3GHz machine!
flailing with a 300-page requirements document that contained many
equations and tables and figures. On symptom was that the live links
in the text to those equations and figures and tables became hopelessly
scrambled. Another symptom was that the numbering of the figures et al
became random. I worked for a very large company, so the IT department
queried Microsoft, only to be told that MS Word was intended only for
documents of up to thirty pages. Gee, it didn't say *that* on the box.
I did suggest Frame, but nobody knew how to use it and didn't want to
learn in the middle of the project, and the customer had specified Word
anyway.
Frame was also a factor more expensive than MS Word. That didn't come
up, but it would have. The obvious counter argument is that Notepad is
cheaper than Word, but neither of them can do the job, so the
comparison is flawed.
So we just struggled on, and became expert in the coddling of MS Word.
For one thing, all those live links were eliminated.
> FM's .mif format, AFAICT, is still supported in current releases
> *and* well documented. But, the SGML approach would *guarantee*
> that the content could be extracted even if some proprietary
> format was used internally.
discipline and competition in the vendor community.
> In my case, the appeal of SGML is that it lets me tag "objects"
> in the document and access them with other tools. Currently, I
> am doing that by adopting conventions for appropriate tags and
> their hierarchy within a (regular) FM document -- in much the
> same way that a formally structured SGML document might.
route. And because IEEE Editors are technical writers, not
programmers.
> I've just got too many (thousands of) pages to be eager to try
> to convert/restructure them under SGML though the nonSGML
> "mode" of FM still handles them -- many versions later than the
> FM version of their original composition! (can't say that of
> anything with MS in the title!)
>
> the move to FM has been a pleasant and rewarding one! (I think
> I moved at about FM4 or so)
VP?
> I moved at about FM4 or so)
Joe Gwinn
k...@attt.bizz
Aug 15, 2014, 11:30:56 AM8/15/14
to
was called something else, too, but It's been too long.
>We got it just after I had done my masters thesis using runnoff. We even had
>a laser printer driven by it - price range 70k$.
>Some year later I wrote my own version of Script running on a Z80 CP/M
>system.
shortly after and we moved to Frame.
Don Y
Aug 15, 2014, 1:14:00 PM8/15/14
to
Hi Joe,
On 8/15/2014 6:53 AM, Joe Gwinn wrote:
[attrs elided]
>>> The IEEE Standards Association, the source of things like the Ethernet
>>> standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
>>> SGML at least ten years ago. The reason for the SGML requirement was
>>> to ensure to against the disappearance of data held only in a
>>> proprietary format. And FrameMaker is suited to the generation of huge
>>> complex documents, documents that will choke MS Word.
>>
>> MSWord chokes on *any* document of substance! I was COMFORTABLY
>> editing 500 page documents with VP3 more than 20 years ago... on
>> a 25MHz machine! Those same documents would bring Word to its
>> knees, today, on a 3GHz machine!
>
> On a project some years ago, we were having big problems with MS Word
> flailing with a 300-page requirements document that contained many
> equations and tables and figures. On symptom was that the live links
> in the text to those equations and figures and tables became hopelessly
And, it's virtually impossible to MANUALLY verify that all of these
cross references, index entries, table/page/figure numbering, etc. are
correct! It's a matter of blind faith -- you really want to trust
your tools.
> scrambled. Another symptom was that the numbering of the figures et al
> became random. I worked for a very large company, so the IT department
> queried Microsoft, only to be told that MS Word was intended only for
> documents of up to thirty pages. Gee, it didn't say *that* on the box.
Yup. But, you *learn*, quickly! ;-)
> I did suggest Frame, but nobody knew how to use it and didn't want to
> learn in the middle of the project, and the customer had specified Word
> anyway.
Moving to it from VP, I found it relatively easy to learn. Equation
editor is a bit tricky -- especially if you want to exploit its
abilities to factor and reduce! I missed the ease with which I could
quickly pull up the "raw" text files and manipulate them by scripting
a "text editor" (emacs, Brief, etc.). I don't think any of these
tools have the versatility that you might need for odd/unusual
replacements/transformations (though if you were to tag aggressively
under SGML, you could probably make any of the changes that "sound
reasonable" just by changing the presentation of those tags).
What I missed, most, was the ability to change a "format"/tag so
that it displayed differently on recto/verso pages! In VP you could
do this easily and come up with some interesting layouts that
"magically" adapted the content to its *actual* placement in the
document.
For example, one format that I used had wide "outside" margins
(with annotations that I could place in this margin as "side heads"
to draw attention to descriptions of key subjects and where those
occurred in the body text). Within the SINGLE "body column" (which
hugged the inner margin), I would place figures towards the outside
margin with short descriptions ALONGSIDE on the inner margin. Note
"inner" and "outer" not "left" and "right".
So, on a recto page:
read this! XXXXXXXXXXXX this is a description
XXXXXXXXXXXX of the picture that
XXXXXXXXXXXX it appears alongside!
XXXXXXXXXXXX
XXXXXXXXXXXX
And, if this ended up falling on a verso page:
this is a description XXXXXXXXXXXX read this!
of the picture that XXXXXXXXXXXX
it appears alongside! XXXXXXXXXXXX
XXXXXXXXXXXX
XXXXXXXXXXXX
I.e., so the layouts are mirror images. In FM, the only distinction
for recto/verso lies in the page (left/right) templates -- I would
have to treat this as multiple columns and specifically place
each bit in the corresponding column!
> Frame was also a factor more expensive than MS Word. That didn't come
> up, but it would have. The obvious counter argument is that Notepad is
> cheaper than Word, but neither of them can do the job, so the
> comparison is flawed.
And pen and ink are even cheaper yet! :<
> So we just struggled on, and became expert in the coddling of MS Word.
> For one thing, all those live links were eliminated.
Yes. You end up AVOIDING features -- because they are unreliable
(or inefficient).
"Tell me again: why are we using this tool?"
>> FM's .mif format, AFAICT, is still supported in current releases
>> *and* well documented. But, the SGML approach would *guarantee*
>> that the content could be extracted even if some proprietary
>> format was used internally.
>
> Yes, and the mere existence of this escape route helps maintain
> discipline and competition in the vendor community.
In my case, it has allowed me to gain access to the document in
a form that I can massage algorithmically. The old VP (pre Corel)
was like this -- plain text (with markup commands embedded).
Adobe products are like this, for the most part. E.g., I can
create drawings in Illustrator and then excise the pertinent
parts (eliding all the preamble, etc.) to move them into
"objects" of my own choosing. E.g., this was how I originally
"designed" all of the gestures in my gesture recognizer... draw
them in Illustrator, extract the terse representation of each
spline/bezier that forms the gesture's path, then import it
into my codebase.
>> In my case, the appeal of SGML is that it lets me tag "objects"
>> in the document and access them with other tools. Currently, I
>> am doing that by adopting conventions for appropriate tags and
>> their hierarchy within a (regular) FM document -- in much the
>> same way that a formally structured SGML document might.
>
> I don't think that IEEE does this, precisely to protect their escape
> route. And because IEEE Editors are technical writers, not
> programmers.
I would think they would, at least, do things like tag any document
references *within* the document with IEEE_Standard or similar.
Then, present the objects tagged thusly in "Bold", etc. In that
way, they could mechanically determine which documents are referenced
in each document, etc.
I think a publishing tool should probably disallow any commands that
alter the appearance (in any way!) of text. FORCE the user to apply
a specific tag in order to alter the presentation. In that way, be
able to assign meaning to the alteration.
E.g., using "italics" for words in foreign languages (etc.), emphasis,
titles of articles, etc. allows each to *appear* as it should (or, as
we were taught in school) -- but loses the distinction between their
intents! Force the user to tag "etc." with Foreign_Words, "My
Scholarly Publication" with Article_Title, and stressed words with
Emphasis.
>> I've just got too many (thousands of) pages to be eager to try
>> to convert/restructure them under SGML though the nonSGML
>> "mode" of FM still handles them -- many versions later than the
>> FM version of their original composition! (can't say that of
>> anything with MS in the title!)
>>
>> While there are many things in VP that I miss (mostly, clever hacks),
>> the move to FM has been a pleasant and rewarding one! (I think
>> I moved at about FM4 or so)
>
> VP?
Ventura Publisher. I used it in the early 90's. I am not sure if
it still survives. Last time I looked at it, Corel had largely
emasculated it! :<
On 8/15/2014 6:53 AM, Joe Gwinn wrote:
[attrs elided]
>>> The IEEE Standards Association, the source of things like the Ethernet
>>> standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
>>> SGML at least ten years ago. The reason for the SGML requirement was
>>> to ensure to against the disappearance of data held only in a
>>> proprietary format. And FrameMaker is suited to the generation of huge
>>> complex documents, documents that will choke MS Word.
>>
>> MSWord chokes on *any* document of substance! I was COMFORTABLY
>> editing 500 page documents with VP3 more than 20 years ago... on
>> a 25MHz machine! Those same documents would bring Word to its
>> knees, today, on a 3GHz machine!
>
> On a project some years ago, we were having big problems with MS Word
> flailing with a 300-page requirements document that contained many
> equations and tables and figures. On symptom was that the live links
> in the text to those equations and figures and tables became hopelessly
cross references, index entries, table/page/figure numbering, etc. are
correct! It's a matter of blind faith -- you really want to trust
your tools.
> scrambled. Another symptom was that the numbering of the figures et al
> became random. I worked for a very large company, so the IT department
> queried Microsoft, only to be told that MS Word was intended only for
> documents of up to thirty pages. Gee, it didn't say *that* on the box.
> I did suggest Frame, but nobody knew how to use it and didn't want to
> learn in the middle of the project, and the customer had specified Word
> anyway.
editor is a bit tricky -- especially if you want to exploit its
abilities to factor and reduce! I missed the ease with which I could
quickly pull up the "raw" text files and manipulate them by scripting
a "text editor" (emacs, Brief, etc.). I don't think any of these
tools have the versatility that you might need for odd/unusual
replacements/transformations (though if you were to tag aggressively
under SGML, you could probably make any of the changes that "sound
reasonable" just by changing the presentation of those tags).
What I missed, most, was the ability to change a "format"/tag so
that it displayed differently on recto/verso pages! In VP you could
do this easily and come up with some interesting layouts that
"magically" adapted the content to its *actual* placement in the
document.
For example, one format that I used had wide "outside" margins
(with annotations that I could place in this margin as "side heads"
to draw attention to descriptions of key subjects and where those
occurred in the body text). Within the SINGLE "body column" (which
hugged the inner margin), I would place figures towards the outside
margin with short descriptions ALONGSIDE on the inner margin. Note
"inner" and "outer" not "left" and "right".
So, on a recto page:
read this! XXXXXXXXXXXX this is a description
XXXXXXXXXXXX of the picture that
XXXXXXXXXXXX it appears alongside!
XXXXXXXXXXXX
XXXXXXXXXXXX
And, if this ended up falling on a verso page:
this is a description XXXXXXXXXXXX read this!
of the picture that XXXXXXXXXXXX
it appears alongside! XXXXXXXXXXXX
XXXXXXXXXXXX
XXXXXXXXXXXX
I.e., so the layouts are mirror images. In FM, the only distinction
for recto/verso lies in the page (left/right) templates -- I would
have to treat this as multiple columns and specifically place
each bit in the corresponding column!
> Frame was also a factor more expensive than MS Word. That didn't come
> up, but it would have. The obvious counter argument is that Notepad is
> cheaper than Word, but neither of them can do the job, so the
> comparison is flawed.
> So we just struggled on, and became expert in the coddling of MS Word.
> For one thing, all those live links were eliminated.
(or inefficient).
"Tell me again: why are we using this tool?"
>> FM's .mif format, AFAICT, is still supported in current releases
>> *and* well documented. But, the SGML approach would *guarantee*
>> that the content could be extracted even if some proprietary
>> format was used internally.
>
> Yes, and the mere existence of this escape route helps maintain
> discipline and competition in the vendor community.
a form that I can massage algorithmically. The old VP (pre Corel)
was like this -- plain text (with markup commands embedded).
Adobe products are like this, for the most part. E.g., I can
create drawings in Illustrator and then excise the pertinent
parts (eliding all the preamble, etc.) to move them into
"objects" of my own choosing. E.g., this was how I originally
"designed" all of the gestures in my gesture recognizer... draw
them in Illustrator, extract the terse representation of each
spline/bezier that forms the gesture's path, then import it
into my codebase.
>> In my case, the appeal of SGML is that it lets me tag "objects"
>> in the document and access them with other tools. Currently, I
>> am doing that by adopting conventions for appropriate tags and
>> their hierarchy within a (regular) FM document -- in much the
>> same way that a formally structured SGML document might.
>
> I don't think that IEEE does this, precisely to protect their escape
> route. And because IEEE Editors are technical writers, not
> programmers.
references *within* the document with IEEE_Standard or similar.
Then, present the objects tagged thusly in "Bold", etc. In that
way, they could mechanically determine which documents are referenced
in each document, etc.
I think a publishing tool should probably disallow any commands that
alter the appearance (in any way!) of text. FORCE the user to apply
a specific tag in order to alter the presentation. In that way, be
able to assign meaning to the alteration.
E.g., using "italics" for words in foreign languages (etc.), emphasis,
titles of articles, etc. allows each to *appear* as it should (or, as
we were taught in school) -- but loses the distinction between their
intents! Force the user to tag "etc." with Foreign_Words, "My
Scholarly Publication" with Article_Title, and stressed words with
Emphasis.
>> I've just got too many (thousands of) pages to be eager to try
>> to convert/restructure them under SGML though the nonSGML
>> "mode" of FM still handles them -- many versions later than the
>> FM version of their original composition! (can't say that of
>> anything with MS in the title!)
>>
>> While there are many things in VP that I miss (mostly, clever hacks),
>> the move to FM has been a pleasant and rewarding one! (I think
>> I moved at about FM4 or so)
>
> VP?
it still survives. Last time I looked at it, Corel had largely
emasculated it! :<
Don Y
Aug 15, 2014, 1:31:27 PM8/15/14
to
On 8/15/2014 10:14 AM, Don Y wrote:
> For example, one format that I used had wide "outside" margins
> (with annotations that I could place in this margin as "side heads"
> to draw attention to descriptions of key subjects and where those
> occurred in the body text). Within the SINGLE "body column" (which
> hugged the inner margin), I would place figures towards the outside
> margin with short descriptions ALONGSIDE on the inner margin. Note
> "inner" and "outer" not "left" and "right".
>
> So, on a recto page:
>
> read this! XXXXXXXXXXXX this is a description
> XXXXXXXXXXXX of the picture that
> XXXXXXXXXXXX it appears alongside!
> XXXXXXXXXXXX
> XXXXXXXXXXXX
>
> And, if this ended up falling on a verso page:
>
> this is a description XXXXXXXXXXXX read this!
> of the picture that XXXXXXXXXXXX
> it appears alongside! XXXXXXXXXXXX
> XXXXXXXXXXXX
> XXXXXXXXXXXX
And, of course, I got that exactly BACKWARDS! <:-(
> For example, one format that I used had wide "outside" margins
> (with annotations that I could place in this margin as "side heads"
> to draw attention to descriptions of key subjects and where those
> occurred in the body text). Within the SINGLE "body column" (which
> hugged the inner margin), I would place figures towards the outside
> margin with short descriptions ALONGSIDE on the inner margin. Note
> "inner" and "outer" not "left" and "right".
>
> So, on a recto page:
>
> read this! XXXXXXXXXXXX this is a description
> XXXXXXXXXXXX of the picture that
> XXXXXXXXXXXX it appears alongside!
> XXXXXXXXXXXX
> XXXXXXXXXXXX
>
> And, if this ended up falling on a verso page:
>
> this is a description XXXXXXXXXXXX read this!
> of the picture that XXXXXXXXXXXX
> it appears alongside! XXXXXXXXXXXX
> XXXXXXXXXXXX
> XXXXXXXXXXXX
(and, should have used something other than whitespace for fill, here!)
Joe Gwinn
Aug 15, 2014, 2:38:34 PM8/15/14
to
In article <lslf4l$a9r$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
> Hi Joe,
>
> On 8/15/2014 6:53 AM, Joe Gwinn wrote:
>
> [attrs elided]
>
> >>> The IEEE Standards Association, the source of things like the Ethernet
> >>> standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
> >>> SGML at least ten years ago. The reason for the SGML requirement was
> >>> to ensure to against the disappearance of data held only in a
> >>> proprietary format. And FrameMaker is suited to the generation of huge
> >>> complex documents, documents that will choke MS Word.
> >>
> >> MSWord chokes on *any* document of substance! I was COMFORTABLY
> >> editing 500 page documents with VP3 more than 20 years ago... on
> >> a 25MHz machine! Those same documents would bring Word to its
> >> knees, today, on a 3GHz machine!
> >
> > On a project some years ago, we were having big problems with MS Word
> > flailing with a 300-page requirements document that contained many
> > equations and tables and figures. On symptom was that the live links
> > in the text to those equations and figures and tables became hopelessly
>
> And, it's virtually impossible to MANUALLY verify that all of these
> cross references, index entries, table/page/figure numbering, etc. are
> correct! It's a matter of blind faith -- you really want to trust
> your tools.
Well, it's not impossible, but it's very labor intensive. But we had
to manually verify anyway.
I always liked markup languages, but then I made my living as a
programmer them. I recall having to teach the typists about stack
order, so they wouldn't hurt themselves when using Digital Standard
Runoff (DSR) on VAX/VMS.
Actually, the bulk of the IEEE standards are written by the working
groups, who are unpaid (at least by IEEE) volunteers. Some Technical
Editors are expert with SGML, some are not.
> I think a publishing tool should probably disallow any commands that
> alter the appearance (in any way!) of text. FORCE the user to apply
> a specific tag in order to alter the presentation. In that way, be
> able to assign meaning to the alteration.
>
> E.g., using "italics" for words in foreign languages (etc.), emphasis,
> titles of articles, etc. allows each to *appear* as it should (or, as
> we were taught in school) -- but loses the distinction between their
> intents! Force the user to tag "etc." with Foreign_Words, "My
> Scholarly Publication" with Article_Title, and stressed words with
> Emphasis.
In the programming world, languages like Ada attempted to coerce good
programming by designing the programming language so that it was
impossible to make a large set of programming errors. The net effect
was to cripple the language, and C/C++ soon relegated all such
languages to niche status.
> >> I've just got too many (thousands of) pages to be eager to try
> >> to convert/restructure them under SGML though the nonSGML
> >> "mode" of FM still handles them -- many versions later than the
> >> FM version of their original composition! (can't say that of
> >> anything with MS in the title!)
> >>
> >> While there are many things in VP that I miss (mostly, clever hacks),
> >> the move to FM has been a pleasant and rewarding one! (I think
> >> I moved at about FM4 or so)
> >
> > VP?
>
> Ventura Publisher. I used it in the early 90's. I am not sure if
> it still survives. Last time I looked at it, Corel had largely
> emasculated it! :<
Never had the pleasure.
Joe Gwinn
wrote:
> Hi Joe,
>
> On 8/15/2014 6:53 AM, Joe Gwinn wrote:
>
> [attrs elided]
>
> >>> The IEEE Standards Association, the source of things like the Ethernet
> >>> standards (IEEE 802.3 and .11 (WiFi)), standardized on FrameMaker with
> >>> SGML at least ten years ago. The reason for the SGML requirement was
> >>> to ensure to against the disappearance of data held only in a
> >>> proprietary format. And FrameMaker is suited to the generation of huge
> >>> complex documents, documents that will choke MS Word.
> >>
> >> MSWord chokes on *any* document of substance! I was COMFORTABLY
> >> editing 500 page documents with VP3 more than 20 years ago... on
> >> a 25MHz machine! Those same documents would bring Word to its
> >> knees, today, on a 3GHz machine!
> >
> > On a project some years ago, we were having big problems with MS Word
> > flailing with a 300-page requirements document that contained many
> > equations and tables and figures. On symptom was that the live links
> > in the text to those equations and figures and tables became hopelessly
>
> And, it's virtually impossible to MANUALLY verify that all of these
> cross references, index entries, table/page/figure numbering, etc. are
> correct! It's a matter of blind faith -- you really want to trust
> your tools.
to manually verify anyway.
programmer them. I recall having to teach the typists about stack
order, so they wouldn't hurt themselves when using Digital Standard
Runoff (DSR) on VAX/VMS.
groups, who are unpaid (at least by IEEE) volunteers. Some Technical
Editors are expert with SGML, some are not.
> I think a publishing tool should probably disallow any commands that
> alter the appearance (in any way!) of text. FORCE the user to apply
> a specific tag in order to alter the presentation. In that way, be
> able to assign meaning to the alteration.
>
> E.g., using "italics" for words in foreign languages (etc.), emphasis,
> titles of articles, etc. allows each to *appear* as it should (or, as
> we were taught in school) -- but loses the distinction between their
> intents! Force the user to tag "etc." with Foreign_Words, "My
> Scholarly Publication" with Article_Title, and stressed words with
> Emphasis.
programming by designing the programming language so that it was
impossible to make a large set of programming errors. The net effect
was to cripple the language, and C/C++ soon relegated all such
languages to niche status.
> >> I've just got too many (thousands of) pages to be eager to try
> >> to convert/restructure them under SGML though the nonSGML
> >> "mode" of FM still handles them -- many versions later than the
> >> FM version of their original composition! (can't say that of
> >> anything with MS in the title!)
> >>
> >> While there are many things in VP that I miss (mostly, clever hacks),
> >> the move to FM has been a pleasant and rewarding one! (I think
> >> I moved at about FM4 or so)
> >
> > VP?
>
> Ventura Publisher. I used it in the early 90's. I am not sure if
> it still survives. Last time I looked at it, Corel had largely
> emasculated it! :<
Joe Gwinn
Don Y
Aug 15, 2014, 5:09:33 PM8/15/14
to
Hi Joe,
>>> On a project some years ago, we were having big problems with MS Word
>>> flailing with a 300-page requirements document that contained many
>>> equations and tables and figures. On symptom was that the live links
>>> in the text to those equations and figures and tables became hopelessly
>>
>> And, it's virtually impossible to MANUALLY verify that all of these
>> cross references, index entries, table/page/figure numbering, etc. are
>> correct! It's a matter of blind faith -- you really want to trust
>> your tools.
>
> Well, it's not impossible, but it's very labor intensive. But we had
> to manually verify anyway.
My condolences! It would be similar to manually verifying the code
generated by a compiler -- you just want to TRUST it and hope it
always behaves -- even if you put a cross reference in a footnote
to a table located that's located in an appendix of a different
document... etc.
> I always liked markup languages, but then I made my living as a
> programmer them. I recall having to teach the typists about stack
> order, so they wouldn't hurt themselves when using Digital Standard
> Runoff (DSR) on VAX/VMS.
I think the only practical way to develop consistent documents is
to have "regular writers" that just crank out the prose, illustrations,
etc. Then, "specialists" that massage this "raw input" into the
structured form that the DTP tools require. Hence my earlier comment
about a "Document Czar" -- who ends up being a *grunt*!
>>>> In my case, the appeal of SGML is that it lets me tag "objects"
>>>> in the document and access them with other tools. Currently, I
>>>> am doing that by adopting conventions for appropriate tags and
>>>> their hierarchy within a (regular) FM document -- in much the
>>>> same way that a formally structured SGML document might.
>>>
>>> I don't think that IEEE does this, precisely to protect their escape
>>> route. And because IEEE Editors are technical writers, not
>>> programmers.
>>
>> I would think they would, at least, do things like tag any document
>> references *within* the document with IEEE_Standard or similar.
>> Then, present the objects tagged thusly in "Bold", etc. In that
>> way, they could mechanically determine which documents are referenced
>> in each document, etc.
>
> Actually, the bulk of the IEEE standards are written by the working
> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> Editors are expert with SGML, some are not.
But, they should at least be able to understand the issues involved
(moreso than, say, a "secretary"). Newer tools are DTD driven and
can at least verify that the structure of the document that you are
creating adheres to the rules for documents of that type. E.g.,
subheadings can't exist at the top level; headings can't exist below
subheadings; etc. And, present that in a GUI-ish environment.
I think the larger problem is designing a document structure and
anticipating the types of tags that will be needed at each level
throughout. But, this responsibility can fall to the "Specialists".
>> I think a publishing tool should probably disallow any commands that
>> alter the appearance (in any way!) of text. FORCE the user to apply
>> a specific tag in order to alter the presentation. In that way, be
>> able to assign meaning to the alteration.
>>
>> E.g., using "italics" for words in foreign languages (etc.), emphasis,
>> titles of articles, etc. allows each to *appear* as it should (or, as
>> we were taught in school) -- but loses the distinction between their
>> intents! Force the user to tag "etc." with Foreign_Words, "My
>> Scholarly Publication" with Article_Title, and stressed words with
>> Emphasis.
>
> In the programming world, languages like Ada attempted to coerce good
> programming by designing the programming language so that it was
> impossible to make a large set of programming errors. The net effect
> was to cripple the language, and C/C++ soon relegated all such
> languages to niche status.
I understand your point. However, I think changes made to the
visual presentation of individual glyphs (i.e., italics, different
type family, etc.) are intended to be significant for SOME reason.
Just calling them "italics" or "bold" sidesteps that reason. And,
invites others to concentrate on mimicking the *appearance* of
some other semantic tag WITHOUT actually bringing the semantics along
with it!
E.g., in the documentation for my gestural interface, I tag the
names of all gestures with <Gesture>. So, references to "circle"
that aren't tagged thus ("The buttons are arranged in a circle.")
don't appear as gestural references ("Issue a <Gesture>Circle<Gesture>
to invoke the help menu"). Manually proofing said documents
(in final rendered form) would be too tedious if a writer could
arbitrarily alter the appearance of "Circle" to resemble its
appearance as a <Gesture> -- without explicitly tagging it as such.
(It also simplifies things like index preparation, special cross
references, etc. as the MEANING of individual bits of text is
indicated by the tag. Imagine naively indexing every reference
to "circle" -- even those that were not indicative of gestures!)
>>> On a project some years ago, we were having big problems with MS Word
>>> flailing with a 300-page requirements document that contained many
>>> equations and tables and figures. On symptom was that the live links
>>> in the text to those equations and figures and tables became hopelessly
>>
>> And, it's virtually impossible to MANUALLY verify that all of these
>> cross references, index entries, table/page/figure numbering, etc. are
>> correct! It's a matter of blind faith -- you really want to trust
>> your tools.
>
> Well, it's not impossible, but it's very labor intensive. But we had
> to manually verify anyway.
generated by a compiler -- you just want to TRUST it and hope it
always behaves -- even if you put a cross reference in a footnote
to a table located that's located in an appendix of a different
document... etc.
> I always liked markup languages, but then I made my living as a
> programmer them. I recall having to teach the typists about stack
> order, so they wouldn't hurt themselves when using Digital Standard
> Runoff (DSR) on VAX/VMS.
to have "regular writers" that just crank out the prose, illustrations,
etc. Then, "specialists" that massage this "raw input" into the
structured form that the DTP tools require. Hence my earlier comment
about a "Document Czar" -- who ends up being a *grunt*!
>>>> In my case, the appeal of SGML is that it lets me tag "objects"
>>>> in the document and access them with other tools. Currently, I
>>>> am doing that by adopting conventions for appropriate tags and
>>>> their hierarchy within a (regular) FM document -- in much the
>>>> same way that a formally structured SGML document might.
>>>
>>> I don't think that IEEE does this, precisely to protect their escape
>>> route. And because IEEE Editors are technical writers, not
>>> programmers.
>>
>> I would think they would, at least, do things like tag any document
>> references *within* the document with IEEE_Standard or similar.
>> Then, present the objects tagged thusly in "Bold", etc. In that
>> way, they could mechanically determine which documents are referenced
>> in each document, etc.
>
> Actually, the bulk of the IEEE standards are written by the working
> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> Editors are expert with SGML, some are not.
(moreso than, say, a "secretary"). Newer tools are DTD driven and
can at least verify that the structure of the document that you are
creating adheres to the rules for documents of that type. E.g.,
subheadings can't exist at the top level; headings can't exist below
subheadings; etc. And, present that in a GUI-ish environment.
I think the larger problem is designing a document structure and
anticipating the types of tags that will be needed at each level
throughout. But, this responsibility can fall to the "Specialists".
>> I think a publishing tool should probably disallow any commands that
>> alter the appearance (in any way!) of text. FORCE the user to apply
>> a specific tag in order to alter the presentation. In that way, be
>> able to assign meaning to the alteration.
>>
>> E.g., using "italics" for words in foreign languages (etc.), emphasis,
>> titles of articles, etc. allows each to *appear* as it should (or, as
>> we were taught in school) -- but loses the distinction between their
>> intents! Force the user to tag "etc." with Foreign_Words, "My
>> Scholarly Publication" with Article_Title, and stressed words with
>> Emphasis.
>
> In the programming world, languages like Ada attempted to coerce good
> programming by designing the programming language so that it was
> impossible to make a large set of programming errors. The net effect
> was to cripple the language, and C/C++ soon relegated all such
> languages to niche status.
visual presentation of individual glyphs (i.e., italics, different
type family, etc.) are intended to be significant for SOME reason.
Just calling them "italics" or "bold" sidesteps that reason. And,
invites others to concentrate on mimicking the *appearance* of
some other semantic tag WITHOUT actually bringing the semantics along
with it!
E.g., in the documentation for my gestural interface, I tag the
names of all gestures with <Gesture>. So, references to "circle"
that aren't tagged thus ("The buttons are arranged in a circle.")
don't appear as gestural references ("Issue a <Gesture>Circle<Gesture>
to invoke the help menu"). Manually proofing said documents
(in final rendered form) would be too tedious if a writer could
arbitrarily alter the appearance of "Circle" to resemble its
appearance as a <Gesture> -- without explicitly tagging it as such.
(It also simplifies things like index preparation, special cross
references, etc. as the MEANING of individual bits of text is
indicated by the tag. Imagine naively indexing every reference
to "circle" -- even those that were not indicative of gestures!)
Joe Gwinn
Aug 15, 2014, 6:43:28 PM8/15/14
to
In article <lslsu9$cdc$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
> Hi Joe,
>
[snip]
idea what they were talking about, and babbled. The result was beyond
repair in the sense that the cheapest approach was to discard the
babble and start over with people who did understand.
A war story: Many years ago, I had a Chinese programmer working for
me, and we needed to document his (very good) code. He normally
escaped doing documentation because his English wasn't nearly good
enough. My solution was to tell him to write the first draft of the
documentation in Chinese and translate it into rough English, and then
work with one of our Tech Writers (a native speaker of English). This
yielded a pretty good document, because while the Tech Writer did not
initially understand the software being documented, the programmer did,
and so could organize the presentation. The Tech Writer cleaned up the
English, and acted as the readers' proxy - if the Tech Writer didn't
understand something, he asked the programmer. Repeat until done.
> >>>> In my case, the appeal of SGML is that it lets me tag "objects"
> >>>> in the document and access them with other tools. Currently, I
> >>>> am doing that by adopting conventions for appropriate tags and
> >>>> their hierarchy within a (regular) FM document -- in much the
> >>>> same way that a formally structured SGML document might.
> >>>
> >>> I don't think that IEEE does this, precisely to protect their escape
> >>> route. And because IEEE Editors are technical writers, not
> >>> programmers.
> >>
> >> I would think they would, at least, do things like tag any document
> >> references *within* the document with IEEE_Standard or similar.
> >> Then, present the objects tagged thusly in "Bold", etc. In that
> >> way, they could mechanically determine which documents are referenced
> >> in each document, etc.
> >
> > Actually, the bulk of the IEEE standards are written by the working
> > groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> > Editors are expert with SGML, some are not.
>
> But, they should at least be able to understand the issues involved
> (moreso than, say, a "secretary"). Newer tools are DTD driven and
> can at least verify that the structure of the document that you are
> creating adheres to the rules for documents of that type. E.g.,
> subheadings can't exist at the top level; headings can't exist below
> subheadings; etc. And, present that in a GUI-ish environment.
They are always very technical, but in the domain of the standard.
Usually they are also comfortable with the editing tools, such as
Frame.
> I think the larger problem is designing a document structure and
> anticipating the types of tags that will be needed at each level
> throughout. But, this responsibility can fall to the "Specialists".
I've seen tagging done for the POSIX standards, but then these
standards were written in a purpose-built version of runoff.
This kind of thing was done in the scripts attending that specialized
form of runoff used for POSIX, but then the Tech Editor was a
world-class programmer.
I very much doubt that Power Society standards have any such thing.
Joe Gwinn
wrote:
> Hi Joe,
>
[snip]
>
> > I always liked markup languages, but then I made my living as a
> > programmer them. I recall having to teach the typists about stack
> > order, so they wouldn't hurt themselves when using Digital Standard
> > Runoff (DSR) on VAX/VMS.
>
> I think the only practical way to develop consistent documents is
> to have "regular writers" that just crank out the prose, illustrations,
> etc. Then, "specialists" that massage this "raw input" into the
> structured form that the DTP tools require. Hence my earlier comment
> about a "Document Czar" -- who ends up being a *grunt*!
I've seen this tried, and it did not work. The regular writers had no
> > I always liked markup languages, but then I made my living as a
> > programmer them. I recall having to teach the typists about stack
> > order, so they wouldn't hurt themselves when using Digital Standard
> > Runoff (DSR) on VAX/VMS.
>
> I think the only practical way to develop consistent documents is
> to have "regular writers" that just crank out the prose, illustrations,
> etc. Then, "specialists" that massage this "raw input" into the
> structured form that the DTP tools require. Hence my earlier comment
> about a "Document Czar" -- who ends up being a *grunt*!
idea what they were talking about, and babbled. The result was beyond
repair in the sense that the cheapest approach was to discard the
babble and start over with people who did understand.
A war story: Many years ago, I had a Chinese programmer working for
me, and we needed to document his (very good) code. He normally
escaped doing documentation because his English wasn't nearly good
enough. My solution was to tell him to write the first draft of the
documentation in Chinese and translate it into rough English, and then
work with one of our Tech Writers (a native speaker of English). This
yielded a pretty good document, because while the Tech Writer did not
initially understand the software being documented, the programmer did,
and so could organize the presentation. The Tech Writer cleaned up the
English, and acted as the readers' proxy - if the Tech Writer didn't
understand something, he asked the programmer. Repeat until done.
> >>>> In my case, the appeal of SGML is that it lets me tag "objects"
> >>>> in the document and access them with other tools. Currently, I
> >>>> am doing that by adopting conventions for appropriate tags and
> >>>> their hierarchy within a (regular) FM document -- in much the
> >>>> same way that a formally structured SGML document might.
> >>>
> >>> I don't think that IEEE does this, precisely to protect their escape
> >>> route. And because IEEE Editors are technical writers, not
> >>> programmers.
> >>
> >> I would think they would, at least, do things like tag any document
> >> references *within* the document with IEEE_Standard or similar.
> >> Then, present the objects tagged thusly in "Bold", etc. In that
> >> way, they could mechanically determine which documents are referenced
> >> in each document, etc.
> >
> > Actually, the bulk of the IEEE standards are written by the working
> > groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> > Editors are expert with SGML, some are not.
>
> But, they should at least be able to understand the issues involved
> (moreso than, say, a "secretary"). Newer tools are DTD driven and
> can at least verify that the structure of the document that you are
> creating adheres to the rules for documents of that type. E.g.,
> subheadings can't exist at the top level; headings can't exist below
> subheadings; etc. And, present that in a GUI-ish environment.
Usually they are also comfortable with the editing tools, such as
Frame.
> I think the larger problem is designing a document structure and
> anticipating the types of tags that will be needed at each level
> throughout. But, this responsibility can fall to the "Specialists".
standards were written in a purpose-built version of runoff.
form of runoff used for POSIX, but then the Tech Editor was a
world-class programmer.
I very much doubt that Power Society standards have any such thing.
Joe Gwinn
Don Y
Aug 15, 2014, 6:59:37 PM8/15/14
to
Hi Joe,
Ah, I don't believe in having folks who don't understand the product
(or whatever it is that is being documented) preparing documentation!
Rather, what I was addressing was to separate the PUBLICATION needs
of the document from the TECHNICAL issues being described. Presumably,
you have someone competent in the technology that can read the prose
written by the "writers" (e.g., these writers may be "junior
programmers" when it comes to documenting software; "technicians"
when it comes to documenting hardware; etc. -- they need not be
the original authors/designers of the works being documented... BUT,
are technically proficient in the vocabulary and concepts that would
be used by those "original creators") and massage it into a form
(and consistent presentation/appearance!) that gets you the last
10 yards...
I.e., split the effort into different sets of skills to get from
A to B (via C).
Most programmers/engineers are lousy writers -- they tend to forget
who they are talking to as well as the types of issues that may be
important to that audience.
Similarly, most *writers* (e.g., Lit/English majors) have no concept
of the technology that is being presented.
I think you have to go from hand to hand (to hand) to get to a
finished document product. This is hard to do in small shops who
probably don't treat documentation as anything more than a checkoff
item. (some of the manuals I've read are abysmal! even from large
multibillion dollar corporations -- as if they assumed no one would
ever READ them so why bother putting any effort into WRITING them?!)
>>> Actually, the bulk of the IEEE standards are written by the working
>>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
>>> Editors are expert with SGML, some are not.
>>
>> But, they should at least be able to understand the issues involved
>> (moreso than, say, a "secretary"). Newer tools are DTD driven and
>> can at least verify that the structure of the document that you are
>> creating adheres to the rules for documents of that type. E.g.,
>> subheadings can't exist at the top level; headings can't exist below
>> subheadings; etc. And, present that in a GUI-ish environment.
>
> They are always very technical, but in the domain of the standard.
> Usually they are also comfortable with the editing tools, such as
> Frame.
So, they just need to be conditioned to adopt a consistent tagging
methodology. Probably difficult (getting agreement) in such a large
"organization". OTOH, probably easier to *enforce*! :>
>> I think the larger problem is designing a document structure and
>> anticipating the types of tags that will be needed at each level
>> throughout. But, this responsibility can fall to the "Specialists".
>
> I've seen tagging done for the POSIX standards, but then these
> standards were written in a purpose-built version of runoff.
I think it has a lot of value as the documents become more tightly
integrated with the products. Currently, most massaging of
documents happens in the design (and documentation) phases. Once
created, they tend to be largely static and "ancillary" items.
E.g., the product never actively references them or incorporates
them into its nominal operation.
All these "advances" are obviously geared towards making documents
more useful and more of a "product resource".
>>>> I think a publishing tool should probably disallow any commands that
>>>> alter the appearance (in any way!) of text. FORCE the user to apply
>>>> a specific tag in order to alter the presentation. In that way, be
>>>> able to assign meaning to the alteration.
However, it may require the A->C->B sort of approach I mentioned
earlier.
(or whatever it is that is being documented) preparing documentation!
Rather, what I was addressing was to separate the PUBLICATION needs
of the document from the TECHNICAL issues being described. Presumably,
you have someone competent in the technology that can read the prose
written by the "writers" (e.g., these writers may be "junior
programmers" when it comes to documenting software; "technicians"
when it comes to documenting hardware; etc. -- they need not be
the original authors/designers of the works being documented... BUT,
are technically proficient in the vocabulary and concepts that would
be used by those "original creators") and massage it into a form
(and consistent presentation/appearance!) that gets you the last
10 yards...
I.e., split the effort into different sets of skills to get from
A to B (via C).
Most programmers/engineers are lousy writers -- they tend to forget
who they are talking to as well as the types of issues that may be
important to that audience.
Similarly, most *writers* (e.g., Lit/English majors) have no concept
of the technology that is being presented.
I think you have to go from hand to hand (to hand) to get to a
finished document product. This is hard to do in small shops who
probably don't treat documentation as anything more than a checkoff
item. (some of the manuals I've read are abysmal! even from large
multibillion dollar corporations -- as if they assumed no one would
ever READ them so why bother putting any effort into WRITING them?!)
>>> Actually, the bulk of the IEEE standards are written by the working
>>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
>>> Editors are expert with SGML, some are not.
>>
>> But, they should at least be able to understand the issues involved
>> (moreso than, say, a "secretary"). Newer tools are DTD driven and
>> can at least verify that the structure of the document that you are
>> creating adheres to the rules for documents of that type. E.g.,
>> subheadings can't exist at the top level; headings can't exist below
>> subheadings; etc. And, present that in a GUI-ish environment.
>
> They are always very technical, but in the domain of the standard.
> Usually they are also comfortable with the editing tools, such as
> Frame.
methodology. Probably difficult (getting agreement) in such a large
"organization". OTOH, probably easier to *enforce*! :>
>> I think the larger problem is designing a document structure and
>> anticipating the types of tags that will be needed at each level
>> throughout. But, this responsibility can fall to the "Specialists".
>
> I've seen tagging done for the POSIX standards, but then these
> standards were written in a purpose-built version of runoff.
integrated with the products. Currently, most massaging of
documents happens in the design (and documentation) phases. Once
created, they tend to be largely static and "ancillary" items.
E.g., the product never actively references them or incorporates
them into its nominal operation.
All these "advances" are obviously geared towards making documents
more useful and more of a "product resource".
>>>> I think a publishing tool should probably disallow any commands that
>>>> alter the appearance (in any way!) of text. FORCE the user to apply
>>>> a specific tag in order to alter the presentation. In that way, be
>>>> able to assign meaning to the alteration.
>>> In the programming world, languages like Ada attempted to coerce good
>>> programming by designing the programming language so that it was
>>> impossible to make a large set of programming errors. The net effect
>>> was to cripple the language, and C/C++ soon relegated all such
>>> languages to niche status.
>>
>> I understand your point. However, I think changes made to the
>> visual presentation of individual glyphs (i.e., italics, different
>> type family, etc.) are intended to be significant for SOME reason.
>> Just calling them "italics" or "bold" sidesteps that reason. And,
>> invites others to concentrate on mimicking the *appearance* of
>> some other semantic tag WITHOUT actually bringing the semantics along
>> with it!
>>> programming by designing the programming language so that it was
>>> impossible to make a large set of programming errors. The net effect
>>> was to cripple the language, and C/C++ soon relegated all such
>>> languages to niche status.
>>
>> I understand your point. However, I think changes made to the
>> visual presentation of individual glyphs (i.e., italics, different
>> type family, etc.) are intended to be significant for SOME reason.
>> Just calling them "italics" or "bold" sidesteps that reason. And,
>> invites others to concentrate on mimicking the *appearance* of
>> some other semantic tag WITHOUT actually bringing the semantics along
>> with it!
> This kind of thing was done in the scripts attending that specialized
> form of runoff used for POSIX, but then the Tech Editor was a
> world-class programmer.
I don't think that should be necessary for this sort of thing to work.
> form of runoff used for POSIX, but then the Tech Editor was a
> world-class programmer.
However, it may require the A->C->B sort of approach I mentioned
earlier.
josephkk
Aug 15, 2014, 11:59:33 PM8/15/14
to
On Fri, 15 Aug 2014 09:53:15 -0400, Joe Gwinn <joeg...@comcast.net>
wrote:
>
region (and below) to well over 1000 pages. We do not use many of the
fancies when we do it, which may be key to success. Indeed a lot of the
embedded fancies would fatally corrupt our documents in a retroactive
heartbeat.
?-)
wrote:
>
>On a project some years ago, we were having big problems with MS Word
>flailing with a 300-page requirements document that contained many
>equations and tables and figures. On symptom was that the live links
>in the text to those equations and figures and tables became hopelessly
>scrambled. Another symptom was that the numbering of the figures et al
>became random. I worked for a very large company, so the IT department
>queried Microsoft, only to be told that MS Word was intended only for
>documents of up to thirty pages. Gee, it didn't say *that* on the box.
>
Wow. In my workplace we use MSWord for documents in the hundred page
>flailing with a 300-page requirements document that contained many
>equations and tables and figures. On symptom was that the live links
>in the text to those equations and figures and tables became hopelessly
>scrambled. Another symptom was that the numbering of the figures et al
>became random. I worked for a very large company, so the IT department
>queried Microsoft, only to be told that MS Word was intended only for
>documents of up to thirty pages. Gee, it didn't say *that* on the box.
>
region (and below) to well over 1000 pages. We do not use many of the
fancies when we do it, which may be key to success. Indeed a lot of the
embedded fancies would fatally corrupt our documents in a retroactive
heartbeat.
?-)
Joe Gwinn
Aug 16, 2014, 1:54:41 PM8/16/14
to
In article <mhltu99ldmmvv27c1...@4ax.com>, josephkk
When was this? No doubt things have improved since that war story.
And our workarounds were simplifications, so Word wouldn't lose the
bead.
But Word was never intended to meet the needs of a publishing house and
its workflow.
Joe Gwinn
And our workarounds were simplifications, so Word wouldn't lose the
bead.
But Word was never intended to meet the needs of a publishing house and
its workflow.
Joe Gwinn
Joe Gwinn
Aug 16, 2014, 2:17:02 PM8/16/14
to
In article <lsm3cq$939$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
Well, yes, and that's the point of my little war story. The fact that
the programmer was Chinese only strengthens the example.
> Most programmers/engineers are lousy writers -- they tend to forget
> who they are talking to as well as the types of issues that may be
> important to that audience.
It's because we in the US no longer teach writing in High School and
before. Writing is work, and there is an artifice to be learned. We
don't teach grammar either.
By the way, we are not talking about being able to write the Great
American Novel. We are talking about writing a simple descriptive
paper. I heard from a colleague that a standard test used to qualify
candidates for a Technical Writing job - ask the candidate to write an
instruction sheet on how to tie one's shoes.
Teaching writing is expensive, because the student-teacher ratio cannot
exceed ten, or the teacher won't have time to do the detailed
correction that's needed. One of the big distinctions between US
public (tax supported) and private (parents pay) schools is that
private schools all teach how to write.
> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> of the technology that is being presented.
Hence they babble, or balk.
> I think you have to go from hand to hand (to hand) to get to a
> finished document product. This is hard to do in small shops who
> probably don't treat documentation as anything more than a checkoff
> item. (some of the manuals I've read are abysmal! even from large
> multibillion dollar corporations -- as if they assumed no one would
> ever READ them so why bother putting any effort into WRITING them?!)
There is the key. It isn't valued. And, as you mention most
programmers are terrible writers, so they will use any excuse to avoid
writing. The problem with my approach of attaching a Tech Writer to
the programmer is that it's expensive, and you have to have some Tech
Writers on staff to assign.
> >>> Actually, the bulk of the IEEE standards are written by the working
> >>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> >>> Editors are expert with SGML, some are not.
> >>
> >> But, they should at least be able to understand the issues involved
> >> (moreso than, say, a "secretary"). Newer tools are DTD driven and
> >> can at least verify that the structure of the document that you are
> >> creating adheres to the rules for documents of that type. E.g.,
> >> subheadings can't exist at the top level; headings can't exist below
> >> subheadings; etc. And, present that in a GUI-ish environment.
> >
> > They are always very technical, but in the domain of the standard.
> > Usually they are also comfortable with the editing tools, such as
> > Frame.
>
> So, they just need to be conditioned to adopt a consistent tagging
> methodology. Probably difficult (getting agreement) in such a large
> "organization". OTOH, probably easier to *enforce*! :>
The problem isn't that they are stupid. The problem is that they
usually don't see the reason to go to the trouble., and it's painful to
learn without the background.
In the case of teaching stack order to typists, they were willing
because making tables and nested tables was driving them nuts, so they
had motive.
Parallel War Story: The lab director's secretary complained to me that
the mouse didn't work, and the cursor would fly off in odd directions.
I couldn't find anything wrong with the mouse, so I watched her work.
Turns out that she was pointing the mouse in the direction she wanted
to go, and then moved there. She had no idea that one held the mouse
axis vertical regardless, and telling her didn't quite work. So, I
took the mouse apart as for cleaning, and showed here the little
wheels, and demonstrated that if I rotated one wheel, the cursor went
up and down, while the other wheel caused side-to-side motion. Also
cleaned the mouse. Problem solved - she now had an adequate mental
model of how the mouse worked.
> >> I think the larger problem is designing a document structure and
> >> anticipating the types of tags that will be needed at each level
> >> throughout. But, this responsibility can fall to the "Specialists".
> >
> > I've seen tagging done for the POSIX standards, but then these
> > standards were written in a purpose-built version of runoff.
>
> I think it has a lot of value as the documents become more tightly
> integrated with the products. Currently, most massaging of
> documents happens in the design (and documentation) phases. Once
> created, they tend to be largely static and "ancillary" items.
> E.g., the product never actively references them or incorporates
> them into its nominal operation.
>
> All these "advances" are obviously geared towards making documents
> more useful and more of a "product resource".
Yes. But it is always an investment decision.
> >>>> I think a publishing tool should probably disallow any commands that
> >>>> alter the appearance (in any way!) of text. FORCE the user to apply
> >>>> a specific tag in order to alter the presentation. In that way, be
> >>>> able to assign meaning to the alteration.
>
> >>> In the programming world, languages like Ada attempted to coerce good
> >>> programming by designing the programming language so that it was
> >>> impossible to make a large set of programming errors. The net effect
> >>> was to cripple the language, and C/C++ soon relegated all such
> >>> languages to niche status.
> >>
> >> I understand your point. However, I think changes made to the
> >> visual presentation of individual glyphs (i.e., italics, different
> >> type family, etc.) are intended to be significant for SOME reason.
> >> Just calling them "italics" or "bold" sidesteps that reason. And,
> >> invites others to concentrate on mimicking the *appearance* of
> >> some other semantic tag WITHOUT actually bringing the semantics along
> >> with it!
>
> > This kind of thing was done in the scripts attending that specialized
> > form of runoff used for POSIX, but then the Tech Editor was a
> > world-class programmer.
>
> I don't think that should be necessary for this sort of thing to work.
> However, it may require the A->C->B sort of approach I mentioned
> earlier.
>
> > I very much doubt that Power Society standards have any such thing.
My general point is that tags and scripts are a programming effort.
My other point is that tags and scripts is a lot of work, and so is
subject to cost-benefit analysis.
Joe Gwinn
wrote:
the programmer was Chinese only strengthens the example.
> Most programmers/engineers are lousy writers -- they tend to forget
> who they are talking to as well as the types of issues that may be
> important to that audience.
before. Writing is work, and there is an artifice to be learned. We
don't teach grammar either.
By the way, we are not talking about being able to write the Great
American Novel. We are talking about writing a simple descriptive
paper. I heard from a colleague that a standard test used to qualify
candidates for a Technical Writing job - ask the candidate to write an
instruction sheet on how to tie one's shoes.
Teaching writing is expensive, because the student-teacher ratio cannot
exceed ten, or the teacher won't have time to do the detailed
correction that's needed. One of the big distinctions between US
public (tax supported) and private (parents pay) schools is that
private schools all teach how to write.
> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> of the technology that is being presented.
> I think you have to go from hand to hand (to hand) to get to a
> finished document product. This is hard to do in small shops who
> probably don't treat documentation as anything more than a checkoff
> item. (some of the manuals I've read are abysmal! even from large
> multibillion dollar corporations -- as if they assumed no one would
> ever READ them so why bother putting any effort into WRITING them?!)
programmers are terrible writers, so they will use any excuse to avoid
writing. The problem with my approach of attaching a Tech Writer to
the programmer is that it's expensive, and you have to have some Tech
Writers on staff to assign.
> >>> Actually, the bulk of the IEEE standards are written by the working
> >>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> >>> Editors are expert with SGML, some are not.
> >>
> >> But, they should at least be able to understand the issues involved
> >> (moreso than, say, a "secretary"). Newer tools are DTD driven and
> >> can at least verify that the structure of the document that you are
> >> creating adheres to the rules for documents of that type. E.g.,
> >> subheadings can't exist at the top level; headings can't exist below
> >> subheadings; etc. And, present that in a GUI-ish environment.
> >
> > They are always very technical, but in the domain of the standard.
> > Usually they are also comfortable with the editing tools, such as
> > Frame.
>
> So, they just need to be conditioned to adopt a consistent tagging
> methodology. Probably difficult (getting agreement) in such a large
> "organization". OTOH, probably easier to *enforce*! :>
usually don't see the reason to go to the trouble., and it's painful to
learn without the background.
In the case of teaching stack order to typists, they were willing
because making tables and nested tables was driving them nuts, so they
had motive.
Parallel War Story: The lab director's secretary complained to me that
the mouse didn't work, and the cursor would fly off in odd directions.
I couldn't find anything wrong with the mouse, so I watched her work.
Turns out that she was pointing the mouse in the direction she wanted
to go, and then moved there. She had no idea that one held the mouse
axis vertical regardless, and telling her didn't quite work. So, I
took the mouse apart as for cleaning, and showed here the little
wheels, and demonstrated that if I rotated one wheel, the cursor went
up and down, while the other wheel caused side-to-side motion. Also
cleaned the mouse. Problem solved - she now had an adequate mental
model of how the mouse worked.
> >> I think the larger problem is designing a document structure and
> >> anticipating the types of tags that will be needed at each level
> >> throughout. But, this responsibility can fall to the "Specialists".
> >
> > I've seen tagging done for the POSIX standards, but then these
> > standards were written in a purpose-built version of runoff.
>
> I think it has a lot of value as the documents become more tightly
> integrated with the products. Currently, most massaging of
> documents happens in the design (and documentation) phases. Once
> created, they tend to be largely static and "ancillary" items.
> E.g., the product never actively references them or incorporates
> them into its nominal operation.
>
> All these "advances" are obviously geared towards making documents
> more useful and more of a "product resource".
> >>>> I think a publishing tool should probably disallow any commands that
> >>>> alter the appearance (in any way!) of text. FORCE the user to apply
> >>>> a specific tag in order to alter the presentation. In that way, be
> >>>> able to assign meaning to the alteration.
>
> >>> In the programming world, languages like Ada attempted to coerce good
> >>> programming by designing the programming language so that it was
> >>> impossible to make a large set of programming errors. The net effect
> >>> was to cripple the language, and C/C++ soon relegated all such
> >>> languages to niche status.
> >>
> >> I understand your point. However, I think changes made to the
> >> visual presentation of individual glyphs (i.e., italics, different
> >> type family, etc.) are intended to be significant for SOME reason.
> >> Just calling them "italics" or "bold" sidesteps that reason. And,
> >> invites others to concentrate on mimicking the *appearance* of
> >> some other semantic tag WITHOUT actually bringing the semantics along
> >> with it!
>
> > This kind of thing was done in the scripts attending that specialized
> > form of runoff used for POSIX, but then the Tech Editor was a
> > world-class programmer.
>
> I don't think that should be necessary for this sort of thing to work.
> However, it may require the A->C->B sort of approach I mentioned
> earlier.
>
> > I very much doubt that Power Society standards have any such thing.
My other point is that tags and scripts is a lot of work, and so is
subject to cost-benefit analysis.
Joe Gwinn
k...@attt.bizz
Aug 16, 2014, 4:28:22 PM8/16/14
to
On Sat, 16 Aug 2014 14:17:02 -0400, Joe Gwinn <joeg...@comcast.net>
wrote:
Not sure that follows anymore.
>> Most programmers/engineers are lousy writers -- they tend to forget
>> who they are talking to as well as the types of issues that may be
>> important to that audience.
>
>It's because we in the US no longer teach writing in High School and
>before. Writing is work, and there is an artifice to be learned. We
>don't teach grammar either.
No, engineers never made good writers. Technical writing has always
been a specialty. The difference is that now there are few companies
that want to invest in them so it's too often left to those who aren't
qualified.
>By the way, we are not talking about being able to write the Great
>American Novel. We are talking about writing a simple descriptive
>paper. I heard from a colleague that a standard test used to qualify
>candidates for a Technical Writing job - ask the candidate to write an
>instruction sheet on how to tie one's shoes.
Good plan but don't expect the average engineer to do it. It's not
their specialty (among a whole host of other reasons).
>Teaching writing is expensive, because the student-teacher ratio cannot
>exceed ten, or the teacher won't have time to do the detailed
>correction that's needed. One of the big distinctions between US
>public (tax supported) and private (parents pay) schools is that
>private schools all teach how to write.
Those are some absolute statements that will require support to be
believed.
>> Similarly, most *writers* (e.g., Lit/English majors) have no concept
>> of the technology that is being presented.
>
>Hence they babble, or balk.
Why should they even be asked to venture outside their training?
>> I think you have to go from hand to hand (to hand) to get to a
>> finished document product. This is hard to do in small shops who
>> probably don't treat documentation as anything more than a checkoff
>> item. (some of the manuals I've read are abysmal! even from large
>> multibillion dollar corporations -- as if they assumed no one would
>> ever READ them so why bother putting any effort into WRITING them?!)
>
>There is the key. It isn't valued. And, as you mention most
>programmers are terrible writers, so they will use any excuse to avoid
>writing. The problem with my approach of attaching a Tech Writer to
>the programmer is that it's expensive, and you have to have some Tech
>Writers on staff to assign.
Exactly, and that has nothing to do with the current state of the
schools. People are expensive. Talented people, even more so.
not only to learn Frame but to unlearn everything we'd done before
(e.g. one does *not* use <CR> to create white space). "Use the
template" was the directive. I thought it was a very good use of the
week and after I really liked using Frame.
>In the case of teaching stack order to typists, they were willing
>because making tables and nested tables was driving them nuts, so they
>had motive.
>
>Parallel War Story: The lab director's secretary complained to me that
>the mouse didn't work, and the cursor would fly off in odd directions.
>I couldn't find anything wrong with the mouse, so I watched her work.
>Turns out that she was pointing the mouse in the direction she wanted
>to go, and then moved there. She had no idea that one held the mouse
>axis vertical regardless, and telling her didn't quite work. So, I
>took the mouse apart as for cleaning, and showed here the little
>wheels, and demonstrated that if I rotated one wheel, the cursor went
>up and down, while the other wheel caused side-to-side motion. Also
>cleaned the mouse. Problem solved - she now had an adequate mental
>model of how the mouse worked.
Most just pick it up in a minute, just by moving the mouse.
<...>
wrote:
>> Most programmers/engineers are lousy writers -- they tend to forget
>> who they are talking to as well as the types of issues that may be
>> important to that audience.
>
>It's because we in the US no longer teach writing in High School and
>before. Writing is work, and there is an artifice to be learned. We
>don't teach grammar either.
been a specialty. The difference is that now there are few companies
that want to invest in them so it's too often left to those who aren't
qualified.
>By the way, we are not talking about being able to write the Great
>American Novel. We are talking about writing a simple descriptive
>paper. I heard from a colleague that a standard test used to qualify
>candidates for a Technical Writing job - ask the candidate to write an
>instruction sheet on how to tie one's shoes.
their specialty (among a whole host of other reasons).
>Teaching writing is expensive, because the student-teacher ratio cannot
>exceed ten, or the teacher won't have time to do the detailed
>correction that's needed. One of the big distinctions between US
>public (tax supported) and private (parents pay) schools is that
>private schools all teach how to write.
believed.
>> Similarly, most *writers* (e.g., Lit/English majors) have no concept
>> of the technology that is being presented.
>
>Hence they babble, or balk.
>> I think you have to go from hand to hand (to hand) to get to a
>> finished document product. This is hard to do in small shops who
>> probably don't treat documentation as anything more than a checkoff
>> item. (some of the manuals I've read are abysmal! even from large
>> multibillion dollar corporations -- as if they assumed no one would
>> ever READ them so why bother putting any effort into WRITING them?!)
>
>There is the key. It isn't valued. And, as you mention most
>programmers are terrible writers, so they will use any excuse to avoid
>writing. The problem with my approach of attaching a Tech Writer to
>the programmer is that it's expensive, and you have to have some Tech
>Writers on staff to assign.
schools. People are expensive. Talented people, even more so.
>
>> >>> Actually, the bulk of the IEEE standards are written by the working
>> >>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
>> >>> Editors are expert with SGML, some are not.
>> >>
>> >> But, they should at least be able to understand the issues involved
>> >> (moreso than, say, a "secretary"). Newer tools are DTD driven and
>> >> can at least verify that the structure of the document that you are
>> >> creating adheres to the rules for documents of that type. E.g.,
>> >> subheadings can't exist at the top level; headings can't exist below
>> >> subheadings; etc. And, present that in a GUI-ish environment.
>> >
>> > They are always very technical, but in the domain of the standard.
>> > Usually they are also comfortable with the editing tools, such as
>> > Frame.
>>
>> So, they just need to be conditioned to adopt a consistent tagging
>> methodology. Probably difficult (getting agreement) in such a large
>> "organization". OTOH, probably easier to *enforce*! :>
>
>The problem isn't that they are stupid. The problem is that they
>usually don't see the reason to go to the trouble., and it's painful to
>learn without the background.
When we switched to Frame, they sent everyone to a week-long class,
>> >>> Actually, the bulk of the IEEE standards are written by the working
>> >>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
>> >>> Editors are expert with SGML, some are not.
>> >>
>> >> But, they should at least be able to understand the issues involved
>> >> (moreso than, say, a "secretary"). Newer tools are DTD driven and
>> >> can at least verify that the structure of the document that you are
>> >> creating adheres to the rules for documents of that type. E.g.,
>> >> subheadings can't exist at the top level; headings can't exist below
>> >> subheadings; etc. And, present that in a GUI-ish environment.
>> >
>> > They are always very technical, but in the domain of the standard.
>> > Usually they are also comfortable with the editing tools, such as
>> > Frame.
>>
>> So, they just need to be conditioned to adopt a consistent tagging
>> methodology. Probably difficult (getting agreement) in such a large
>> "organization". OTOH, probably easier to *enforce*! :>
>
>The problem isn't that they are stupid. The problem is that they
>usually don't see the reason to go to the trouble., and it's painful to
>learn without the background.
not only to learn Frame but to unlearn everything we'd done before
(e.g. one does *not* use <CR> to create white space). "Use the
template" was the directive. I thought it was a very good use of the
week and after I really liked using Frame.
>In the case of teaching stack order to typists, they were willing
>because making tables and nested tables was driving them nuts, so they
>had motive.
>
>Parallel War Story: The lab director's secretary complained to me that
>the mouse didn't work, and the cursor would fly off in odd directions.
>I couldn't find anything wrong with the mouse, so I watched her work.
>Turns out that she was pointing the mouse in the direction she wanted
>to go, and then moved there. She had no idea that one held the mouse
>axis vertical regardless, and telling her didn't quite work. So, I
>took the mouse apart as for cleaning, and showed here the little
>wheels, and demonstrated that if I rotated one wheel, the cursor went
>up and down, while the other wheel caused side-to-side motion. Also
>cleaned the mouse. Problem solved - she now had an adequate mental
>model of how the mouse worked.
<...>
Joe Gwinn
Aug 16, 2014, 5:01:21 PM8/16/14
to
In article <31fvu9ll2dcv92a22...@4ax.com>,
People are still people.
> >> Most programmers/engineers are lousy writers -- they tend to forget
> >> who they are talking to as well as the types of issues that may be
> >> important to that audience.
> >
> >It's because we in the US no longer teach writing in High School and
> >before. Writing is work, and there is an artifice to be learned. We
> >don't teach grammar either.
>
> No, engineers never made good writers. Technical writing has always
> been a specialty. The difference is that now there are few companies
> that want to invest in them so it's too often left to those who aren't
> qualified.
Some were good writers, some were not. I've met both kinds.
The classic books in any field are almost always written by people who
are good writers.
I have observed that technical books written in the UK are on average
better written than those written in the US. I gather that this is
because they still teach all students in the UK how to write, whether
they want to or not.
> >By the way, we are not talking about being able to write the Great
> >American Novel. We are talking about writing a simple descriptive
> >paper. I heard from a colleague that a standard test used to qualify
> >candidates for a Technical Writing job - ask the candidate to write an
> >instruction sheet on how to tie one's shoes.
>
> Good plan but don't expect the average engineer to do it. It's not
> their specialty (among a whole host of other reasons).
And it cripples them. I see it every day.
> >Teaching writing is expensive, because the student-teacher ratio cannot
> >exceed ten, or the teacher won't have time to do the detailed
> >correction that's needed. One of the big distinctions between US
> >public (tax supported) and private (parents pay) schools is that
> >private schools all teach how to write.
>
> Those are some absolute statements that will require support to be
> believed.
This is from personal observation and talking to people who went to
private school. If you need mathematical proof, go right ahead.
> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> >> of the technology that is being presented.
> >
> >Hence they babble, or balk.
>
> Why should they even be asked to venture outside their training?
That was my original point, saying that having the non-engineer writers
go first won't work. And I've seen it tried.
Actually, on a radar system many years ago, I saw the tech manual
writers struggle to generate anything useful, and so decided it would
take less of my time if I just sat down and wrote the rough first
draft. One cannot just deliver muck because the customer verifies the
usefulness of these documents by trying to follow them.
> >> I think you have to go from hand to hand (to hand) to get to a
> >> finished document product. This is hard to do in small shops who
> >> probably don't treat documentation as anything more than a checkoff
> >> item. (some of the manuals I've read are abysmal! even from large
> >> multibillion dollar corporations -- as if they assumed no one would
> >> ever READ them so why bother putting any effort into WRITING them?!)
> >
> >There is the key. It isn't valued. And, as you mention most
> >programmers are terrible writers, so they will use any excuse to avoid
> >writing. The problem with my approach of attaching a Tech Writer to
> >the programmer is that it's expensive, and you have to have some Tech
> >Writers on staff to assign.
>
> Exactly, and that has nothing to do with the current state of the
> schools. People are expensive. Talented people, even more so.
No, it's exactly on point. The problem being solved by addition of
Tech Writers is exactly that engineers are able to graduate without
being taught how to write a comprehensible paper.
> >> >>> Actually, the bulk of the IEEE standards are written by the working
> >> >>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> >> >>> Editors are expert with SGML, some are not.
> >> >>
> >> >> But, they should at least be able to understand the issues involved
> >> >> (moreso than, say, a "secretary"). Newer tools are DTD driven and
> >> >> can at least verify that the structure of the document that you are
> >> >> creating adheres to the rules for documents of that type. E.g.,
> >> >> subheadings can't exist at the top level; headings can't exist below
> >> >> subheadings; etc. And, present that in a GUI-ish environment.
> >> >
> >> > They are always very technical, but in the domain of the standard.
> >> > Usually they are also comfortable with the editing tools, such as
> >> > Frame.
> >>
> >> So, they just need to be conditioned to adopt a consistent tagging
> >> methodology. Probably difficult (getting agreement) in such a large
> >> "organization". OTOH, probably easier to *enforce*! :>
> >
> >The problem isn't that they are stupid. The problem is that they
> >usually don't see the reason to go to the trouble., and it's painful to
> >learn without the background.
>
> When we switched to Frame, they sent everyone to a week-long class,
> not only to learn Frame but to unlearn everything we'd done before
> (e.g. one does *not* use <CR> to create white space). "Use the
> template" was the directive. I thought it was a very good use of the
> week and after I really liked using Frame.
I learned Frame from a book, and there was a learning curve for sure.
> >In the case of teaching stack order to typists, they were willing
> >because making tables and nested tables was driving them nuts, so they
> >had motive.
> >
> >Parallel War Story: The lab director's secretary complained to me that
> >the mouse didn't work, and the cursor would fly off in odd directions.
> >I couldn't find anything wrong with the mouse, so I watched her work.
> >Turns out that she was pointing the mouse in the direction she wanted
> >to go, and then moved there. She had no idea that one held the mouse
> >axis vertical regardless, and telling her didn't quite work. So, I
> >took the mouse apart as for cleaning, and showed here the little
> >wheels, and demonstrated that if I rotated one wheel, the cursor went
> >up and down, while the other wheel caused side-to-side motion. Also
> >cleaned the mouse. Problem solved - she now had an adequate mental
> >model of how the mouse worked.
>
> Most just pick it up in a minute, just by moving the mouse.
A lab director's secretary is never a kid. She was from the old
school, and had little prior experience with computers.
If you want the fuller explanation, read some of the human interface
guidelines documents from Apple in the 1980s, especially the book by
Tog (I don't recall his full name, but it will come to me - Tog is a
clip of his last name).
Joe Gwinn
<k...@attt.bizz> wrote:
> On Sat, 16 Aug 2014 14:17:02 -0400, Joe Gwinn <joeg...@comcast.net>
> wrote:
>
> >In article <lsm3cq$939$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
> >wrote:
> >
> >> Hi Joe,
> >>
> >> On 8/15/2014 3:43 PM, Joe Gwinn wrote:
> >>
[snip]
> On Sat, 16 Aug 2014 14:17:02 -0400, Joe Gwinn <joeg...@comcast.net>
> wrote:
>
> >In article <lsm3cq$939$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
> >wrote:
> >
> >> Hi Joe,
> >>
> >> On 8/15/2014 3:43 PM, Joe Gwinn wrote:
> >>
> >> Most programmers/engineers are lousy writers -- they tend to forget
> >> who they are talking to as well as the types of issues that may be
> >> important to that audience.
> >
> >It's because we in the US no longer teach writing in High School and
> >before. Writing is work, and there is an artifice to be learned. We
> >don't teach grammar either.
>
> No, engineers never made good writers. Technical writing has always
> been a specialty. The difference is that now there are few companies
> that want to invest in them so it's too often left to those who aren't
> qualified.
The classic books in any field are almost always written by people who
are good writers.
I have observed that technical books written in the UK are on average
better written than those written in the US. I gather that this is
because they still teach all students in the UK how to write, whether
they want to or not.
> >By the way, we are not talking about being able to write the Great
> >American Novel. We are talking about writing a simple descriptive
> >paper. I heard from a colleague that a standard test used to qualify
> >candidates for a Technical Writing job - ask the candidate to write an
> >instruction sheet on how to tie one's shoes.
>
> Good plan but don't expect the average engineer to do it. It's not
> their specialty (among a whole host of other reasons).
> >Teaching writing is expensive, because the student-teacher ratio cannot
> >exceed ten, or the teacher won't have time to do the detailed
> >correction that's needed. One of the big distinctions between US
> >public (tax supported) and private (parents pay) schools is that
> >private schools all teach how to write.
>
> Those are some absolute statements that will require support to be
> believed.
private school. If you need mathematical proof, go right ahead.
> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> >> of the technology that is being presented.
> >
> >Hence they babble, or balk.
>
> Why should they even be asked to venture outside their training?
go first won't work. And I've seen it tried.
Actually, on a radar system many years ago, I saw the tech manual
writers struggle to generate anything useful, and so decided it would
take less of my time if I just sat down and wrote the rough first
draft. One cannot just deliver muck because the customer verifies the
usefulness of these documents by trying to follow them.
> >> I think you have to go from hand to hand (to hand) to get to a
> >> finished document product. This is hard to do in small shops who
> >> probably don't treat documentation as anything more than a checkoff
> >> item. (some of the manuals I've read are abysmal! even from large
> >> multibillion dollar corporations -- as if they assumed no one would
> >> ever READ them so why bother putting any effort into WRITING them?!)
> >
> >There is the key. It isn't valued. And, as you mention most
> >programmers are terrible writers, so they will use any excuse to avoid
> >writing. The problem with my approach of attaching a Tech Writer to
> >the programmer is that it's expensive, and you have to have some Tech
> >Writers on staff to assign.
>
> Exactly, and that has nothing to do with the current state of the
> schools. People are expensive. Talented people, even more so.
Tech Writers is exactly that engineers are able to graduate without
being taught how to write a comprehensible paper.
> >> >>> Actually, the bulk of the IEEE standards are written by the working
> >> >>> groups, who are unpaid (at least by IEEE) volunteers. Some Technical
> >> >>> Editors are expert with SGML, some are not.
> >> >>
> >> >> But, they should at least be able to understand the issues involved
> >> >> (moreso than, say, a "secretary"). Newer tools are DTD driven and
> >> >> can at least verify that the structure of the document that you are
> >> >> creating adheres to the rules for documents of that type. E.g.,
> >> >> subheadings can't exist at the top level; headings can't exist below
> >> >> subheadings; etc. And, present that in a GUI-ish environment.
> >> >
> >> > They are always very technical, but in the domain of the standard.
> >> > Usually they are also comfortable with the editing tools, such as
> >> > Frame.
> >>
> >> So, they just need to be conditioned to adopt a consistent tagging
> >> methodology. Probably difficult (getting agreement) in such a large
> >> "organization". OTOH, probably easier to *enforce*! :>
> >
> >The problem isn't that they are stupid. The problem is that they
> >usually don't see the reason to go to the trouble., and it's painful to
> >learn without the background.
>
> When we switched to Frame, they sent everyone to a week-long class,
> not only to learn Frame but to unlearn everything we'd done before
> (e.g. one does *not* use <CR> to create white space). "Use the
> template" was the directive. I thought it was a very good use of the
> week and after I really liked using Frame.
> >In the case of teaching stack order to typists, they were willing
> >because making tables and nested tables was driving them nuts, so they
> >had motive.
> >
> >Parallel War Story: The lab director's secretary complained to me that
> >the mouse didn't work, and the cursor would fly off in odd directions.
> >I couldn't find anything wrong with the mouse, so I watched her work.
> >Turns out that she was pointing the mouse in the direction she wanted
> >to go, and then moved there. She had no idea that one held the mouse
> >axis vertical regardless, and telling her didn't quite work. So, I
> >took the mouse apart as for cleaning, and showed here the little
> >wheels, and demonstrated that if I rotated one wheel, the cursor went
> >up and down, while the other wheel caused side-to-side motion. Also
> >cleaned the mouse. Problem solved - she now had an adequate mental
> >model of how the mouse worked.
>
> Most just pick it up in a minute, just by moving the mouse.
school, and had little prior experience with computers.
If you want the fuller explanation, read some of the human interface
guidelines documents from Apple in the 1980s, especially the book by
Tog (I don't recall his full name, but it will come to me - Tog is a
clip of his last name).
Joe Gwinn
Don Y
Aug 16, 2014, 5:11:18 PM8/16/14
to
Hi Joe,
On 8/16/2014 11:17 AM, Joe Gwinn wrote:
[very proficient/creator --> familiar/technician --> document prep guy]
>> I.e., split the effort into different sets of skills to get from
>> A to B (via C).
>
> Well, yes, and that's the point of my little war story. The fact that
> the programmer was Chinese only strengthens the example.
I would think using "fresh hires", "junior staff", etc. would be an
EXCELLENT way of filling in the "middle position" in the above chain.
It allows that individual to become (intimately!) familiar with your
products without having the responsibility of making design or
implementation decisions. And, encourages building writing and
communication skills in the process. Likewise, has prepared him/her
for the eventual "very proficient" role in which he/she will have to
be aware that others will be trying to DECIPHER and EXPLAIN his/her
design/implementation decisions!
I.e., the value of consistency in the design as evidenced by teh
relative ease with which a consistent design methodology can more
readily be documented/explained (hopefully, a lesson he/she learned
while filling that middle role!)
>> Most programmers/engineers are lousy writers -- they tend to forget
>> who they are talking to as well as the types of issues that may be
>> important to that audience.
>
> It's because we in the US no longer teach writing in High School and
> before. Writing is work, and there is an artifice to be learned. We
> don't teach grammar either.
Dunno. School, for me, was many decades ago. But, I recall a fair
bit of emphasis on "English" throughout elementary and junior/senior
high schools. E.g., you couldn't be awarded a high school diploma
without having had 4 years of English -- the same was not true of
Math, Science, etc.!
> By the way, we are not talking about being able to write the Great
> American Novel. We are talking about writing a simple descriptive
> paper.
Correct. But, IMO, it's more than just being able to describe
something. You have to be able to see The Big Picture and come
up with a strategy for describing The Whole Enchilada. You don't
want to write several discrete, distinct chapters that don't "fit"
well together.
E.g., the first writing contract I took on was to document an
existing device (for which the exiting documentation was universally
recognized as abysmal, incorrect, out-of-date, etc.).
Not knowing anything about the device, I had to first familiarize myself
with it, how it would be used, the types of things you would want to
do with it, the types of details you would likely *forget* (without
continued exposure), etc. I.e., if *I* owned one of these, what would
*I* want the documentation to look like?
My prose ended up very stilted -- more like the "classic" technical
writing style (dry, as if enumerating facts). But, to my credit,
I was told old customers were cold calling *requesting* to BUY copies
of the "new manual"! The gentleman who provided support for the
device commented, "There hasn't been anything that I have been UNable
to find in the manual!" I guess a testament to the structure I laid
out for the document, the actual "presentation", depth of index, etc.
You knew *where* to look for whatever it is you sought!
Since then, I've been concentrating on how to "soften" my prose and
make it more "conversational" -- lead the reader to a specific
understanding instead of bombarding him with a set of "facts".
> I heard from a colleague that a standard test used to qualify
> candidates for a Technical Writing job - ask the candidate to write an
> instruction sheet on how to tie one's shoes.
Sensible. I always used "change a tire" as a programming "test"
(did you remember to pull off to the side of the road? OPEN the
door before getting out? How are you watching for oncoming traffic
WHILE you are focused on removing the flat? etc.)
> Teaching writing is expensive, because the student-teacher ratio cannot
> exceed ten, or the teacher won't have time to do the detailed
> correction that's needed. One of the big distinctions between US
> public (tax supported) and private (parents pay) schools is that
> private schools all teach how to write.
<frown> No idea. I went to public schools and *think* I can build a
sentence properly (though I have a persistent problem with spelling...
especially doubling consonants! :< )
I think a bigger problem is people's inability to organize their
thoughts, well. Hand someone a piece of paper and tell them to
write a piece of code, a story, etc. and they will stare at it,
unable to begin.
Give them an EXISTING piece of code, story/outline, etc. and they'll
usually have no problem "fleshing it out"!
>> Similarly, most *writers* (e.g., Lit/English majors) have no concept
>> of the technology that is being presented.
>
> Hence they babble, or balk.
I was thinking that the "junior programmer" (middle person in the
aforementioned chain) could "translate" the technical issues into
something resembling "English"; then, someone skilled in writing
and document prep could translate *that* into REAL English -- without
really having to "understand" it!
>> I think you have to go from hand to hand (to hand) to get to a
>> finished document product. This is hard to do in small shops who
>> probably don't treat documentation as anything more than a checkoff
>> item. (some of the manuals I've read are abysmal! even from large
>> multibillion dollar corporations -- as if they assumed no one would
>> ever READ them so why bother putting any effort into WRITING them?!)
>
> There is the key. It isn't valued. And, as you mention most
> programmers are terrible writers, so they will use any excuse to avoid
> writing. The problem with my approach of attaching a Tech Writer to
> the programmer is that it's expensive, and you have to have some Tech
> Writers on staff to assign.
It may be that "written materials" are not valued! E.g., the tiny
user manual for our washing machine (big company!) is full of errors
and "bad translations". Is this because they have crappy staff? Or,
because they figure they don't NEED to invest in these tasks as
*Users* never read this stuff, anyway!?
(How many folks have read the LENGTHY "user manual" that accompanies
most new automobiles? Or, the instructions for their cell phone?
Or, the manual for their VCR/DVR/washing machine/computer/programs/etc?
Why invest the time in preparing a document if its never going to be
read?)
>>> They are always very technical, but in the domain of the standard.
>>> Usually they are also comfortable with the editing tools, such as
>>> Frame.
>>
>> So, they just need to be conditioned to adopt a consistent tagging
>> methodology. Probably difficult (getting agreement) in such a large
>> "organization". OTOH, probably easier to *enforce*! :>
>
> The problem isn't that they are stupid. The problem is that they
> usually don't see the reason to go to the trouble., and it's painful to
> learn without the background.
>
> In the case of teaching stack order to typists, they were willing
> because making tables and nested tables was driving them nuts, so they
> had motive.
I am relying on the same approach with my docs! Have the documents
play a key role in the design of the product so that the path of
least resistance is to keep the documents up to date. Make it
more tedious for the next developer to work *around* the documents
than it would be to work THROUGH them!
>> I think it has a lot of value as the documents become more tightly
>> integrated with the products. Currently, most massaging of
>> documents happens in the design (and documentation) phases. Once
>> created, they tend to be largely static and "ancillary" items.
>> E.g., the product never actively references them or incorporates
>> them into its nominal operation.
>
>> All these "advances" are obviously geared towards making documents
>> more useful and more of a "product resource".
>
> Yes. But it is always an investment decision.
That's the point -- make it an investment that has a real payoff!
E.g., automates some of the code generation; or, addresses some
portion of the "user documentation" that will eventually need to be
prepared, etc. So there is an incentive to preparing and maintaining
the documents!
On 8/16/2014 11:17 AM, Joe Gwinn wrote:
[very proficient/creator --> familiar/technician --> document prep guy]
>> I.e., split the effort into different sets of skills to get from
>> A to B (via C).
>
> Well, yes, and that's the point of my little war story. The fact that
> the programmer was Chinese only strengthens the example.
EXCELLENT way of filling in the "middle position" in the above chain.
It allows that individual to become (intimately!) familiar with your
products without having the responsibility of making design or
implementation decisions. And, encourages building writing and
communication skills in the process. Likewise, has prepared him/her
for the eventual "very proficient" role in which he/she will have to
be aware that others will be trying to DECIPHER and EXPLAIN his/her
design/implementation decisions!
I.e., the value of consistency in the design as evidenced by teh
relative ease with which a consistent design methodology can more
readily be documented/explained (hopefully, a lesson he/she learned
while filling that middle role!)
>> Most programmers/engineers are lousy writers -- they tend to forget
>> who they are talking to as well as the types of issues that may be
>> important to that audience.
>
> It's because we in the US no longer teach writing in High School and
> before. Writing is work, and there is an artifice to be learned. We
> don't teach grammar either.
bit of emphasis on "English" throughout elementary and junior/senior
high schools. E.g., you couldn't be awarded a high school diploma
without having had 4 years of English -- the same was not true of
Math, Science, etc.!
> By the way, we are not talking about being able to write the Great
> American Novel. We are talking about writing a simple descriptive
> paper.
something. You have to be able to see The Big Picture and come
up with a strategy for describing The Whole Enchilada. You don't
want to write several discrete, distinct chapters that don't "fit"
well together.
E.g., the first writing contract I took on was to document an
existing device (for which the exiting documentation was universally
recognized as abysmal, incorrect, out-of-date, etc.).
Not knowing anything about the device, I had to first familiarize myself
with it, how it would be used, the types of things you would want to
do with it, the types of details you would likely *forget* (without
continued exposure), etc. I.e., if *I* owned one of these, what would
*I* want the documentation to look like?
My prose ended up very stilted -- more like the "classic" technical
writing style (dry, as if enumerating facts). But, to my credit,
I was told old customers were cold calling *requesting* to BUY copies
of the "new manual"! The gentleman who provided support for the
device commented, "There hasn't been anything that I have been UNable
to find in the manual!" I guess a testament to the structure I laid
out for the document, the actual "presentation", depth of index, etc.
You knew *where* to look for whatever it is you sought!
Since then, I've been concentrating on how to "soften" my prose and
make it more "conversational" -- lead the reader to a specific
understanding instead of bombarding him with a set of "facts".
> I heard from a colleague that a standard test used to qualify
> candidates for a Technical Writing job - ask the candidate to write an
> instruction sheet on how to tie one's shoes.
(did you remember to pull off to the side of the road? OPEN the
door before getting out? How are you watching for oncoming traffic
WHILE you are focused on removing the flat? etc.)
> Teaching writing is expensive, because the student-teacher ratio cannot
> exceed ten, or the teacher won't have time to do the detailed
> correction that's needed. One of the big distinctions between US
> public (tax supported) and private (parents pay) schools is that
> private schools all teach how to write.
sentence properly (though I have a persistent problem with spelling...
especially doubling consonants! :< )
I think a bigger problem is people's inability to organize their
thoughts, well. Hand someone a piece of paper and tell them to
write a piece of code, a story, etc. and they will stare at it,
unable to begin.
Give them an EXISTING piece of code, story/outline, etc. and they'll
usually have no problem "fleshing it out"!
>> Similarly, most *writers* (e.g., Lit/English majors) have no concept
>> of the technology that is being presented.
>
> Hence they babble, or balk.
aforementioned chain) could "translate" the technical issues into
something resembling "English"; then, someone skilled in writing
and document prep could translate *that* into REAL English -- without
really having to "understand" it!
>> I think you have to go from hand to hand (to hand) to get to a
>> finished document product. This is hard to do in small shops who
>> probably don't treat documentation as anything more than a checkoff
>> item. (some of the manuals I've read are abysmal! even from large
>> multibillion dollar corporations -- as if they assumed no one would
>> ever READ them so why bother putting any effort into WRITING them?!)
>
> There is the key. It isn't valued. And, as you mention most
> programmers are terrible writers, so they will use any excuse to avoid
> writing. The problem with my approach of attaching a Tech Writer to
> the programmer is that it's expensive, and you have to have some Tech
> Writers on staff to assign.
user manual for our washing machine (big company!) is full of errors
and "bad translations". Is this because they have crappy staff? Or,
because they figure they don't NEED to invest in these tasks as
*Users* never read this stuff, anyway!?
(How many folks have read the LENGTHY "user manual" that accompanies
most new automobiles? Or, the instructions for their cell phone?
Or, the manual for their VCR/DVR/washing machine/computer/programs/etc?
Why invest the time in preparing a document if its never going to be
read?)
>>> They are always very technical, but in the domain of the standard.
>>> Usually they are also comfortable with the editing tools, such as
>>> Frame.
>>
>> So, they just need to be conditioned to adopt a consistent tagging
>> methodology. Probably difficult (getting agreement) in such a large
>> "organization". OTOH, probably easier to *enforce*! :>
>
> The problem isn't that they are stupid. The problem is that they
> usually don't see the reason to go to the trouble., and it's painful to
> learn without the background.
>
> In the case of teaching stack order to typists, they were willing
> because making tables and nested tables was driving them nuts, so they
> had motive.
play a key role in the design of the product so that the path of
least resistance is to keep the documents up to date. Make it
more tedious for the next developer to work *around* the documents
than it would be to work THROUGH them!
>> I think it has a lot of value as the documents become more tightly
>> integrated with the products. Currently, most massaging of
>> documents happens in the design (and documentation) phases. Once
>> created, they tend to be largely static and "ancillary" items.
>> E.g., the product never actively references them or incorporates
>> them into its nominal operation.
>
>> All these "advances" are obviously geared towards making documents
>> more useful and more of a "product resource".
>
> Yes. But it is always an investment decision.
E.g., automates some of the code generation; or, addresses some
portion of the "user documentation" that will eventually need to be
prepared, etc. So there is an incentive to preparing and maintaining
the documents!
Don Y
Aug 16, 2014, 5:43:12 PM8/16/14
to
Hi Joe,
On 8/16/2014 2:01 PM, Joe Gwinn wrote:
> In article<31fvu9ll2dcv92a22...@4ax.com>,
> <k...@attt.bizz> wrote:
>>> By the way, we are not talking about being able to write the Great
>>> American Novel. We are talking about writing a simple descriptive
>>> paper. I heard from a colleague that a standard test used to qualify
>>> candidates for a Technical Writing job - ask the candidate to write an
>>> instruction sheet on how to tie one's shoes.
>>
>> Good plan but don't expect the average engineer to do it. It's not
>> their specialty (among a whole host of other reasons).
>
> And it cripples them. I see it every day.
Writing == communication. If you can't "build" an explanation
(or "argument") on paper, you probably can't build it with the
spoken word, either! How do you organize your THOUGHTS if you
can't organize your *words*?
Listen to how those around you explain things that are of personal
interest to them (or, work-related experiences) to others. Do they
cling to their own, application-specific terminology? Magically
expecting everyone around them to understand their technical
shorthand? Or, do they make an effort to relate their subject in
terms that their audience is *likely* to understand?
I had a lady coworker once jokingly berate me for explaining
computer-related issues using *kitchen* analogies -- as if I
was being misogynistic! So, the next "problem" she presented
to me I opted to matter-of-factly explain in "bedroom" analogies.
When she had achieved a suitably uniform shade of RED, I paused
and waited for her to suggest I return to the kitchen domain,
again! :>
But, in each case, she ended up understanding the issue that
others had tried explaining/resolving with techno-babble.
On 8/16/2014 2:01 PM, Joe Gwinn wrote:
> In article<31fvu9ll2dcv92a22...@4ax.com>,
> <k...@attt.bizz> wrote:
>>> By the way, we are not talking about being able to write the Great
>>> American Novel. We are talking about writing a simple descriptive
>>> paper. I heard from a colleague that a standard test used to qualify
>>> candidates for a Technical Writing job - ask the candidate to write an
>>> instruction sheet on how to tie one's shoes.
>>
>> Good plan but don't expect the average engineer to do it. It's not
>> their specialty (among a whole host of other reasons).
>
> And it cripples them. I see it every day.
(or "argument") on paper, you probably can't build it with the
spoken word, either! How do you organize your THOUGHTS if you
can't organize your *words*?
Listen to how those around you explain things that are of personal
interest to them (or, work-related experiences) to others. Do they
cling to their own, application-specific terminology? Magically
expecting everyone around them to understand their technical
shorthand? Or, do they make an effort to relate their subject in
terms that their audience is *likely* to understand?
I had a lady coworker once jokingly berate me for explaining
computer-related issues using *kitchen* analogies -- as if I
was being misogynistic! So, the next "problem" she presented
to me I opted to matter-of-factly explain in "bedroom" analogies.
When she had achieved a suitably uniform shade of RED, I paused
and waited for her to suggest I return to the kitchen domain,
again! :>
But, in each case, she ended up understanding the issue that
others had tried explaining/resolving with techno-babble.
Joe Gwinn
Aug 16, 2014, 6:04:21 PM8/16/14
to
In article <lsoj9d$246$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
> Hi Joe,
>
> On 8/16/2014 2:01 PM, Joe Gwinn wrote:
> > In article<31fvu9ll2dcv92a22...@4ax.com>,
> > <k...@attt.bizz> wrote:
> >>> By the way, we are not talking about being able to write the Great
> >>> American Novel. We are talking about writing a simple descriptive
> >>> paper. I heard from a colleague that a standard test used to qualify
> >>> candidates for a Technical Writing job - ask the candidate to write an
> >>> instruction sheet on how to tie one's shoes.
> >>
> >> Good plan but don't expect the average engineer to do it. It's not
> >> their specialty (among a whole host of other reasons).
> >
> > And it cripples them. I see it every day.
>
> Writing == communication. If you can't "build" an explanation
> (or "argument") on paper, you probably can't build it with the
> spoken word, either! How do you organize your THOUGHTS if you
> can't organize your *words*?
Actually, I usually write an analytical and/or tutorial memo while
solving a problem because I find it helps me to clarify my thinking.
And I get a nice memo out of it.
> Listen to how those around you explain things that are of personal
> interest to them (or, work-related experiences) to others. Do they
> cling to their own, application-specific terminology? Magically
> expecting everyone around them to understand their technical
> shorthand? Or, do they make an effort to relate their subject in
> terms that their audience is *likely* to understand?
>
> I had a lady coworker once jokingly berate me for explaining
> computer-related issues using *kitchen* analogies -- as if I
> was being misogynistic! So, the next "problem" she presented
> to me I opted to matter-of-factly explain in "bedroom" analogies.
> When she had achieved a suitably uniform shade of RED, I paused
> and waited for her to suggest I return to the kitchen domain,
> again! :>
>
> But, in each case, she ended up understanding the issue that
> others had tried explaining/resolving with techno-babble.
Would have been fun to watch. You must have known her well, to get
away with that.
Don't think I'll try that approach. It would probably end badly - the
lawyers would be babbling something about creating a hostile
environment as the guards frog-marched me out the door.
Joe Gwinn
wrote:
> Hi Joe,
>
> On 8/16/2014 2:01 PM, Joe Gwinn wrote:
> > In article<31fvu9ll2dcv92a22...@4ax.com>,
> > <k...@attt.bizz> wrote:
> >>> By the way, we are not talking about being able to write the Great
> >>> American Novel. We are talking about writing a simple descriptive
> >>> paper. I heard from a colleague that a standard test used to qualify
> >>> candidates for a Technical Writing job - ask the candidate to write an
> >>> instruction sheet on how to tie one's shoes.
> >>
> >> Good plan but don't expect the average engineer to do it. It's not
> >> their specialty (among a whole host of other reasons).
> >
> > And it cripples them. I see it every day.
>
> Writing == communication. If you can't "build" an explanation
> (or "argument") on paper, you probably can't build it with the
> spoken word, either! How do you organize your THOUGHTS if you
> can't organize your *words*?
solving a problem because I find it helps me to clarify my thinking.
And I get a nice memo out of it.
> Listen to how those around you explain things that are of personal
> interest to them (or, work-related experiences) to others. Do they
> cling to their own, application-specific terminology? Magically
> expecting everyone around them to understand their technical
> shorthand? Or, do they make an effort to relate their subject in
> terms that their audience is *likely* to understand?
>
> I had a lady coworker once jokingly berate me for explaining
> computer-related issues using *kitchen* analogies -- as if I
> was being misogynistic! So, the next "problem" she presented
> to me I opted to matter-of-factly explain in "bedroom" analogies.
> When she had achieved a suitably uniform shade of RED, I paused
> and waited for her to suggest I return to the kitchen domain,
> again! :>
>
> But, in each case, she ended up understanding the issue that
> others had tried explaining/resolving with techno-babble.
away with that.
Don't think I'll try that approach. It would probably end badly - the
lawyers would be babbling something about creating a hostile
environment as the guards frog-marched me out the door.
Joe Gwinn
Joe Gwinn
Aug 16, 2014, 6:20:58 PM8/16/14
to
In article <lsohdj$u3t$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
> Hi Joe,
>
> On 8/16/2014 11:17 AM, Joe Gwinn wrote:
>
> [very proficient/creator --> familiar/technician --> document prep guy]
>
> >> I.e., split the effort into different sets of skills to get from
> >> A to B (via C).
> >
> > Well, yes, and that's the point of my little war story. The fact that
> > the programmer was Chinese only strengthens the example.
>
> I would think using "fresh hires", "junior staff", etc. would be an
> EXCELLENT way of filling in the "middle position" in the above chain.
> It allows that individual to become (intimately!) familiar with your
> products without having the responsibility of making design or
> implementation decisions. And, encourages building writing and
> communication skills in the process. Likewise, has prepared him/her
> for the eventual "very proficient" role in which he/she will have to
> be aware that others will be trying to DECIPHER and EXPLAIN his/her
> design/implementation decisions!
>
> I.e., the value of consistency in the design as evidenced by the
babble as badly as the English majors, only slightly more plausibly.
> >> Most programmers/engineers are lousy writers -- they tend to forget
> >> who they are talking to as well as the types of issues that may be
> >> important to that audience.
> >
> > It's because we in the US no longer teach writing in High School and
> > before. Writing is work, and there is an artifice to be learned. We
> > don't teach grammar either.
>
> Dunno. School, for me, was many decades ago. But, I recall a fair
> bit of emphasis on "English" throughout elementary and junior/senior
> high schools. E.g., you couldn't be awarded a high school diploma
> without having had 4 years of English -- the same was not true of
> Math, Science, etc.!
The requirement is still something like four years of English. What
varies is the content of "English".
> > By the way, we are not talking about being able to write the Great
> > American Novel. We are talking about writing a simple descriptive
> > paper.
>
> Correct. But, IMO, it's more than just being able to describe
> something. You have to be able to see The Big Picture and come
> up with a strategy for describing The Whole Enchilada. You don't
> want to write several discrete, distinct chapters that don't "fit"
> well together.
Well, yes. But if that cannot do the simple description, they will not
be doing the grand sweep either.
> E.g., the first writing contract I took on was to document an
> existing device (for which the exiting documentation was universally
> recognized as abysmal, incorrect, out-of-date, etc.).
>
> Not knowing anything about the device, I had to first familiarize myself
> with it, how it would be used, the types of things you would want to
> do with it, the types of details you would likely *forget* (without
> continued exposure), etc. I.e., if *I* owned one of these, what would
> *I* want the documentation to look like?
>
> My prose ended up very stilted -- more like the "classic" technical
> writing style (dry, as if enumerating facts). But, to my credit,
> I was told old customers were cold calling *requesting* to BUY copies
> of the "new manual"! The gentleman who provided support for the
> device commented, "There hasn't been anything that I have been UNable
> to find in the manual!" I guess a testament to the structure I laid
> out for the document, the actual "presentation", depth of index, etc.
>
> You knew *where* to look for whatever it is you sought!
>
> Since then, I've been concentrating on how to "soften" my prose and
> make it more "conversational" -- lead the reader to a specific
> understanding instead of bombarding him with a set of "facts".
I'm glad to hear this, but my immediate reaction was that you were
fortunate to have a boss who was willing to pay for your education.
> > I heard from a colleague that a standard test used to qualify
> > candidates for a Technical Writing job - ask the candidate to write an
> > instruction sheet on how to tie one's shoes.
>
> Sensible. I always used "change a tire" as a programming "test"
> (did you remember to pull off to the side of the road? OPEN the
> door before getting out? How are you watching for oncoming traffic
> WHILE you are focused on removing the flat? etc.)
Yep.
This isn't a writing test, but another colleague of mine tested the
knowledge of UNIX system admins and programmers by giving them a piece
of paper and asking them to describe and diagram the boot sequence of
UNIX. This is a very effective filter.
> > Teaching writing is expensive, because the student-teacher ratio cannot
> > exceed ten, or the teacher won't have time to do the detailed
> > correction that's needed. One of the big distinctions between US
> > public (tax supported) and private (parents pay) schools is that
> > private schools all teach how to write.
>
> <frown> No idea. I went to public schools and *think* I can build a
> sentence properly (though I have a persistent problem with spelling...
> especially doubling consonants! :< )
>
> I think a bigger problem is people's inability to organize their
> thoughts, well. Hand someone a piece of paper and tell them to
> write a piece of code, a story, etc. and they will stare at it,
> unable to begin.
>
> Give them an EXISTING piece of code, story/outline, etc. and they'll
> usually have no problem "fleshing it out"!
This is a different problem. Teaching someone how to write does not
ensure that they have anything to say.
> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> >> of the technology that is being presented.
> >
> > Hence they babble, or balk.
>
> I was thinking that the "junior programmer" (middle person in the
> aforementioned chain) could "translate" the technical issues into
> something resembling "English"; then, someone skilled in writing
> and document prep could translate *that* into REAL English -- without
> really having to "understand" it!
As discussed above, it takes a while before the college hires figure
things out.
> >> I think you have to go from hand to hand (to hand) to get to a
> >> finished document product. This is hard to do in small shops who
> >> probably don't treat documentation as anything more than a checkoff
> >> item. (some of the manuals I've read are abysmal! even from large
> >> multibillion dollar corporations -- as if they assumed no one would
> >> ever READ them so why bother putting any effort into WRITING them?!)
> >
> > There is the key. It isn't valued. And, as you mention most
> > programmers are terrible writers, so they will use any excuse to avoid
> > writing. The problem with my approach of attaching a Tech Writer to
> > the programmer is that it's expensive, and you have to have some Tech
> > Writers on staff to assign.
>
> It may be that "written materials" are not valued! E.g., the tiny
> user manual for our washing machine (big company!) is full of errors
> and "bad translations". Is this because they have crappy staff? Or,
> because they figure they don't NEED to invest in these tasks as
> *Users* never read this stuff, anyway!?
>
> (How many folks have read the LENGTHY "user manual" that accompanies
> most new automobiles? Or, the instructions for their cell phone?
> Or, the manual for their VCR/DVR/washing machine/computer/programs/etc?
> Why invest the time in preparing a document if its never going to be
> read?)
There is an air of circularity here. If the manual is worthless, why
read it? If people don't read manuals, why write good ones?
Some companies are famous for good documentation, and some are famous
for the converse. I've never heard of a company that dies because
their documentation was bad.
Joe Gwinn
wrote:
> Hi Joe,
>
> On 8/16/2014 11:17 AM, Joe Gwinn wrote:
>
> [very proficient/creator --> familiar/technician --> document prep guy]
>
> >> I.e., split the effort into different sets of skills to get from
> >> A to B (via C).
> >
> > Well, yes, and that's the point of my little war story. The fact that
> > the programmer was Chinese only strengthens the example.
>
> I would think using "fresh hires", "junior staff", etc. would be an
> EXCELLENT way of filling in the "middle position" in the above chain.
> It allows that individual to become (intimately!) familiar with your
> products without having the responsibility of making design or
> implementation decisions. And, encourages building writing and
> communication skills in the process. Likewise, has prepared him/her
> for the eventual "very proficient" role in which he/she will have to
> be aware that others will be trying to DECIPHER and EXPLAIN his/her
> design/implementation decisions!
>
> relative ease with which a consistent design methodology can more
> readily be documented/explained (hopefully, a lesson he/she learned
> while filling that middle role!)
The college hires don't yet know enough for that to work, and will
> readily be documented/explained (hopefully, a lesson he/she learned
> while filling that middle role!)
babble as badly as the English majors, only slightly more plausibly.
> >> Most programmers/engineers are lousy writers -- they tend to forget
> >> who they are talking to as well as the types of issues that may be
> >> important to that audience.
> >
> > It's because we in the US no longer teach writing in High School and
> > before. Writing is work, and there is an artifice to be learned. We
> > don't teach grammar either.
>
> Dunno. School, for me, was many decades ago. But, I recall a fair
> bit of emphasis on "English" throughout elementary and junior/senior
> high schools. E.g., you couldn't be awarded a high school diploma
> without having had 4 years of English -- the same was not true of
> Math, Science, etc.!
varies is the content of "English".
> > By the way, we are not talking about being able to write the Great
> > American Novel. We are talking about writing a simple descriptive
> > paper.
>
> Correct. But, IMO, it's more than just being able to describe
> something. You have to be able to see The Big Picture and come
> up with a strategy for describing The Whole Enchilada. You don't
> want to write several discrete, distinct chapters that don't "fit"
> well together.
be doing the grand sweep either.
> E.g., the first writing contract I took on was to document an
> existing device (for which the exiting documentation was universally
> recognized as abysmal, incorrect, out-of-date, etc.).
>
> Not knowing anything about the device, I had to first familiarize myself
> with it, how it would be used, the types of things you would want to
> do with it, the types of details you would likely *forget* (without
> continued exposure), etc. I.e., if *I* owned one of these, what would
> *I* want the documentation to look like?
>
> My prose ended up very stilted -- more like the "classic" technical
> writing style (dry, as if enumerating facts). But, to my credit,
> I was told old customers were cold calling *requesting* to BUY copies
> of the "new manual"! The gentleman who provided support for the
> device commented, "There hasn't been anything that I have been UNable
> to find in the manual!" I guess a testament to the structure I laid
> out for the document, the actual "presentation", depth of index, etc.
>
> You knew *where* to look for whatever it is you sought!
>
> Since then, I've been concentrating on how to "soften" my prose and
> make it more "conversational" -- lead the reader to a specific
> understanding instead of bombarding him with a set of "facts".
fortunate to have a boss who was willing to pay for your education.
> > I heard from a colleague that a standard test used to qualify
> > candidates for a Technical Writing job - ask the candidate to write an
> > instruction sheet on how to tie one's shoes.
>
> Sensible. I always used "change a tire" as a programming "test"
> (did you remember to pull off to the side of the road? OPEN the
> door before getting out? How are you watching for oncoming traffic
> WHILE you are focused on removing the flat? etc.)
This isn't a writing test, but another colleague of mine tested the
knowledge of UNIX system admins and programmers by giving them a piece
of paper and asking them to describe and diagram the boot sequence of
UNIX. This is a very effective filter.
> > Teaching writing is expensive, because the student-teacher ratio cannot
> > exceed ten, or the teacher won't have time to do the detailed
> > correction that's needed. One of the big distinctions between US
> > public (tax supported) and private (parents pay) schools is that
> > private schools all teach how to write.
>
> <frown> No idea. I went to public schools and *think* I can build a
> sentence properly (though I have a persistent problem with spelling...
> especially doubling consonants! :< )
>
> I think a bigger problem is people's inability to organize their
> thoughts, well. Hand someone a piece of paper and tell them to
> write a piece of code, a story, etc. and they will stare at it,
> unable to begin.
>
> Give them an EXISTING piece of code, story/outline, etc. and they'll
> usually have no problem "fleshing it out"!
ensure that they have anything to say.
> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> >> of the technology that is being presented.
> >
> > Hence they babble, or balk.
>
> I was thinking that the "junior programmer" (middle person in the
> aforementioned chain) could "translate" the technical issues into
> something resembling "English"; then, someone skilled in writing
> and document prep could translate *that* into REAL English -- without
> really having to "understand" it!
things out.
> >> I think you have to go from hand to hand (to hand) to get to a
> >> finished document product. This is hard to do in small shops who
> >> probably don't treat documentation as anything more than a checkoff
> >> item. (some of the manuals I've read are abysmal! even from large
> >> multibillion dollar corporations -- as if they assumed no one would
> >> ever READ them so why bother putting any effort into WRITING them?!)
> >
> > There is the key. It isn't valued. And, as you mention most
> > programmers are terrible writers, so they will use any excuse to avoid
> > writing. The problem with my approach of attaching a Tech Writer to
> > the programmer is that it's expensive, and you have to have some Tech
> > Writers on staff to assign.
>
> It may be that "written materials" are not valued! E.g., the tiny
> user manual for our washing machine (big company!) is full of errors
> and "bad translations". Is this because they have crappy staff? Or,
> because they figure they don't NEED to invest in these tasks as
> *Users* never read this stuff, anyway!?
>
> (How many folks have read the LENGTHY "user manual" that accompanies
> most new automobiles? Or, the instructions for their cell phone?
> Or, the manual for their VCR/DVR/washing machine/computer/programs/etc?
> Why invest the time in preparing a document if its never going to be
> read?)
read it? If people don't read manuals, why write good ones?
for the converse. I've never heard of a company that dies because
their documentation was bad.
Joe Gwinn
Don Y
Aug 16, 2014, 6:53:34 PM8/16/14
to
Hi Joe,
On 8/16/2014 3:04 PM, Joe Gwinn wrote:
>>>>> By the way, we are not talking about being able to write the Great
>>>>> American Novel. We are talking about writing a simple descriptive
>>>>> paper. I heard from a colleague that a standard test used to qualify
>>>>> candidates for a Technical Writing job - ask the candidate to write an
>>>>> instruction sheet on how to tie one's shoes.
>>>>
>>>> Good plan but don't expect the average engineer to do it. It's not
>>>> their specialty (among a whole host of other reasons).
>>>
>>> And it cripples them. I see it every day.
>>
>> Writing == communication. If you can't "build" an explanation
>> (or "argument") on paper, you probably can't build it with the
>> spoken word, either! How do you organize your THOUGHTS if you
>> can't organize your *words*?
>
> Actually, I usually write an analytical and/or tutorial memo while
> solving a problem because I find it helps me to clarify my thinking.
> And I get a nice memo out of it.
I am dismayed at how much ends up "lost to posterity" due to
inadequate or incorrect documentation. I've been trudging through
many "classic" research papers *chagrined* at the typographical
errors that make them less than (immediately) useful! In some
cases, contacting the original authors has proven difficult/impossible.
And, in other cases, the original author may no longer recollect
some of the fine detail that I am questioning -- and, have little
interest in "investigating" their old works.
So, I'm left with the knowledge that something is (should be?)
"do-able" (allegedly) -- yet not having a clear path to repeat their
prior successes (or, even TEST against them!)
As I want the things I am working on to be "self-supporting"
(i.e., *I* don't want to spend my time answering questions), I
have been attempting to document them in a more "educational"
manner.
It is impractical to document hardware or software in anything more
than a "theory of operation" manner. There's just no provision to
explain and explore alternatives *before* arriving at the eventual
implementation as a "conclusion".
So, I try to build free-standing documents that educate on a particular
aspect of a problem. Then, ASSUME the developer has read these so I
can just refer to their results/conclusions in the hardware/software
documentation -- without having to explain them (again!), there!
>> Listen to how those around you explain things that are of personal
>> interest to them (or, work-related experiences) to others. Do they
>> cling to their own, application-specific terminology? Magically
>> expecting everyone around them to understand their technical
>> shorthand? Or, do they make an effort to relate their subject in
>> terms that their audience is *likely* to understand?
>>
>> I had a lady coworker once jokingly berate me for explaining
>> computer-related issues using *kitchen* analogies -- as if I
>> was being misogynistic! So, the next "problem" she presented
>> to me I opted to matter-of-factly explain in "bedroom" analogies.
>> When she had achieved a suitably uniform shade of RED, I paused
>> and waited for her to suggest I return to the kitchen domain,
>> again! :>
>>
>> But, in each case, she ended up understanding the issue that
>> others had tried explaining/resolving with techno-babble.
>
> Would have been fun to watch. You must have known her well, to get
> away with that.
Yes, you could say that! ;-)
The point is/was, to find a way of explaining an issue in terms
to which the other party will be able to relate! Listen to how
often people try to explain things AS IF they were still "at work"
talking to their peers/superiors.
"And, you expect me to PARTICIPATE in this discussion? How??"
Technical people are particularly bad in this regard. They forget
that language and terminology that are commonplace in their "element"
are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of
that community!
> Don't think I'll try that approach. It would probably end badly - the
> lawyers would be babbling something about creating a hostile
> environment as the guards frog-marched me out the door.
Yeah, nowadays, the workplace is far less tolerant of this sort of
stuff! Sad as this sort of familiar/casual interaction can be
great at tearing down boundaries between people/groups. I.e.,
"being able to take a joke"...
On 8/16/2014 3:04 PM, Joe Gwinn wrote:
>>>>> By the way, we are not talking about being able to write the Great
>>>>> American Novel. We are talking about writing a simple descriptive
>>>>> paper. I heard from a colleague that a standard test used to qualify
>>>>> candidates for a Technical Writing job - ask the candidate to write an
>>>>> instruction sheet on how to tie one's shoes.
>>>>
>>>> Good plan but don't expect the average engineer to do it. It's not
>>>> their specialty (among a whole host of other reasons).
>>>
>>> And it cripples them. I see it every day.
>>
>> Writing == communication. If you can't "build" an explanation
>> (or "argument") on paper, you probably can't build it with the
>> spoken word, either! How do you organize your THOUGHTS if you
>> can't organize your *words*?
>
> Actually, I usually write an analytical and/or tutorial memo while
> solving a problem because I find it helps me to clarify my thinking.
> And I get a nice memo out of it.
inadequate or incorrect documentation. I've been trudging through
many "classic" research papers *chagrined* at the typographical
errors that make them less than (immediately) useful! In some
cases, contacting the original authors has proven difficult/impossible.
And, in other cases, the original author may no longer recollect
some of the fine detail that I am questioning -- and, have little
interest in "investigating" their old works.
So, I'm left with the knowledge that something is (should be?)
"do-able" (allegedly) -- yet not having a clear path to repeat their
prior successes (or, even TEST against them!)
As I want the things I am working on to be "self-supporting"
(i.e., *I* don't want to spend my time answering questions), I
have been attempting to document them in a more "educational"
manner.
It is impractical to document hardware or software in anything more
than a "theory of operation" manner. There's just no provision to
explain and explore alternatives *before* arriving at the eventual
implementation as a "conclusion".
So, I try to build free-standing documents that educate on a particular
aspect of a problem. Then, ASSUME the developer has read these so I
can just refer to their results/conclusions in the hardware/software
documentation -- without having to explain them (again!), there!
>> Listen to how those around you explain things that are of personal
>> interest to them (or, work-related experiences) to others. Do they
>> cling to their own, application-specific terminology? Magically
>> expecting everyone around them to understand their technical
>> shorthand? Or, do they make an effort to relate their subject in
>> terms that their audience is *likely* to understand?
>>
>> I had a lady coworker once jokingly berate me for explaining
>> computer-related issues using *kitchen* analogies -- as if I
>> was being misogynistic! So, the next "problem" she presented
>> to me I opted to matter-of-factly explain in "bedroom" analogies.
>> When she had achieved a suitably uniform shade of RED, I paused
>> and waited for her to suggest I return to the kitchen domain,
>> again! :>
>>
>> But, in each case, she ended up understanding the issue that
>> others had tried explaining/resolving with techno-babble.
>
> Would have been fun to watch. You must have known her well, to get
> away with that.
The point is/was, to find a way of explaining an issue in terms
to which the other party will be able to relate! Listen to how
often people try to explain things AS IF they were still "at work"
talking to their peers/superiors.
"And, you expect me to PARTICIPATE in this discussion? How??"
Technical people are particularly bad in this regard. They forget
that language and terminology that are commonplace in their "element"
are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of
that community!
> Don't think I'll try that approach. It would probably end badly - the
> lawyers would be babbling something about creating a hostile
> environment as the guards frog-marched me out the door.
stuff! Sad as this sort of familiar/casual interaction can be
great at tearing down boundaries between people/groups. I.e.,
"being able to take a joke"...
Don Y
Aug 16, 2014, 7:47:41 PM8/16/14
to
Hi Joe,
On 8/16/2014 3:20 PM, Joe Gwinn wrote:
>> [very proficient/creator --> familiar/technician --> document prep guy]
>>
>>>> I.e., split the effort into different sets of skills to get from
>>>> A to B (via C).
>>>
>>> Well, yes, and that's the point of my little war story. The fact that
>>> the programmer was Chinese only strengthens the example.
>>
>> I would think using "fresh hires", "junior staff", etc. would be an
>> EXCELLENT way of filling in the "middle position" in the above chain.
>> It allows that individual to become (intimately!) familiar with your
>> products without having the responsibility of making design or
>> implementation decisions. And, encourages building writing and
>> communication skills in the process. Likewise, has prepared him/her
>> for the eventual "very proficient" role in which he/she will have to
>> be aware that others will be trying to DECIPHER and EXPLAIN his/her
>> design/implementation decisions!
>>
>> I.e., the value of consistency in the design as evidenced by the
>> relative ease with which a consistent design methodology can more
>> readily be documented/explained (hopefully, a lesson he/she learned
>> while filling that middle role!)
>
> The college hires don't yet know enough for that to work, and will
> babble as badly as the English majors, only slightly more plausibly.
<frown> Perhaps I have the benefit of having been surrounded by
"more adept" peers? If I restricted my selection to those with
English as their native language, *any* of the folks I went to
school (college) with could easily do this -- AND, appreciate the
logic behind it.
It might take some time for them to develop a good "approach" to
each assignment (i.e., avoid the temptation to start at "main()"
and describe the code sequentially). But, I think they would be
smart enough to know not to (for example) just repackage the comments
that accompany the code!
>>>> Most programmers/engineers are lousy writers -- they tend to forget
>>>> who they are talking to as well as the types of issues that may be
>>>> important to that audience.
>>>
>>> It's because we in the US no longer teach writing in High School and
>>> before. Writing is work, and there is an artifice to be learned. We
>>> don't teach grammar either.
>>
>> Dunno. School, for me, was many decades ago. But, I recall a fair
>> bit of emphasis on "English" throughout elementary and junior/senior
>> high schools. E.g., you couldn't be awarded a high school diploma
>> without having had 4 years of English -- the same was not true of
>> Math, Science, etc.!
>
> The requirement is still something like four years of English. What
> varies is the content of "English".
Again, I guess I can't imagine what it could be *other* than "reading
and writing". At the end of my High School stint, they were starting
to introduce courses like "Film Appreciation", etc. -- but, those
were distinctly *not* "English".
I recall there was an emphasis on American Literature -- one year
in High School and another in Jr High. Ditto American History.
I was actually surprised, in college, to encounter other "Americans"
who had not had these exposures! I.e., I deliberately chose courses
of similar titles for college "electives" knowing that I had already
seen much of that material, before! :-/
>> E.g., the first writing contract I took on was to document an
>> existing device (for which the exiting documentation was universally
>> recognized as abysmal, incorrect, out-of-date, etc.).
>>
>> Not knowing anything about the device, I had to first familiarize myself
>> with it, how it would be used, the types of things you would want to
>> do with it, the types of details you would likely *forget* (without
>> continued exposure), etc. I.e., if *I* owned one of these, what would
>> *I* want the documentation to look like?
>>
>> My prose ended up very stilted -- more like the "classic" technical
>> writing style (dry, as if enumerating facts). But, to my credit,
>> I was told old customers were cold calling *requesting* to BUY copies
>> of the "new manual"! The gentleman who provided support for the
>> device commented, "There hasn't been anything that I have been UNable
>> to find in the manual!" I guess a testament to the structure I laid
>> out for the document, the actual "presentation", depth of index, etc.
>>
>> You knew *where* to look for whatever it is you sought!
>>
>> Since then, I've been concentrating on how to "soften" my prose and
>> make it more "conversational" -- lead the reader to a specific
>> understanding instead of bombarding him with a set of "facts".
>
> I'm glad to hear this, but my immediate reaction was that you were
> fortunate to have a boss who was willing to pay for your education.
The client gave me the opportunity to learn (by awarding me a project
that required this skillset). The learning came out of my pocket as
the job was essentially fixed cost (they got a GREAT deal as I prepared
dozens of illustrations, schematics, code samples, etc. and documented
*hundreds* of bugs in the product -- clearly not part of the "intended"
contract but you uncover ALL the behavior if you are trying to be
exhaustive in your documentation!).
There was exactly *one* pass through the process. My first draft
was the *final* draft. (I am very thorough :> )
>>> Teaching writing is expensive, because the student-teacher ratio cannot
>>> exceed ten, or the teacher won't have time to do the detailed
>>> correction that's needed. One of the big distinctions between US
>>> public (tax supported) and private (parents pay) schools is that
>>> private schools all teach how to write.
>>
>> <frown> No idea. I went to public schools and *think* I can build a
>> sentence properly (though I have a persistent problem with spelling...
>> especially doubling consonants! :< )
>>
>> I think a bigger problem is people's inability to organize their
>> thoughts, well. Hand someone a piece of paper and tell them to
>> write a piece of code, a story, etc. and they will stare at it,
>> unable to begin.
>>
>> Give them an EXISTING piece of code, story/outline, etc. and they'll
>> usually have no problem "fleshing it out"!
>
> This is a different problem. Teaching someone how to write does not
> ensure that they have anything to say.
I see knowing how to *approach* a problem (whether it is writing a piece
of code, designing a circuit or documenting a device/interface) as a
necessary skill to effectively complete the task "unassisted". If
you can't sort out how you are going to "pitch" some information to
a faceless reader, then, chances are, the reader will end up confused
and find little value in what you end up writing.
>>> There is the key. It isn't valued. And, as you mention most
>>> programmers are terrible writers, so they will use any excuse to avoid
>>> writing. The problem with my approach of attaching a Tech Writer to
>>> the programmer is that it's expensive, and you have to have some Tech
>>> Writers on staff to assign.
>>
>> It may be that "written materials" are not valued! E.g., the tiny
>> user manual for our washing machine (big company!) is full of errors
>> and "bad translations". Is this because they have crappy staff? Or,
>> because they figure they don't NEED to invest in these tasks as
>> *Users* never read this stuff, anyway!?
documentation, will it be VALUED? Will it be consulted? Will
it even be *kept*??
>>>> I think it has a lot of value as the documents become more tightly
>>>> integrated with the products. Currently, most massaging of
>>>> documents happens in the design (and documentation) phases. Once
>>>> created, they tend to be largely static and "ancillary" items.
>>>> E.g., the product never actively references them or incorporates
>>>> them into its nominal operation.
>>>
>>>> All these "advances" are obviously geared towards making documents
>>>> more useful and more of a "product resource".
>>>
>>> Yes. But it is always an investment decision.
>>
>> That's the point -- make it an investment that has a real payoff!
>> E.g., automates some of the code generation; or, addresses some
>> portion of the "user documentation" that will eventually need to be
>> prepared, etc. So there is an incentive to preparing and maintaining
>> the documents!
>
> Some companies are famous for good documentation, and some are famous
> for the converse. I've never heard of a company that dies because
> their documentation was bad.
Yup. The most common metric, currently, seems to be "price".
As such, why do *anything* (documentation, improved product
quality, etc.) that will adversely impact price??
On 8/16/2014 3:20 PM, Joe Gwinn wrote:
>> [very proficient/creator --> familiar/technician --> document prep guy]
>>
>>>> I.e., split the effort into different sets of skills to get from
>>>> A to B (via C).
>>>
>>> Well, yes, and that's the point of my little war story. The fact that
>>> the programmer was Chinese only strengthens the example.
>>
>> I would think using "fresh hires", "junior staff", etc. would be an
>> EXCELLENT way of filling in the "middle position" in the above chain.
>> It allows that individual to become (intimately!) familiar with your
>> products without having the responsibility of making design or
>> implementation decisions. And, encourages building writing and
>> communication skills in the process. Likewise, has prepared him/her
>> for the eventual "very proficient" role in which he/she will have to
>> be aware that others will be trying to DECIPHER and EXPLAIN his/her
>> design/implementation decisions!
>>
>> I.e., the value of consistency in the design as evidenced by the
>> relative ease with which a consistent design methodology can more
>> readily be documented/explained (hopefully, a lesson he/she learned
>> while filling that middle role!)
>
> The college hires don't yet know enough for that to work, and will
> babble as badly as the English majors, only slightly more plausibly.
"more adept" peers? If I restricted my selection to those with
English as their native language, *any* of the folks I went to
school (college) with could easily do this -- AND, appreciate the
logic behind it.
It might take some time for them to develop a good "approach" to
each assignment (i.e., avoid the temptation to start at "main()"
and describe the code sequentially). But, I think they would be
smart enough to know not to (for example) just repackage the comments
that accompany the code!
>>>> Most programmers/engineers are lousy writers -- they tend to forget
>>>> who they are talking to as well as the types of issues that may be
>>>> important to that audience.
>>>
>>> It's because we in the US no longer teach writing in High School and
>>> before. Writing is work, and there is an artifice to be learned. We
>>> don't teach grammar either.
>>
>> Dunno. School, for me, was many decades ago. But, I recall a fair
>> bit of emphasis on "English" throughout elementary and junior/senior
>> high schools. E.g., you couldn't be awarded a high school diploma
>> without having had 4 years of English -- the same was not true of
>> Math, Science, etc.!
>
> The requirement is still something like four years of English. What
> varies is the content of "English".
and writing". At the end of my High School stint, they were starting
to introduce courses like "Film Appreciation", etc. -- but, those
were distinctly *not* "English".
I recall there was an emphasis on American Literature -- one year
in High School and another in Jr High. Ditto American History.
I was actually surprised, in college, to encounter other "Americans"
who had not had these exposures! I.e., I deliberately chose courses
of similar titles for college "electives" knowing that I had already
seen much of that material, before! :-/
>> E.g., the first writing contract I took on was to document an
>> existing device (for which the exiting documentation was universally
>> recognized as abysmal, incorrect, out-of-date, etc.).
>>
>> Not knowing anything about the device, I had to first familiarize myself
>> with it, how it would be used, the types of things you would want to
>> do with it, the types of details you would likely *forget* (without
>> continued exposure), etc. I.e., if *I* owned one of these, what would
>> *I* want the documentation to look like?
>>
>> My prose ended up very stilted -- more like the "classic" technical
>> writing style (dry, as if enumerating facts). But, to my credit,
>> I was told old customers were cold calling *requesting* to BUY copies
>> of the "new manual"! The gentleman who provided support for the
>> device commented, "There hasn't been anything that I have been UNable
>> to find in the manual!" I guess a testament to the structure I laid
>> out for the document, the actual "presentation", depth of index, etc.
>>
>> You knew *where* to look for whatever it is you sought!
>>
>> Since then, I've been concentrating on how to "soften" my prose and
>> make it more "conversational" -- lead the reader to a specific
>> understanding instead of bombarding him with a set of "facts".
>
> I'm glad to hear this, but my immediate reaction was that you were
> fortunate to have a boss who was willing to pay for your education.
that required this skillset). The learning came out of my pocket as
the job was essentially fixed cost (they got a GREAT deal as I prepared
dozens of illustrations, schematics, code samples, etc. and documented
*hundreds* of bugs in the product -- clearly not part of the "intended"
contract but you uncover ALL the behavior if you are trying to be
exhaustive in your documentation!).
There was exactly *one* pass through the process. My first draft
was the *final* draft. (I am very thorough :> )
>>> Teaching writing is expensive, because the student-teacher ratio cannot
>>> exceed ten, or the teacher won't have time to do the detailed
>>> correction that's needed. One of the big distinctions between US
>>> public (tax supported) and private (parents pay) schools is that
>>> private schools all teach how to write.
>>
>> <frown> No idea. I went to public schools and *think* I can build a
>> sentence properly (though I have a persistent problem with spelling...
>> especially doubling consonants! :< )
>>
>> I think a bigger problem is people's inability to organize their
>> thoughts, well. Hand someone a piece of paper and tell them to
>> write a piece of code, a story, etc. and they will stare at it,
>> unable to begin.
>>
>> Give them an EXISTING piece of code, story/outline, etc. and they'll
>> usually have no problem "fleshing it out"!
>
> This is a different problem. Teaching someone how to write does not
> ensure that they have anything to say.
of code, designing a circuit or documenting a device/interface) as a
necessary skill to effectively complete the task "unassisted". If
you can't sort out how you are going to "pitch" some information to
a faceless reader, then, chances are, the reader will end up confused
and find little value in what you end up writing.
>>> There is the key. It isn't valued. And, as you mention most
>>> programmers are terrible writers, so they will use any excuse to avoid
>>> writing. The problem with my approach of attaching a Tech Writer to
>>> the programmer is that it's expensive, and you have to have some Tech
>>> Writers on staff to assign.
>>
>> It may be that "written materials" are not valued! E.g., the tiny
>> user manual for our washing machine (big company!) is full of errors
>> and "bad translations". Is this because they have crappy staff? Or,
>> because they figure they don't NEED to invest in these tasks as
>> *Users* never read this stuff, anyway!?
> There is an air of circularity here. If the manual is worthless, why
> read it? If people don't read manuals, why write good ones?
Exactly! The real question, then, is: if you prepare good
> read it? If people don't read manuals, why write good ones?
documentation, will it be VALUED? Will it be consulted? Will
it even be *kept*??
>>>> I think it has a lot of value as the documents become more tightly
>>>> integrated with the products. Currently, most massaging of
>>>> documents happens in the design (and documentation) phases. Once
>>>> created, they tend to be largely static and "ancillary" items.
>>>> E.g., the product never actively references them or incorporates
>>>> them into its nominal operation.
>>>
>>>> All these "advances" are obviously geared towards making documents
>>>> more useful and more of a "product resource".
>>>
>>> Yes. But it is always an investment decision.
>>
>> That's the point -- make it an investment that has a real payoff!
>> E.g., automates some of the code generation; or, addresses some
>> portion of the "user documentation" that will eventually need to be
>> prepared, etc. So there is an incentive to preparing and maintaining
>> the documents!
>
> Some companies are famous for good documentation, and some are famous
> for the converse. I've never heard of a company that dies because
> their documentation was bad.
As such, why do *anything* (documentation, improved product
quality, etc.) that will adversely impact price??
k...@attt.bizz
Aug 16, 2014, 8:08:46 PM8/16/14
to
On Sat, 16 Aug 2014 17:01:21 -0400, Joe Gwinn <joeg...@comcast.net>
Two things that make your point silly:
1) A Chinese national can't be expected to write a technical English
manual.
2) US citizens of Chinese ancestry often do better in school, English
included, than those of European ancestry.
of the brain. One cannot expect even the best engineer to have the
capability to do technical writing.
>The classic books in any field are almost always written by people who
>are good writers.
Many are horrible writers. Many Textbook authors come to mind. Those
with both skills are a *SMALL* subset of the universe of engineers.
>I have observed that technical books written in the UK are on average
>better written than those written in the US. I gather that this is
>because they still teach all students in the UK how to write, whether
>they want to or not.
Or perhaps that says something about the textbooks you've been exposed
to.
stating that you have data that shows the absolute is true. That's
just silly. Perhaps you're not as good at writing as you think you
are?
>
>> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
>> >> of the technology that is being presented.
>> >
>> >Hence they babble, or balk.
>>
>> Why should they even be asked to venture outside their training?
>
>That was my original point, saying that having the non-engineer writers
>go first won't work. And I've seen it tried.
There *is* such a profession called "technical writer". They're
trained as such. My SIL was one, many moons ago.
>Actually, on a radar system many years ago, I saw the tech manual
>writers struggle to generate anything useful, and so decided it would
>take less of my time if I just sat down and wrote the rough first
>draft. One cannot just deliver muck because the customer verifies the
>usefulness of these documents by trying to follow them.
That doesn't support anything you've said. Of course it's a good idea
to have input from the designers. In fact, the first documents should
come from marketing (what are we trying to build) and the system
architects (how are we going to approach the solution). The designers
may fill in some detail (or not).
the past. It's not some revelation that engineers, in general, are
poor writers. This was true fifty years ago and if what my father
complained about, it was true a generation before that. The two take
a very different set of skills and aptitudes.
<...>
that's needed. Learning context and buttons complicate things a lot
but any bloody idiot should be able to pick up the motion, for
themselves, in a couple of minutes.
>If you want the fuller explanation, read some of the human interface
>guidelines documents from Apple in the 1980s, especially the book by
>Tog (I don't recall his full name, but it will come to me - Tog is a
>clip of his last name).
You're saying that Apple wrote a book about the 2D motion of a mouse?
Perhaps that says something about Apple's customers. If they needed
that book, I'm surprised they were able to read it.
1) A Chinese national can't be expected to write a technical English
manual.
2) US citizens of Chinese ancestry often do better in school, English
included, than those of European ancestry.
>
>> >> Most programmers/engineers are lousy writers -- they tend to forget
>> >> who they are talking to as well as the types of issues that may be
>> >> important to that audience.
>> >
>> >It's because we in the US no longer teach writing in High School and
>> >before. Writing is work, and there is an artifice to be learned. We
>> >don't teach grammar either.
>>
>> No, engineers never made good writers. Technical writing has always
>> been a specialty. The difference is that now there are few companies
>> that want to invest in them so it's too often left to those who aren't
>> qualified.
>
>Some were good writers, some were not. I've met both kinds.
It's a different skill set, one that uses completely different parts
>> >> Most programmers/engineers are lousy writers -- they tend to forget
>> >> who they are talking to as well as the types of issues that may be
>> >> important to that audience.
>> >
>> >It's because we in the US no longer teach writing in High School and
>> >before. Writing is work, and there is an artifice to be learned. We
>> >don't teach grammar either.
>>
>> No, engineers never made good writers. Technical writing has always
>> been a specialty. The difference is that now there are few companies
>> that want to invest in them so it's too often left to those who aren't
>> qualified.
>
>Some were good writers, some were not. I've met both kinds.
of the brain. One cannot expect even the best engineer to have the
capability to do technical writing.
>The classic books in any field are almost always written by people who
>are good writers.
with both skills are a *SMALL* subset of the universe of engineers.
>I have observed that technical books written in the UK are on average
>better written than those written in the US. I gather that this is
>because they still teach all students in the UK how to write, whether
>they want to or not.
to.
>
>> >By the way, we are not talking about being able to write the Great
>> >American Novel. We are talking about writing a simple descriptive
>> >paper. I heard from a colleague that a standard test used to qualify
>> >candidates for a Technical Writing job - ask the candidate to write an
>> >instruction sheet on how to tie one's shoes.
>>
>> Good plan but don't expect the average engineer to do it. It's not
>> their specialty (among a whole host of other reasons).
>
>And it cripples them. I see it every day.
If their job is technical writing, sure. It shouldn't be.
>> >By the way, we are not talking about being able to write the Great
>> >American Novel. We are talking about writing a simple descriptive
>> >paper. I heard from a colleague that a standard test used to qualify
>> >candidates for a Technical Writing job - ask the candidate to write an
>> >instruction sheet on how to tie one's shoes.
>>
>> Good plan but don't expect the average engineer to do it. It's not
>> their specialty (among a whole host of other reasons).
>
>And it cripples them. I see it every day.
>
>> >Teaching writing is expensive, because the student-teacher ratio cannot
>> >exceed ten, or the teacher won't have time to do the detailed
>> >correction that's needed. One of the big distinctions between US
>> >public (tax supported) and private (parents pay) schools is that
>> >private schools all teach how to write.
>>
>> Those are some absolute statements that will require support to be
>> believed.
>
>This is from personal observation and talking to people who went to
>private school. If you need mathematical proof, go right ahead.
"cannot exceed ten" and "private schools all teach" means that you're
>> >Teaching writing is expensive, because the student-teacher ratio cannot
>> >exceed ten, or the teacher won't have time to do the detailed
>> >correction that's needed. One of the big distinctions between US
>> >public (tax supported) and private (parents pay) schools is that
>> >private schools all teach how to write.
>>
>> Those are some absolute statements that will require support to be
>> believed.
>
>This is from personal observation and talking to people who went to
>private school. If you need mathematical proof, go right ahead.
stating that you have data that shows the absolute is true. That's
just silly. Perhaps you're not as good at writing as you think you
are?
>
>> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
>> >> of the technology that is being presented.
>> >
>> >Hence they babble, or balk.
>>
>> Why should they even be asked to venture outside their training?
>
>That was my original point, saying that having the non-engineer writers
>go first won't work. And I've seen it tried.
trained as such. My SIL was one, many moons ago.
>Actually, on a radar system many years ago, I saw the tech manual
>writers struggle to generate anything useful, and so decided it would
>take less of my time if I just sat down and wrote the rough first
>draft. One cannot just deliver muck because the customer verifies the
>usefulness of these documents by trying to follow them.
to have input from the designers. In fact, the first documents should
come from marketing (what are we trying to build) and the system
architects (how are we going to approach the solution). The designers
may fill in some detail (or not).
>
>> >> I think you have to go from hand to hand (to hand) to get to a
>> >> finished document product. This is hard to do in small shops who
>> >> probably don't treat documentation as anything more than a checkoff
>> >> item. (some of the manuals I've read are abysmal! even from large
>> >> multibillion dollar corporations -- as if they assumed no one would
>> >> ever READ them so why bother putting any effort into WRITING them?!)
>> >
>> >There is the key. It isn't valued. And, as you mention most
>> >programmers are terrible writers, so they will use any excuse to avoid
>> >writing. The problem with my approach of attaching a Tech Writer to
>> >the programmer is that it's expensive, and you have to have some Tech
>> >Writers on staff to assign.
>>
>> Exactly, and that has nothing to do with the current state of the
>> schools. People are expensive. Talented people, even more so.
>
>No, it's exactly on point. The problem being solved by addition of
>Tech Writers is exactly that engineers are able to graduate without
>being taught how to write a comprehensible paper.
Bullshit. There are fewer technical writers now than there were in
>> >> I think you have to go from hand to hand (to hand) to get to a
>> >> finished document product. This is hard to do in small shops who
>> >> probably don't treat documentation as anything more than a checkoff
>> >> item. (some of the manuals I've read are abysmal! even from large
>> >> multibillion dollar corporations -- as if they assumed no one would
>> >> ever READ them so why bother putting any effort into WRITING them?!)
>> >
>> >There is the key. It isn't valued. And, as you mention most
>> >programmers are terrible writers, so they will use any excuse to avoid
>> >writing. The problem with my approach of attaching a Tech Writer to
>> >the programmer is that it's expensive, and you have to have some Tech
>> >Writers on staff to assign.
>>
>> Exactly, and that has nothing to do with the current state of the
>> schools. People are expensive. Talented people, even more so.
>
>No, it's exactly on point. The problem being solved by addition of
>Tech Writers is exactly that engineers are able to graduate without
>being taught how to write a comprehensible paper.
the past. It's not some revelation that engineers, in general, are
poor writers. This was true fifty years ago and if what my father
complained about, it was true a generation before that. The two take
a very different set of skills and aptitudes.
<...>
>
>> >In the case of teaching stack order to typists, they were willing
>> >because making tables and nested tables was driving them nuts, so they
>> >had motive.
>> >
>> >Parallel War Story: The lab director's secretary complained to me that
>> >the mouse didn't work, and the cursor would fly off in odd directions.
>> >I couldn't find anything wrong with the mouse, so I watched her work.
>> >Turns out that she was pointing the mouse in the direction she wanted
>> >to go, and then moved there. She had no idea that one held the mouse
>> >axis vertical regardless, and telling her didn't quite work. So, I
>> >took the mouse apart as for cleaning, and showed here the little
>> >wheels, and demonstrated that if I rotated one wheel, the cursor went
>> >up and down, while the other wheel caused side-to-side motion. Also
>> >cleaned the mouse. Problem solved - she now had an adequate mental
>> >model of how the mouse worked.
>>
>> Most just pick it up in a minute, just by moving the mouse.
>
>A lab director's secretary is never a kid. She was from the old
>school, and had little prior experience with computers.
Doesn't matter. It's a simple device. Two minutes play should be all
>> >In the case of teaching stack order to typists, they were willing
>> >because making tables and nested tables was driving them nuts, so they
>> >had motive.
>> >
>> >Parallel War Story: The lab director's secretary complained to me that
>> >the mouse didn't work, and the cursor would fly off in odd directions.
>> >I couldn't find anything wrong with the mouse, so I watched her work.
>> >Turns out that she was pointing the mouse in the direction she wanted
>> >to go, and then moved there. She had no idea that one held the mouse
>> >axis vertical regardless, and telling her didn't quite work. So, I
>> >took the mouse apart as for cleaning, and showed here the little
>> >wheels, and demonstrated that if I rotated one wheel, the cursor went
>> >up and down, while the other wheel caused side-to-side motion. Also
>> >cleaned the mouse. Problem solved - she now had an adequate mental
>> >model of how the mouse worked.
>>
>> Most just pick it up in a minute, just by moving the mouse.
>
>A lab director's secretary is never a kid. She was from the old
>school, and had little prior experience with computers.
that's needed. Learning context and buttons complicate things a lot
but any bloody idiot should be able to pick up the motion, for
themselves, in a couple of minutes.
>If you want the fuller explanation, read some of the human interface
>guidelines documents from Apple in the 1980s, especially the book by
>Tog (I don't recall his full name, but it will come to me - Tog is a
>clip of his last name).
Perhaps that says something about Apple's customers. If they needed
that book, I'm surprised they were able to read it.
Joe Gwinn
Aug 17, 2014, 3:03:41 PM8/17/14
to
In article <o8rvu9pk86ipl5nqj...@4ax.com>,
Well, my story was one approach to getting good documentation from a
programmer who could not write understandable English documentation.
Have you a better method?
> >> >> Most programmers/engineers are lousy writers -- they tend to forget
> >> >> who they are talking to as well as the types of issues that may be
> >> >> important to that audience.
> >> >
> >> >It's because we in the US no longer teach writing in High School and
> >> >before. Writing is work, and there is an artifice to be learned. We
> >> >don't teach grammar either.
> >>
> >> No, engineers never made good writers. Technical writing has always
> >> been a specialty. The difference is that now there are few companies
> >> that want to invest in them so it's too often left to those who aren't
> >> qualified.
> >
> >Some were good writers, some were not. I've met both kinds.
>
> It's a different skill set, one that uses completely different parts
> of the brain. One cannot expect even the best engineer to have the
> capability to do technical writing.
Where was that claimed?
But there are engineers that are also good writers, as discussed next.
> >The classic books in any field are almost always written by people who
> >are good writers.
>
> Many are horrible writers. Many Textbook authors come to mind. Those
> with both skills are a *SMALL* subset of the universe of engineers.
>
> >I have observed that technical books written in the UK are on average
> >better written than those written in the US. I gather that this is
> >because they still teach all students in the UK how to write, whether
> >they want to or not.
>
> Or perhaps that says something about the textbooks you've been exposed
> to.
Well, I have a sample spanning many decades, and easily read ten books
a year.
> >> >By the way, we are not talking about being able to write the Great
> >> >American Novel. We are talking about writing a simple descriptive
> >> >paper. I heard from a colleague that a standard test used to qualify
> >> >candidates for a Technical Writing job - ask the candidate to write an
> >> >instruction sheet on how to tie one's shoes.
> >>
> >> Good plan but don't expect the average engineer to do it. It's not
> >> their specialty (among a whole host of other reasons).
> >
> >And it cripples them. I see it every day.
>
> If their job is technical writing, sure. It shouldn't be.
The problem is that they cannot convince other engineers and managers
of the correctness of their approach. Or write a reasonable proposal
section. This happens long before issues of documentation come up.
> >> >Teaching writing is expensive, because the student-teacher ratio cannot
> >> >exceed ten, or the teacher won't have time to do the detailed
> >> >correction that's needed. One of the big distinctions between US
> >> >public (tax supported) and private (parents pay) schools is that
> >> >private schools all teach how to write.
> >>
> >> Those are some absolute statements that will require support to be
> >> believed.
> >
> >This is from personal observation and talking to people who went to
> >private school. If you need mathematical proof, go right ahead.
>
> "cannot exceed ten" and "private schools all teach" means that you're
> stating that you have data that shows the absolute is true. That's
> just silly. Perhaps you're not as good at writing as you think you
> are?
Non sequitur. I said it was my personal experience. My ability to
write was not at issue.
> >> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> >> >> of the technology that is being presented.
> >> >
> >> >Hence they babble, or balk.
> >>
> >> Why should they even be asked to venture outside their training?
> >
> >That was my original point, saying that having the non-engineer writers
> >go first won't work. And I've seen it tried.
>
> There *is* such a profession called "technical writer". They're
> trained as such. My SIL was one, many moons ago.
>
> >Actually, on a radar system many years ago, I saw the tech manual
> >writers struggle to generate anything useful, and so decided it would
> >take less of my time if I just sat down and wrote the rough first
> >draft. One cannot just deliver muck because the customer verifies the
> >usefulness of these documents by trying to follow them.
>
> That doesn't support anything you've said. Of course it's a good idea
> to have input from the designers. In fact, the first documents should
> come from marketing (what are we trying to build) and the system
> architects (how are we going to approach the solution). The designers
> may fill in some detail (or not).
Again, in this example, I came to the conclusion that it was best if I
wrote the first draft, and did so. Your experience may differ.
> >> >> I think you have to go from hand to hand (to hand) to get to a
> >> >> finished document product. This is hard to do in small shops who
> >> >> probably don't treat documentation as anything more than a checkoff
> >> >> item. (some of the manuals I've read are abysmal! even from large
> >> >> multibillion dollar corporations -- as if they assumed no one would
> >> >> ever READ them so why bother putting any effort into WRITING them?!)
> >> >
> >> >There is the key. It isn't valued. And, as you mention most
> >> >programmers are terrible writers, so they will use any excuse to avoid
> >> >writing. The problem with my approach of attaching a Tech Writer to
> >> >the programmer is that it's expensive, and you have to have some Tech
> >> >Writers on staff to assign.
> >>
> >> Exactly, and that has nothing to do with the current state of the
> >> schools. People are expensive. Talented people, even more so.
> >
> >No, it's exactly on point. The problem being solved by addition of
> >Tech Writers is exactly that engineers are able to graduate without
> >being taught how to write a comprehensible paper.
>
> Bullshit. There are fewer technical writers now than there were in
> the past. It's not some revelation that engineers, in general, are
> poor writers. This was true fifty years ago and if what my father
> complained about, it was true a generation before that. The two take
> a very different set of skills and aptitudes.
Well, I don't know if the total number of Tech Writers has changed or
not. I haven't noticed any such thing in my corner of the swamp.
Perhaps you would like to support that statement by finding the
relevant statistics on the US Bureau of Labor Statistics website.
> >> >In the case of teaching stack order to typists, they were willing
> >> >because making tables and nested tables was driving them nuts, so they
> >> >had motive.
> >> >
> >> >Parallel War Story: The lab director's secretary complained to me that
> >> >the mouse didn't work, and the cursor would fly off in odd directions.
> >> >I couldn't find anything wrong with the mouse, so I watched her work.
> >> >Turns out that she was pointing the mouse in the direction she wanted
> >> >to go, and then moved there. She had no idea that one held the mouse
> >> >axis vertical regardless, and telling her didn't quite work. So, I
> >> >took the mouse apart as for cleaning, and showed here the little
> >> >wheels, and demonstrated that if I rotated one wheel, the cursor went
> >> >up and down, while the other wheel caused side-to-side motion. Also
> >> >cleaned the mouse. Problem solved - she now had an adequate mental
> >> >model of how the mouse worked.
> >>
> >> Most just pick it up in a minute, just by moving the mouse.
> >
> >A lab director's secretary is never a kid. She was from the old
> >school, and had little prior experience with computers.
>
> Doesn't matter. It's a simple device. Two minutes play should be all
> that's needed. Learning context and buttons complicate things a lot
> but any bloody idiot should be able to pick up the motion, for
> themselves, in a couple of minutes.
Umm. Nice theory. Didn't work out that way.
And telling the lab director's secretary that she's an idiot may prove
career-limiting.
> >If you want the fuller explanation, read some of the human interface
> >guidelines documents from Apple in the 1980s, especially the book by
> >Tog (I don't recall his full name, but it will come to me - Tog is a
> >clip of his last name).
>
> You're saying that Apple wrote a book about the 2D motion of a mouse?
> Perhaps that says something about Apple's customers. If they needed
> that book, I'm surprised they were able to read it.
Right. There is far more to it than that. Enough to fill a book:
"TOG on Interface", Bruce "TOG" Tognazzini, Apple Computer Inc,
Addison-Wesley 1992, 331 pages.
Joe Gwinn
programmer who could not write understandable English documentation.
Have you a better method?
> >> >> Most programmers/engineers are lousy writers -- they tend to forget
> >> >> who they are talking to as well as the types of issues that may be
> >> >> important to that audience.
> >> >
> >> >It's because we in the US no longer teach writing in High School and
> >> >before. Writing is work, and there is an artifice to be learned. We
> >> >don't teach grammar either.
> >>
> >> No, engineers never made good writers. Technical writing has always
> >> been a specialty. The difference is that now there are few companies
> >> that want to invest in them so it's too often left to those who aren't
> >> qualified.
> >
> >Some were good writers, some were not. I've met both kinds.
>
> It's a different skill set, one that uses completely different parts
> of the brain. One cannot expect even the best engineer to have the
> capability to do technical writing.
But there are engineers that are also good writers, as discussed next.
> >The classic books in any field are almost always written by people who
> >are good writers.
>
> Many are horrible writers. Many Textbook authors come to mind. Those
> with both skills are a *SMALL* subset of the universe of engineers.
>
> >I have observed that technical books written in the UK are on average
> >better written than those written in the US. I gather that this is
> >because they still teach all students in the UK how to write, whether
> >they want to or not.
>
> Or perhaps that says something about the textbooks you've been exposed
> to.
a year.
> >> >By the way, we are not talking about being able to write the Great
> >> >American Novel. We are talking about writing a simple descriptive
> >> >paper. I heard from a colleague that a standard test used to qualify
> >> >candidates for a Technical Writing job - ask the candidate to write an
> >> >instruction sheet on how to tie one's shoes.
> >>
> >> Good plan but don't expect the average engineer to do it. It's not
> >> their specialty (among a whole host of other reasons).
> >
> >And it cripples them. I see it every day.
>
> If their job is technical writing, sure. It shouldn't be.
of the correctness of their approach. Or write a reasonable proposal
section. This happens long before issues of documentation come up.
> >> >Teaching writing is expensive, because the student-teacher ratio cannot
> >> >exceed ten, or the teacher won't have time to do the detailed
> >> >correction that's needed. One of the big distinctions between US
> >> >public (tax supported) and private (parents pay) schools is that
> >> >private schools all teach how to write.
> >>
> >> Those are some absolute statements that will require support to be
> >> believed.
> >
> >This is from personal observation and talking to people who went to
> >private school. If you need mathematical proof, go right ahead.
>
> "cannot exceed ten" and "private schools all teach" means that you're
> stating that you have data that shows the absolute is true. That's
> just silly. Perhaps you're not as good at writing as you think you
> are?
write was not at issue.
> >> >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> >> >> of the technology that is being presented.
> >> >
> >> >Hence they babble, or balk.
> >>
> >> Why should they even be asked to venture outside their training?
> >
> >That was my original point, saying that having the non-engineer writers
> >go first won't work. And I've seen it tried.
>
> There *is* such a profession called "technical writer". They're
> trained as such. My SIL was one, many moons ago.
>
> >Actually, on a radar system many years ago, I saw the tech manual
> >writers struggle to generate anything useful, and so decided it would
> >take less of my time if I just sat down and wrote the rough first
> >draft. One cannot just deliver muck because the customer verifies the
> >usefulness of these documents by trying to follow them.
>
> That doesn't support anything you've said. Of course it's a good idea
> to have input from the designers. In fact, the first documents should
> come from marketing (what are we trying to build) and the system
> architects (how are we going to approach the solution). The designers
> may fill in some detail (or not).
wrote the first draft, and did so. Your experience may differ.
> >> >> I think you have to go from hand to hand (to hand) to get to a
> >> >> finished document product. This is hard to do in small shops who
> >> >> probably don't treat documentation as anything more than a checkoff
> >> >> item. (some of the manuals I've read are abysmal! even from large
> >> >> multibillion dollar corporations -- as if they assumed no one would
> >> >> ever READ them so why bother putting any effort into WRITING them?!)
> >> >
> >> >There is the key. It isn't valued. And, as you mention most
> >> >programmers are terrible writers, so they will use any excuse to avoid
> >> >writing. The problem with my approach of attaching a Tech Writer to
> >> >the programmer is that it's expensive, and you have to have some Tech
> >> >Writers on staff to assign.
> >>
> >> Exactly, and that has nothing to do with the current state of the
> >> schools. People are expensive. Talented people, even more so.
> >
> >No, it's exactly on point. The problem being solved by addition of
> >Tech Writers is exactly that engineers are able to graduate without
> >being taught how to write a comprehensible paper.
>
> Bullshit. There are fewer technical writers now than there were in
> the past. It's not some revelation that engineers, in general, are
> poor writers. This was true fifty years ago and if what my father
> complained about, it was true a generation before that. The two take
> a very different set of skills and aptitudes.
not. I haven't noticed any such thing in my corner of the swamp.
Perhaps you would like to support that statement by finding the
relevant statistics on the US Bureau of Labor Statistics website.
> >> >In the case of teaching stack order to typists, they were willing
> >> >because making tables and nested tables was driving them nuts, so they
> >> >had motive.
> >> >
> >> >Parallel War Story: The lab director's secretary complained to me that
> >> >the mouse didn't work, and the cursor would fly off in odd directions.
> >> >I couldn't find anything wrong with the mouse, so I watched her work.
> >> >Turns out that she was pointing the mouse in the direction she wanted
> >> >to go, and then moved there. She had no idea that one held the mouse
> >> >axis vertical regardless, and telling her didn't quite work. So, I
> >> >took the mouse apart as for cleaning, and showed here the little
> >> >wheels, and demonstrated that if I rotated one wheel, the cursor went
> >> >up and down, while the other wheel caused side-to-side motion. Also
> >> >cleaned the mouse. Problem solved - she now had an adequate mental
> >> >model of how the mouse worked.
> >>
> >> Most just pick it up in a minute, just by moving the mouse.
> >
> >A lab director's secretary is never a kid. She was from the old
> >school, and had little prior experience with computers.
>
> Doesn't matter. It's a simple device. Two minutes play should be all
> that's needed. Learning context and buttons complicate things a lot
> but any bloody idiot should be able to pick up the motion, for
> themselves, in a couple of minutes.
And telling the lab director's secretary that she's an idiot may prove
career-limiting.
> >If you want the fuller explanation, read some of the human interface
> >guidelines documents from Apple in the 1980s, especially the book by
> >Tog (I don't recall his full name, but it will come to me - Tog is a
> >clip of his last name).
>
> You're saying that Apple wrote a book about the 2D motion of a mouse?
> Perhaps that says something about Apple's customers. If they needed
> that book, I'm surprised they were able to read it.
"TOG on Interface", Bruce "TOG" Tognazzini, Apple Computer Inc,
Addison-Wesley 1992, 331 pages.
Joe Gwinn
Joe Gwinn
Aug 17, 2014, 3:16:48 PM8/17/14
to
In article <lsoqiu$fus$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
> Hi Joe,
>
> On 8/16/2014 3:20 PM, Joe Gwinn wrote:
>
> >
> > The college hires don't yet know enough for that to work, and will
> > babble as badly as the English majors, only slightly more plausibly.
>
> <frown> Perhaps I have the benefit of having been surrounded by
> "more adept" peers? If I restricted my selection to those with
> English as their native language, *any* of the folks I went to
> school (college) with could easily do this -- AND, appreciate the
> logic behind it.
>
> It might take some time for them to develop a good "approach" to
> each assignment (i.e., avoid the temptation to start at "main()"
> and describe the code sequentially). But, I think they would be
> smart enough to know not to (for example) just repackage the comments
> that accompany the code!
These systems are very large and complex, and it takes a year to really
learn them.
> >>>> Most programmers/engineers are lousy writers -- they tend to forget
> >>>> who they are talking to as well as the types of issues that may be
> >>>> important to that audience.
> >>>
> >>> It's because we in the US no longer teach writing in High School and
> >>> before. Writing is work, and there is an artifice to be learned. We
> >>> don't teach grammar either.
> >>
> >> Dunno. School, for me, was many decades ago. But, I recall a fair
> >> bit of emphasis on "English" throughout elementary and junior/senior
> >> high schools. E.g., you couldn't be awarded a high school diploma
> >> without having had 4 years of English -- the same was not true of
> >> Math, Science, etc.!
> >
> > The requirement is still something like four years of English. What
> > varies is the content of "English".
>
> Again, I guess I can't imagine what it could be *other* than "reading
> and writing". At the end of my High School stint, they were starting
> to introduce courses like "Film Appreciation", etc. -- but, those
> were distinctly *not* "English".
>
> I recall there was an emphasis on American Literature -- one year
> in High School and another in Jr High. Ditto American History.
> I was actually surprised, in college, to encounter other "Americans"
> who had not had these exposures! I.e., I deliberately chose courses
> of similar titles for college "electives" knowing that I had already
> seen much of that material, before! :-/
There has been a lot of dumbing down over the years, often in service
of political correctness and fads in teaching methods.
> >> I think a bigger problem is people's inability to organize their
> >> thoughts, well. Hand someone a piece of paper and tell them to
> >> write a piece of code, a story, etc. and they will stare at it,
> >> unable to begin.
> >>
> >> Give them an EXISTING piece of code, story/outline, etc. and they'll
> >> usually have no problem "fleshing it out"!
> >
> > This is a different problem. Teaching someone how to write does not
> > ensure that they have anything to say.
>
> I see knowing how to *approach* a problem (whether it is writing a piece
> of code, designing a circuit or documenting a device/interface) as a
> necessary skill to effectively complete the task "unassisted". If
> you can't sort out how you are going to "pitch" some information to
> a faceless reader, then, chances are, the reader will end up confused
> and find little value in what you end up writing.
Yes, but the problem is the factless writer.
> >>>> I think it has a lot of value as the documents become more tightly
> >>>> integrated with the products. Currently, most massaging of
> >>>> documents happens in the design (and documentation) phases. Once
> >>>> created, they tend to be largely static and "ancillary" items.
> >>>> E.g., the product never actively references them or incorporates
> >>>> them into its nominal operation.
> >>>
> >>>> All these "advances" are obviously geared towards making documents
> >>>> more useful and more of a "product resource".
> >>>
> >>> Yes. But it is always an investment decision.
> >>
> >> That's the point -- make it an investment that has a real payoff!
> >> E.g., automates some of the code generation; or, addresses some
> >> portion of the "user documentation" that will eventually need to be
> >> prepared, etc. So there is an incentive to preparing and maintaining
> >> the documents!
> >
> > Some companies are famous for good documentation, and some are famous
> > for the converse. I've never heard of a company that dies because
> > their documentation was bad.
>
> Yup. The most common metric, currently, seems to be "price".
> As such, why do *anything* (documentation, improved product
> quality, etc.) that will adversely impact price??
It's because for all their complaining, customers still buy.
Joe Gwinn
wrote:
> Hi Joe,
>
> On 8/16/2014 3:20 PM, Joe Gwinn wrote:
>
> >
> > The college hires don't yet know enough for that to work, and will
> > babble as badly as the English majors, only slightly more plausibly.
>
> <frown> Perhaps I have the benefit of having been surrounded by
> "more adept" peers? If I restricted my selection to those with
> English as their native language, *any* of the folks I went to
> school (college) with could easily do this -- AND, appreciate the
> logic behind it.
>
> It might take some time for them to develop a good "approach" to
> each assignment (i.e., avoid the temptation to start at "main()"
> and describe the code sequentially). But, I think they would be
> smart enough to know not to (for example) just repackage the comments
> that accompany the code!
learn them.
> >>>> Most programmers/engineers are lousy writers -- they tend to forget
> >>>> who they are talking to as well as the types of issues that may be
> >>>> important to that audience.
> >>>
> >>> It's because we in the US no longer teach writing in High School and
> >>> before. Writing is work, and there is an artifice to be learned. We
> >>> don't teach grammar either.
> >>
> >> Dunno. School, for me, was many decades ago. But, I recall a fair
> >> bit of emphasis on "English" throughout elementary and junior/senior
> >> high schools. E.g., you couldn't be awarded a high school diploma
> >> without having had 4 years of English -- the same was not true of
> >> Math, Science, etc.!
> >
> > The requirement is still something like four years of English. What
> > varies is the content of "English".
>
> Again, I guess I can't imagine what it could be *other* than "reading
> and writing". At the end of my High School stint, they were starting
> to introduce courses like "Film Appreciation", etc. -- but, those
> were distinctly *not* "English".
>
> I recall there was an emphasis on American Literature -- one year
> in High School and another in Jr High. Ditto American History.
> I was actually surprised, in college, to encounter other "Americans"
> who had not had these exposures! I.e., I deliberately chose courses
> of similar titles for college "electives" knowing that I had already
> seen much of that material, before! :-/
of political correctness and fads in teaching methods.
> >> I think a bigger problem is people's inability to organize their
> >> thoughts, well. Hand someone a piece of paper and tell them to
> >> write a piece of code, a story, etc. and they will stare at it,
> >> unable to begin.
> >>
> >> Give them an EXISTING piece of code, story/outline, etc. and they'll
> >> usually have no problem "fleshing it out"!
> >
> > This is a different problem. Teaching someone how to write does not
> > ensure that they have anything to say.
>
> I see knowing how to *approach* a problem (whether it is writing a piece
> of code, designing a circuit or documenting a device/interface) as a
> necessary skill to effectively complete the task "unassisted". If
> you can't sort out how you are going to "pitch" some information to
> a faceless reader, then, chances are, the reader will end up confused
> and find little value in what you end up writing.
> >>>> I think it has a lot of value as the documents become more tightly
> >>>> integrated with the products. Currently, most massaging of
> >>>> documents happens in the design (and documentation) phases. Once
> >>>> created, they tend to be largely static and "ancillary" items.
> >>>> E.g., the product never actively references them or incorporates
> >>>> them into its nominal operation.
> >>>
> >>>> All these "advances" are obviously geared towards making documents
> >>>> more useful and more of a "product resource".
> >>>
> >>> Yes. But it is always an investment decision.
> >>
> >> That's the point -- make it an investment that has a real payoff!
> >> E.g., automates some of the code generation; or, addresses some
> >> portion of the "user documentation" that will eventually need to be
> >> prepared, etc. So there is an incentive to preparing and maintaining
> >> the documents!
> >
> > Some companies are famous for good documentation, and some are famous
> > for the converse. I've never heard of a company that dies because
> > their documentation was bad.
>
> Yup. The most common metric, currently, seems to be "price".
> As such, why do *anything* (documentation, improved product
> quality, etc.) that will adversely impact price??
Joe Gwinn
Joe Gwinn
Aug 17, 2014, 3:22:03 PM8/17/14
to
In article <lsondf$abm$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
wrote:
Usually, it's a real theory of operation that I most need. Without
this, the myriad details mean little.
> >> I had a lady coworker once jokingly berate me for explaining
> >> computer-related issues using *kitchen* analogies -- as if I
> >> was being misogynistic! So, the next "problem" she presented
> >> to me I opted to matter-of-factly explain in "bedroom" analogies.
> >> When she had achieved a suitably uniform shade of RED, I paused
> >> and waited for her to suggest I return to the kitchen domain,
> >> again! :>
> >>
> >> But, in each case, she ended up understanding the issue that
> >> others had tried explaining/resolving with techno-babble.
> >
> > Would have been fun to watch. You must have known her well, to get
> > away with that.
>
> Yes, you could say that! ;-)
>
> The point is/was, to find a way of explaining an issue in terms
> to which the other party will be able to relate! Listen to how
> often people try to explain things AS IF they were still "at work"
> talking to their peers/superiors.
>
> "And, you expect me to PARTICIPATE in this discussion? How??"
>
> Technical people are particularly bad in this regard. They forget
> that language and terminology that are commonplace in their "element"
> are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of
> that community!
Yeah. My wife retired from the Finance business. It took some years,
but I did learn more of her jargon than she learned of my jargon.
> > Don't think I'll try that approach. It would probably end badly - the
> > lawyers would be babbling something about creating a hostile
> > environment as the guards frog-marched me out the door.
>
> Yeah, nowadays, the workplace is far less tolerant of this sort of
> stuff! Sad as this sort of familiar/casual interaction can be
> great at tearing down boundaries between people/groups. I.e.,
> "being able to take a joke"...
I did have a lot of fun teasing the true believers by mentioning that
my wife very much regretted the rise of political correctness, because
it killed all the good jokes off.
Joe Gwinn
wrote:
this, the myriad details mean little.
> >> I had a lady coworker once jokingly berate me for explaining
> >> computer-related issues using *kitchen* analogies -- as if I
> >> was being misogynistic! So, the next "problem" she presented
> >> to me I opted to matter-of-factly explain in "bedroom" analogies.
> >> When she had achieved a suitably uniform shade of RED, I paused
> >> and waited for her to suggest I return to the kitchen domain,
> >> again! :>
> >>
> >> But, in each case, she ended up understanding the issue that
> >> others had tried explaining/resolving with techno-babble.
> >
> > Would have been fun to watch. You must have known her well, to get
> > away with that.
>
> Yes, you could say that! ;-)
>
> The point is/was, to find a way of explaining an issue in terms
> to which the other party will be able to relate! Listen to how
> often people try to explain things AS IF they were still "at work"
> talking to their peers/superiors.
>
> "And, you expect me to PARTICIPATE in this discussion? How??"
>
> Technical people are particularly bad in this regard. They forget
> that language and terminology that are commonplace in their "element"
> are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of
> that community!
but I did learn more of her jargon than she learned of my jargon.
> > Don't think I'll try that approach. It would probably end badly - the
> > lawyers would be babbling something about creating a hostile
> > environment as the guards frog-marched me out the door.
>
> Yeah, nowadays, the workplace is far less tolerant of this sort of
> stuff! Sad as this sort of familiar/casual interaction can be
> great at tearing down boundaries between people/groups. I.e.,
> "being able to take a joke"...
my wife very much regretted the rise of political correctness, because
it killed all the good jokes off.
Joe Gwinn
Don Y
Aug 17, 2014, 3:42:50 PM8/17/14
to
Hi Joe,
On 8/17/2014 12:22 PM, Joe Gwinn wrote:
>> I am dismayed at how much ends up "lost to posterity" due to
>> inadequate or incorrect documentation. I've been trudging through
>> many "classic" research papers *chagrined* at the typographical
>> errors that make them less than (immediately) useful! In some
>> cases, contacting the original authors has proven difficult/impossible.
>> And, in other cases, the original author may no longer recollect
>> some of the fine detail that I am questioning -- and, have little
>> interest in "investigating" their old works.
>>
>> So, I'm left with the knowledge that something is (should be?)
>> "do-able" (allegedly) -- yet not having a clear path to repeat their
>> prior successes (or, even TEST against them!)
>>
>> As I want the things I am working on to be "self-supporting"
>> (i.e., *I* don't want to spend my time answering questions), I
>> have been attempting to document them in a more "educational"
>> manner.
>>
>> It is impractical to document hardware or software in anything more
>> than a "theory of operation" manner. There's just no provision to
>> explain and explore alternatives *before* arriving at the eventual
>> implementation as a "conclusion".
>
> Usually, it's a real theory of operation that I most need. Without
> this, the myriad details mean little.
For software, there are often far too many *different* approaches
to a problem. Explaining why you chose a particular approach -- and
its merits over the unnamed others -- can do far more for bringing
the next developer "along" than any sort of detailed discussion of
the *current* implementation.
E.g., where break-even points happen to exist between algorithms.
Or, pitfalls that one might have from which another is immune.
It also lets you demonstrate many of the boundary conditions that
someone might not otherwise be aware of. So, instead of "don't
touch this piece of code", you can reference the particular
special case that it protects against.
E.g., if you have a Bezier curve in which all control points are
colinear, it's a piece of cake to compute it's "length" with simple
arithmetic. OTOH, other schemes (e.g., De Casteljau's) can fall
apart silently!
>>> Would have been fun to watch. You must have known her well, to get
>>> away with that.
>>
>> Yes, you could say that! ;-)
>>
>> The point is/was, to find a way of explaining an issue in terms
>> to which the other party will be able to relate! Listen to how
>> often people try to explain things AS IF they were still "at work"
>> talking to their peers/superiors.
>>
>> "And, you expect me to PARTICIPATE in this discussion? How??"
>>
>> Technical people are particularly bad in this regard. They forget
>> that language and terminology that are commonplace in their "element"
>> are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of
>> that community!
>
> Yeah. My wife retired from the Finance business. It took some years,
> but I did learn more of her jargon than she learned of my jargon.
I don't think folks do this intentionally. Rather, they just get so
accustomed to their "niche-speak" that they forget that there is
*meaning* behind those terms/acronyms that they have become accustomed
to glossing over -- but, that others would have to ponder to appreciate.
>>> Don't think I'll try that approach. It would probably end badly - the
>>> lawyers would be babbling something about creating a hostile
>>> environment as the guards frog-marched me out the door.
>>
>> Yeah, nowadays, the workplace is far less tolerant of this sort of
>> stuff! Sad as this sort of familiar/casual interaction can be
>> great at tearing down boundaries between people/groups. I.e.,
>> "being able to take a joke"...
>
> I did have a lot of fun teasing the true believers by mentioning that
> my wife very much regretted the rise of political correctness, because
> it killed all the good jokes off.
This is where "familiarity" often wins out. People know your *intent*
and can look past the words: "Oh, that's just Don being Don..."
Being OUTRAGEOUS often helps as any more subtle comments can leave
people wondering if you meant what was SUGGESTED by them.
Sunday lunch! Finestkind! :>
On 8/17/2014 12:22 PM, Joe Gwinn wrote:
>> I am dismayed at how much ends up "lost to posterity" due to
>> inadequate or incorrect documentation. I've been trudging through
>> many "classic" research papers *chagrined* at the typographical
>> errors that make them less than (immediately) useful! In some
>> cases, contacting the original authors has proven difficult/impossible.
>> And, in other cases, the original author may no longer recollect
>> some of the fine detail that I am questioning -- and, have little
>> interest in "investigating" their old works.
>>
>> So, I'm left with the knowledge that something is (should be?)
>> "do-able" (allegedly) -- yet not having a clear path to repeat their
>> prior successes (or, even TEST against them!)
>>
>> As I want the things I am working on to be "self-supporting"
>> (i.e., *I* don't want to spend my time answering questions), I
>> have been attempting to document them in a more "educational"
>> manner.
>>
>> It is impractical to document hardware or software in anything more
>> than a "theory of operation" manner. There's just no provision to
>> explain and explore alternatives *before* arriving at the eventual
>> implementation as a "conclusion".
>
> Usually, it's a real theory of operation that I most need. Without
> this, the myriad details mean little.
to a problem. Explaining why you chose a particular approach -- and
its merits over the unnamed others -- can do far more for bringing
the next developer "along" than any sort of detailed discussion of
the *current* implementation.
E.g., where break-even points happen to exist between algorithms.
Or, pitfalls that one might have from which another is immune.
It also lets you demonstrate many of the boundary conditions that
someone might not otherwise be aware of. So, instead of "don't
touch this piece of code", you can reference the particular
special case that it protects against.
E.g., if you have a Bezier curve in which all control points are
colinear, it's a piece of cake to compute it's "length" with simple
arithmetic. OTOH, other schemes (e.g., De Casteljau's) can fall
apart silently!
>>> Would have been fun to watch. You must have known her well, to get
>>> away with that.
>>
>> Yes, you could say that! ;-)
>>
>> The point is/was, to find a way of explaining an issue in terms
>> to which the other party will be able to relate! Listen to how
>> often people try to explain things AS IF they were still "at work"
>> talking to their peers/superiors.
>>
>> "And, you expect me to PARTICIPATE in this discussion? How??"
>>
>> Technical people are particularly bad in this regard. They forget
>> that language and terminology that are commonplace in their "element"
>> are jibberish (or, worse -- MISUNDERSTOOD!) to others not a part of
>> that community!
>
> Yeah. My wife retired from the Finance business. It took some years,
> but I did learn more of her jargon than she learned of my jargon.
accustomed to their "niche-speak" that they forget that there is
*meaning* behind those terms/acronyms that they have become accustomed
to glossing over -- but, that others would have to ponder to appreciate.
>>> Don't think I'll try that approach. It would probably end badly - the
>>> lawyers would be babbling something about creating a hostile
>>> environment as the guards frog-marched me out the door.
>>
>> Yeah, nowadays, the workplace is far less tolerant of this sort of
>> stuff! Sad as this sort of familiar/casual interaction can be
>> great at tearing down boundaries between people/groups. I.e.,
>> "being able to take a joke"...
>
> I did have a lot of fun teasing the true believers by mentioning that
> my wife very much regretted the rise of political correctness, because
> it killed all the good jokes off.
and can look past the words: "Oh, that's just Don being Don..."
Being OUTRAGEOUS often helps as any more subtle comments can leave
people wondering if you meant what was SUGGESTED by them.
Sunday lunch! Finestkind! :>
k...@attt.bizz
Aug 17, 2014, 4:52:09 PM8/17/14
to
On Sun, 17 Aug 2014 15:03:41 -0400, Joe Gwinn <joeg...@comcast.net>
Sure. Stop trying to cheat the customer and hire a professional to
create the documents.
>> >> >> Most programmers/engineers are lousy writers -- they tend to forget
>> >> >> who they are talking to as well as the types of issues that may be
>> >> >> important to that audience.
>> >> >
>> >> >It's because we in the US no longer teach writing in High School and
>> >> >before. Writing is work, and there is an artifice to be learned. We
>> >> >don't teach grammar either.
>> >>
>> >> No, engineers never made good writers. Technical writing has always
>> >> been a specialty. The difference is that now there are few companies
>> >> that want to invest in them so it's too often left to those who aren't
>> >> qualified.
>> >
>> >Some were good writers, some were not. I've met both kinds.
>>
>> It's a different skill set, one that uses completely different parts
>> of the brain. One cannot expect even the best engineer to have the
>> capability to do technical writing.
>
>Where was that claimed?
You've claimed it all along.
>But there are engineers that are also good writers, as discussed next.
Sometimes you find a Picasso at a garage sale, too.
>> >The classic books in any field are almost always written by people who
>> >are good writers.
>>
>> Many are horrible writers. Many Textbook authors come to mind. Those
>> with both skills are a *SMALL* subset of the universe of engineers.
>>
>> >I have observed that technical books written in the UK are on average
>> >better written than those written in the US. I gather that this is
>> >because they still teach all students in the UK how to write, whether
>> >they want to or not.
>>
>> Or perhaps that says something about the textbooks you've been exposed
>> to.
>
>Well, I have a sample spanning many decades, and easily read ten books
>a year.
Ten of each, UK and US engineering texts. ...random samples?
>> >> >By the way, we are not talking about being able to write the Great
>> >> >American Novel. We are talking about writing a simple descriptive
>> >> >paper. I heard from a colleague that a standard test used to qualify
>> >> >candidates for a Technical Writing job - ask the candidate to write an
>> >> >instruction sheet on how to tie one's shoes.
>> >>
>> >> Good plan but don't expect the average engineer to do it. It's not
>> >> their specialty (among a whole host of other reasons).
>> >
>> >And it cripples them. I see it every day.
>>
>> If their job is technical writing, sure. It shouldn't be.
>
>The problem is that they cannot convince other engineers and managers
>of the correctness of their approach. Or write a reasonable proposal
>section. This happens long before issues of documentation come up.
That makes their engineering skills suspect? Good grief!
You think the entire world should be as wonderful as you (think you)
are. How much of your field of vision does your nose take up?
No, I believe the first documents should come from the people closest
to the customer, and then the system architects. The designers add
their pound of flesh somewhere down the pipe, just as they add the
rest of their value. I think JL is on target here, though he's doing
all three of these jobs. the documentation has to be done *before*
the design. It can't be done after. It won't be.
I didn't say she was the brightest bulb. I know my wife didn't have
to have any mechanical engineering instruction to pick up a mouse and
use it. Less than a minute pushing it around, without any
instruction, told her everything she needed to know. Well, perhaps
other than what was under the RMB.
>And telling the lab director's secretary that she's an idiot may prove
>career-limiting.
The truth can hurt but that's not the point. You seem to think this
abject lack of mechanical aptitude is somehow normal and expected. I
don't know anyone under the age of 80 who had trouble learning how to
use a mouse.
>> >If you want the fuller explanation, read some of the human interface
>> >guidelines documents from Apple in the 1980s, especially the book by
>> >Tog (I don't recall his full name, but it will come to me - Tog is a
>> >clip of his last name).
>>
>> You're saying that Apple wrote a book about the 2D motion of a mouse?
>> Perhaps that says something about Apple's customers. If they needed
>> that book, I'm surprised they were able to read it.
>
>Right. There is far more to it than that. Enough to fill a book:
Good grief! They rote books about how a mouse moves? *NOTHING* else?
which direction to point a mouse?
create the documents.
>> >> >> Most programmers/engineers are lousy writers -- they tend to forget
>> >> >> who they are talking to as well as the types of issues that may be
>> >> >> important to that audience.
>> >> >
>> >> >It's because we in the US no longer teach writing in High School and
>> >> >before. Writing is work, and there is an artifice to be learned. We
>> >> >don't teach grammar either.
>> >>
>> >> No, engineers never made good writers. Technical writing has always
>> >> been a specialty. The difference is that now there are few companies
>> >> that want to invest in them so it's too often left to those who aren't
>> >> qualified.
>> >
>> >Some were good writers, some were not. I've met both kinds.
>>
>> It's a different skill set, one that uses completely different parts
>> of the brain. One cannot expect even the best engineer to have the
>> capability to do technical writing.
>
>Where was that claimed?
>But there are engineers that are also good writers, as discussed next.
>> >The classic books in any field are almost always written by people who
>> >are good writers.
>>
>> Many are horrible writers. Many Textbook authors come to mind. Those
>> with both skills are a *SMALL* subset of the universe of engineers.
>>
>> >I have observed that technical books written in the UK are on average
>> >better written than those written in the US. I gather that this is
>> >because they still teach all students in the UK how to write, whether
>> >they want to or not.
>>
>> Or perhaps that says something about the textbooks you've been exposed
>> to.
>
>Well, I have a sample spanning many decades, and easily read ten books
>a year.
>> >> >By the way, we are not talking about being able to write the Great
>> >> >American Novel. We are talking about writing a simple descriptive
>> >> >paper. I heard from a colleague that a standard test used to qualify
>> >> >candidates for a Technical Writing job - ask the candidate to write an
>> >> >instruction sheet on how to tie one's shoes.
>> >>
>> >> Good plan but don't expect the average engineer to do it. It's not
>> >> their specialty (among a whole host of other reasons).
>> >
>> >And it cripples them. I see it every day.
>>
>> If their job is technical writing, sure. It shouldn't be.
>
>The problem is that they cannot convince other engineers and managers
>of the correctness of their approach. Or write a reasonable proposal
>section. This happens long before issues of documentation come up.
are. How much of your field of vision does your nose take up?
No, I believe the first documents should come from the people closest
to the customer, and then the system architects. The designers add
their pound of flesh somewhere down the pipe, just as they add the
rest of their value. I think JL is on target here, though he's doing
all three of these jobs. the documentation has to be done *before*
the design. It can't be done after. It won't be.
to have any mechanical engineering instruction to pick up a mouse and
use it. Less than a minute pushing it around, without any
instruction, told her everything she needed to know. Well, perhaps
other than what was under the RMB.
>And telling the lab director's secretary that she's an idiot may prove
>career-limiting.
abject lack of mechanical aptitude is somehow normal and expected. I
don't know anyone under the age of 80 who had trouble learning how to
use a mouse.
>> >If you want the fuller explanation, read some of the human interface
>> >guidelines documents from Apple in the 1980s, especially the book by
>> >Tog (I don't recall his full name, but it will come to me - Tog is a
>> >clip of his last name).
>>
>> You're saying that Apple wrote a book about the 2D motion of a mouse?
>> Perhaps that says something about Apple's customers. If they needed
>> that book, I'm surprised they were able to read it.
>
>Right. There is far more to it than that. Enough to fill a book:
>"TOG on Interface", Bruce "TOG" Tognazzini, Apple Computer Inc,
>Addison-Wesley 1992, 331 pages.
A whole book on mouse balls! Did you have to read it all to know
>Addison-Wesley 1992, 331 pages.
which direction to point a mouse?
Joe Gwinn
Aug 17, 2014, 5:47:21 PM8/17/14
to
In article <dj42v91545hidlo9a...@4ax.com>,
You keep saying that people should not be as described. Well, they are
what they are, and no amount of Internet pontification will change
that. You may have the last word.
Joe Gwinn
what they are, and no amount of Internet pontification will change
that. You may have the last word.
Joe Gwinn
k...@attt.bizz
Aug 17, 2014, 6:18:58 PM8/17/14
to
On Sun, 17 Aug 2014 17:47:21 -0400, Joe Gwinn <joeg...@comcast.net>
Oh good Lord. You really can't read, even what *YOU* have written!
You're looking down your nose at engineers because they don't live up
to the standards that you think you do.
You believe people should not be as you describe them. I didn't
describe people. _You_ did.
*YOU* are the one pontificating. *I* am calling *you* on exactly what
you wrote in the last paragraph.
You're looking down your nose at engineers because they don't live up
to the standards that you think you do.
You believe people should not be as you describe them. I didn't
describe people. _You_ did.
*YOU* are the one pontificating. *I* am calling *you* on exactly what
you wrote in the last paragraph.
josephkk
Aug 18, 2014, 4:33:07 AM8/18/14
to
On Sat, 16 Aug 2014 13:54:41 -0400, Joe Gwinn <joeg...@comcast.net>
My present employer has been doing it for over 2 decades now. My personal
contributions span about a decade. But we cut MSWord back to being a
rather simple editor in order to achieve it (well we add in some rather
simple tools with templates and some macros. Deamons i have learned to
hate VBA). Wordpad could do the work if it could handle the file size.
?-)
contributions span about a decade. But we cut MSWord back to being a
rather simple editor in order to achieve it (well we add in some rather
simple tools with templates and some macros. Deamons i have learned to
hate VBA). Wordpad could do the work if it could handle the file size.
?-)
Bill Sloman
Aug 20, 2014, 9:19:43 PM8/20/14
to
On Sunday, 17 August 2014 07:01:21 UTC+10, Joe Gwinn wrote:
> In article <31fvu9ll2dcv92a22...@4ax.com>,
> <k...@attt.bizz> wrote:
> > On Sat, 16 Aug 2014 14:17:02 -0400, Joe Gwinn <joeg...@comcast.net>
> > wrote:
> > >In article <lsm3cq$939$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
> > >wrote:
><snip>
> In article <31fvu9ll2dcv92a22...@4ax.com>,
> <k...@attt.bizz> wrote:
> > On Sat, 16 Aug 2014 14:17:02 -0400, Joe Gwinn <joeg...@comcast.net>
> > wrote:
> > >In article <lsm3cq$939$1...@speranza.aioe.org>, Don Y <th...@is.not.me.com>
> > >wrote:
> > >> Most programmers/engineers are lousy writers -- they tend to forget who they are talking to as well as the types of issues that may be important to that audience.
> > >
> > >It's because we in the US no longer teach writing in High School and before. Writing is work, and there is an artifice to be learned. We don't teach grammar either.
> >
> > No, engineers never made good writers. Technical writing has always been a specialty. The difference is that now there are few companies that want to invest in them so it's too often left to those who aren't qualified.
>
> Some were good writers, some were not. I've met both kinds.
http://www.computinghistory.org.uk/det/5858/David-Johnson-Davies/
http://www.interface.co.uk/
David happens to be the first graduate student (in Pyschology) of a friend of ours and we'd met him socially around Cambridge long before my boss at Fisons Applied Sensor Technology told me that he wanted me to write our user manual.
By then I knew that David had set up Human Computer Interface Ltd. and I suggested that they'd do a better job than I would. The boss talked to David, and came back very favourably impressed - a few years earlier the boss had decided that Fison's weren't going to buy up a project, largely because the user manual was rubbish. David Johnson-Davies' mob had subsequently got that contract, and the example manual that they showed my boss was their version of the manual, which was much better than the original.
Human Computer Interfaces went on write the manual for the IASys biosensor unit and everybody was very happy with it.
> The classic books in any field are almost always written by people who
are good writers.
>
> I have observed that technical books written in the UK are on average
better written than those written in the US. I gather that this is because they still teach all students in the UK how to write, whether they want to or not.
> > >By the way, we are not talking about being able to write the Great
American Novel. We are talking about writing a simple descriptive paper. I heard from a colleague that a standard test used to qualify candidates for a Technical Writing job - ask the candidate to write an instruction sheet on how to tie one's shoes.
> >
> > Good plan but don't expect the average engineer to do it. It's not their specialty (among a whole host of other reasons).
> And it cripples them. I see it every day.
> > >Teaching writing is expensive, because the student-teacher ratio cannot
exceed ten, or the teacher won't have time to do the detailed correction that's needed. One of the big distinctions between US public (tax supported) and private (parents pay) schools is that private schools all teach how to write.
> >
> > Those are some absolute statements that will require support to be
believed.
> This is from personal observation and talking to people who went to private school. If you need mathematical proof, go right ahead.
> > >> Similarly, most *writers* (e.g., Lit/English majors) have no concept of the technology that is being presented.
> > >
> > >Hence they babble, or balk.
> >
> > Why should they even be asked to venture outside their training?
There's no point in training communication skills if the people trained don't have anything to communicate. The information conveyed in a technical manual isn't usually all that extensive or unexpected - the art is in organising it in a way that lets the reader absorb it rapidly, and without too much intellectual effort.
> That was my original point, saying that having the non-engineer writers go first won't work. And I've seen it tried.
>
> Actually, on a radar system many years ago, I saw the tech manual writers struggle to generate anything useful, and so decided it would take less of my time if I just sat down and wrote the rough first draft. One cannot just deliver muck because the customer verifies the usefulness of these documents by trying to follow them.
> > >> I think you have to go from hand to hand (to hand) to get to a finished document product. This is hard to do in small shops who probably don't treat documentation as anything more than a checkoff item. (Some of the manuals I've read are abysmal! even from large multi-billion dollar corporations -- as if they assumed no one would ever READ them so why bother putting any effort into WRITING them?!)
> > >
> > >There is the key. It isn't valued. And, as you mention most programmers are terrible writers, so they will use any excuse to avoid writing. The problem with my approach of attaching a Tech Writer to the programmer is that it's expensive, and you have to have some Tech Writers on staff to assign.
> >
> > Exactly, and that has nothing to do with the current state of the schools. People are expensive. Talented people, even more so.
>
> No, it's exactly on point. The problem being solved by addition of Tech Writers is exactly that engineers are able to graduate without being taught how to write a comprehensible paper.
Writing a comprehensible paper is a talent, and not the same talent as being able to conceive an elegant circuit, and different again from the talent of working out why a circuit isn't working and fixing that. Spearman's G-factor correlates with all three skills, but most "talented" people aren't equally talented in all three areas. If you've got enough general intelligence, you can learn to do any of them adequately, but it can take quite a while to learn how to do any one of them really well - 10,000 hours is the oft-quoted claim. Some people can perform some skill adequately with a lot less practice, but they tend to get encouraged to apply that particular skill for most of their waking hours.
> > >There is the key. It isn't valued. And, as you mention most programmers are terrible writers, so they will use any excuse to avoid writing. The problem with my approach of attaching a Tech Writer to the programmer is that it's expensive, and you have to have some Tech Writers on staff to assign.
> >
> > Exactly, and that has nothing to do with the current state of the schools. People are expensive. Talented people, even more so.
>
> No, it's exactly on point. The problem being solved by addition of Tech Writers is exactly that engineers are able to graduate without being taught how to write a comprehensible paper.
Running a business is a different talent again ...
<snipped stuff about using a particular editor>
--
Bill Sloman, Sydney
Robert Baer
Aug 20, 2014, 10:47:04 PM8/20/14
to
Too bad there are NO program manuals or program "help" files that are
anywhere near the ideals mentioned.
Joe Gwinn
Aug 22, 2014, 5:16:39 PM8/22/14
to
In article <3d0bcec1-05ac-4b89...@googlegroups.com>,
> >
> > Some [engineers] were good writers, some were not. I've met both kinds.
> > The classic books in any field are almost always written by people who
> > are good writers.
> >
> > I have observed that technical books written in the UK are on average
> better written than those written in the US. I gather that this is because
> they still teach all students in the UK how to write, whether they want to or
> not.
>
> UK universoity students are expected to write essays - of the order of ten
> pages long - on stuff they have been taught or have been required to study.
Yes, precisely. But it must have been backed up in the schools for the
decade prior to university, or it would have proven impossible to get a
ten-page essay out of them in university - they simply would not have
it in them.
> > > >By the way, we are not talking about being able to write the Great
> American Novel. We are talking about writing a simple descriptive paper. I
> heard from a colleague that a standard test used to qualify candidates for a
> Technical Writing job - ask the candidate to write an instruction sheet on
> how to tie one's shoes.
> > >
> > > Good plan but don't expect the average engineer to do it. It's not their
> > > specialty (among a whole host of other reasons).
>
> But it ought to be.
>
> > And it cripples them. I see it every day.
>
> Not being able to write clear, complete and comprehensible text is a real
> disadvantage. Having the best idea in the world isn't much use if you can't
> tell anybody else about it.
Yes. And they don't like being ignored, but by then it's too late.
> > > >Teaching writing is expensive, because the student-teacher ratio cannot
> exceed ten, or the teacher won't have time to do the detailed correction
> that's needed. One of the big distinctions between US public (tax supported)
> and private (parents pay) schools is that private schools all teach how to
> write.
> > >
> > > Those are some absolute statements that will require support to be
> believed.
>
> Bizarre to see krw claiming this - he's never supported any of his absolute
> statements, and I'd come to think that he didn't understand the concept. He
> probably doesn't, and the sentence is just one that he's learned to drop into
> an argument at the right point. I suspect that some tax-supported US schools
> will teach some of their students how to write, and that some parent-paid-for
> US schools will fail some of their students in this regard, but the general
> claim is plausible.
>
> > This is from personal observation and talking to people who went to private
> > school. If you need mathematical proof, go right ahead.
>
> It would be statistical support for your point of view - a mathematical proof
> isn't on offer for this kind of statement. Krw is unlikely to produce it.
Ahh, well, I was exaggerating. It that point, it seemed unlikely that
there was any level of proof that would suffice, and it wasn't worth
the trouble anyway.
> > > >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> > > >> of the technology that is being presented.
> > > >
> > > >Hence they babble, or balk.
> > >
> > > Why should they even be asked to venture outside their training?
>
> Because they are being asked to apply the skill in which they have been
> trained - writing clearly and holding the readers attention - to convey
> information that needs to be passed on to the reader.
>
> There's no point in training communication skills if the people trained don't
> have anything to communicate. The information conveyed in a technical manual
> isn't usually all that extensive or unexpected - the art is in organising it
> in a way that lets the reader absorb it rapidly, and without too much
> intellectual effort.
>
> > That was my original point, saying that having the non-engineer writers go
> > first won't work. And I've seen it tried.
> >
> > Actually, on a radar system many years ago, I saw the tech manual writers
> > struggle to generate anything useful, and so decided it would take less of
> > my time if I just sat down and wrote the rough first draft. One cannot
> > just deliver muck because the customer verifies the usefulness of these
> > documents by trying to follow them.
>
> At the very first job I had the bosses pulled in a technical writer to write
> our progress report. He didn't understand enough of the technical content to
> do an entirely satisfactory job, so I rewrote it - retaining his structure
> and a lot of his wording. Either way can work.
Yes, it can work either way. But my judgement at the time was that it
was less work for me if I went first. I had been involved when it was
done the other way, tech writer first, and it was endless, because they
didn't have anything to start with. A first draft gave them something
to start with.
As you imply above, anybody with the general intelligence to be an
engineer will also be able to become an adequate writer, with training.
They don't have to like it. A tiny minority of these engineers will go
on to write the Great British Novel, but it matters little.
Joe Gwinn
Bill Sloman <bill....@gmail.com> wrote:
> On Sunday, 17 August 2014 07:01:21 UTC+10, Joe Gwinn wrote:
[snip]
> On Sunday, 17 August 2014 07:01:21 UTC+10, Joe Gwinn wrote:
> >
> > Some [engineers] were good writers, some were not. I've met both kinds.
>
> There's a least one good programmer who is also a great technical writer
>
> http://www.computinghistory.org.uk/det/5858/David-Johnson-Davies/
>
> http://www.interface.co.uk/
>
> David happens to be the first graduate student (in Pyschology) of a friend of
> ours and we'd met him socially around Cambridge long before my boss at Fisons
> Applied Sensor Technology told me that he wanted me to write our user manual.
>
> By then I knew that David had set up Human Computer Interface Ltd. and I
> suggested that they'd do a better job than I would. The boss talked to David,
> and came back very favourably impressed - a few years earlier the boss had
> decided that Fison's weren't going to buy up a project, largely because the
> user manual was rubbish. David Johnson-Davies' mob had subsequently got that
> contract, and the example manual that they showed my boss was their version
> of the manual, which was much better than the original.
>
> Human Computer Interfaces went on write the manual for the IASys biosensor
> unit and everybody was very happy with it.
Interesting.
> There's a least one good programmer who is also a great technical writer
>
> http://www.computinghistory.org.uk/det/5858/David-Johnson-Davies/
>
> http://www.interface.co.uk/
>
> David happens to be the first graduate student (in Pyschology) of a friend of
> ours and we'd met him socially around Cambridge long before my boss at Fisons
> Applied Sensor Technology told me that he wanted me to write our user manual.
>
> By then I knew that David had set up Human Computer Interface Ltd. and I
> suggested that they'd do a better job than I would. The boss talked to David,
> and came back very favourably impressed - a few years earlier the boss had
> decided that Fison's weren't going to buy up a project, largely because the
> user manual was rubbish. David Johnson-Davies' mob had subsequently got that
> contract, and the example manual that they showed my boss was their version
> of the manual, which was much better than the original.
>
> Human Computer Interfaces went on write the manual for the IASys biosensor
> unit and everybody was very happy with it.
> > The classic books in any field are almost always written by people who
> > are good writers.
> >
> > I have observed that technical books written in the UK are on average
> better written than those written in the US. I gather that this is because
> they still teach all students in the UK how to write, whether they want to or
> not.
>
> UK universoity students are expected to write essays - of the order of ten
> pages long - on stuff they have been taught or have been required to study.
decade prior to university, or it would have proven impossible to get a
ten-page essay out of them in university - they simply would not have
it in them.
> > > >By the way, we are not talking about being able to write the Great
> American Novel. We are talking about writing a simple descriptive paper. I
> heard from a colleague that a standard test used to qualify candidates for a
> Technical Writing job - ask the candidate to write an instruction sheet on
> how to tie one's shoes.
> > >
> > > Good plan but don't expect the average engineer to do it. It's not their
> > > specialty (among a whole host of other reasons).
>
> But it ought to be.
>
> > And it cripples them. I see it every day.
>
> Not being able to write clear, complete and comprehensible text is a real
> disadvantage. Having the best idea in the world isn't much use if you can't
> tell anybody else about it.
> > > >Teaching writing is expensive, because the student-teacher ratio cannot
> exceed ten, or the teacher won't have time to do the detailed correction
> that's needed. One of the big distinctions between US public (tax supported)
> and private (parents pay) schools is that private schools all teach how to
> write.
> > >
> > > Those are some absolute statements that will require support to be
> believed.
>
> Bizarre to see krw claiming this - he's never supported any of his absolute
> statements, and I'd come to think that he didn't understand the concept. He
> probably doesn't, and the sentence is just one that he's learned to drop into
> an argument at the right point. I suspect that some tax-supported US schools
> will teach some of their students how to write, and that some parent-paid-for
> US schools will fail some of their students in this regard, but the general
> claim is plausible.
>
> > This is from personal observation and talking to people who went to private
> > school. If you need mathematical proof, go right ahead.
>
> It would be statistical support for your point of view - a mathematical proof
> isn't on offer for this kind of statement. Krw is unlikely to produce it.
there was any level of proof that would suffice, and it wasn't worth
the trouble anyway.
> > > >> Similarly, most *writers* (e.g., Lit/English majors) have no concept
> > > >> of the technology that is being presented.
> > > >
> > > >Hence they babble, or balk.
> > >
> > > Why should they even be asked to venture outside their training?
>
> Because they are being asked to apply the skill in which they have been
> trained - writing clearly and holding the readers attention - to convey
> information that needs to be passed on to the reader.
>
> There's no point in training communication skills if the people trained don't
> have anything to communicate. The information conveyed in a technical manual
> isn't usually all that extensive or unexpected - the art is in organising it
> in a way that lets the reader absorb it rapidly, and without too much
> intellectual effort.
>
> > That was my original point, saying that having the non-engineer writers go
> > first won't work. And I've seen it tried.
> >
> > Actually, on a radar system many years ago, I saw the tech manual writers
> > struggle to generate anything useful, and so decided it would take less of
> > my time if I just sat down and wrote the rough first draft. One cannot
> > just deliver muck because the customer verifies the usefulness of these
> > documents by trying to follow them.
>
> At the very first job I had the bosses pulled in a technical writer to write
> our progress report. He didn't understand enough of the technical content to
> do an entirely satisfactory job, so I rewrote it - retaining his structure
> and a lot of his wording. Either way can work.
was less work for me if I went first. I had been involved when it was
done the other way, tech writer first, and it was endless, because they
didn't have anything to start with. A first draft gave them something
to start with.
engineer will also be able to become an adequate writer, with training.
They don't have to like it. A tiny minority of these engineers will go
on to write the Great British Novel, but it matters little.
Joe Gwinn
0 new messages