RE: Mark Baker's next book [was hijacked thread "Re:
Subject:
RE: Mark Baker's next book [was hijacked thread "Re:
From:
Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To:
"techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>, "Doug -dot- Grossman -at- sas -dot- com" <Doug -dot- Grossman -at- sas -dot- com>
Date:
Wed, 3 May 2017 12:43:36 +0000 (UTC)
Doug asks:What's wrong with being a wordsmith? Wordsmiths have their place in the world, just as any other profession.
Yes they do. But the industry has put a big squeeze on us all. I remember when the dev to writer ratio was supposed to hover around 6 : 1. I'm up to about 35, last I counted.
Look at the history of what we do (in software, anyway). We used to hand copy to a typesetter who produced galleys that were proofed, pasted up, and photographed. (Heck, even that is pretty modern.) Then came desktop publishing. Suddenly we had to know how to lay out a page, and we had to write within that layout. Then came GUIs -- we had to use more art. Thanks to desktop publishing software, we could do it all. Then came online... We had to generate CHMs or HTML. That led us to creating CSS, using javascript, and so on. And now there's XML -- DITA or DocBook, usually.Â
All this is to get more documentation out of us in less time and for less money. Now the economy of the industry says that clean copy isn't so important. What's important is that you reduce support calls and improve customer experience. Customers don't want to know they're reading anything... They don't want a book, they just want to "know". So we have to move the content even closer to the GUI.Â
Rather than being word smiths, I think of the profession as one subset of the spectrum of information management that goes into delivering a product. Exactly where you will fall in that spectrum will change from project to project. The broader you coverage of the spectrum can be, the more value you can add.Â
Why should you be the one who has to engineer your content delivery? Because nobody else wants to do it. Because you can. Because it adds value. Being a word smith... That's a luxury I can scarcely remember.Â
From: "techwr-l-request -at- lists -dot- techwr-l -dot- com" <techwr-l-request -at- lists -dot- techwr-l -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Sent: Wednesday, May 3, 2017 1:55 AM
Subject: TECHWR-L Digest, Vol 139, Issue 2
Send TECHWR-L mailing list submissions to
ÂÂÂ techwr-l -at- lists -dot- techwr-l -dot- com
To subscribe or unsubscribe via the World Wide Web, visit
ÂÂÂ http://lists.techwr-l.com/mailman/listinfo/techwr-l
or, via email, send a message with subject or body 'help' to
ÂÂÂ techwr-l-request -at- lists -dot- techwr-l -dot- com
You can reach the person managing the list at
ÂÂÂ techwr-l-owner -at- lists -dot- techwr-l -dot- com
When replying, please edit your Subject line so it is more specific
than "Re: Contents of TECHWR-L digest..."
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Today's Topics:
 1. RE: Structured stuff for the beginner (Chris Despopoulos)
 2. RE: Structured stuff for the beginner (mbaker -at- analecta -dot- com)
 3. Re: Structured stuff for the beginner (Chris Despopoulos)
 4. RE: Structured stuff for the beginner (mbaker -at- analecta -dot- com)
 5. RE: Ethics in Technical Writing (Wright, Lynne)
 6. Mark Baker's next book [was hijacked thread "Re: Structured
   stuff for the beginner"] (Robert Lauriston)
 7. Re: Ethics in Technical Writing (Gene Kim-Eng)
 8. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Gene Kim-Eng)
 9. RE: Ethics in Technical Writing (Wright, Lynne)
 10. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Simon North)
 11. RE: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Doug Grossman)
 12. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Sarah Kiniry)
 13. RE: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (mbaker -at- analecta -dot- com)
 14. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Robert Lauriston)
 15. RE: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Wright, Lynne)
 16. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Elisa R. Sawyer)
 17. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Elisa R. Sawyer)
 18. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Robert Lauriston)
 19. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Monique Semp)
 20. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Elisa R. Sawyer)
 21. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Robert Lauriston)
 22. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Gene Kim-Eng)
 23. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Robert Lauriston)
 24. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Gene Kim-Eng)
 25. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Simon North)
 26. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Elisa R. Sawyer)
 27. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Bee Hanson)
 28. RE: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (mbaker -at- analecta -dot- com)
 29. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Robert Lauriston)
 30. RE: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Wright, Lynne)
 31. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Robert Lauriston)
 32. Re: Ethics in Technical Writing (Lauren)
 33. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stuff for the beginner"] (Elisa R. Sawyer)
 34. Re: Ethics in Technical Writing (Lauren)
 35. RE: Structured stuff for the beginner (Janoff, Steven)
 36. Re: Ethics in Technical Writing (Robert Lauriston)
 37. Re: Ethics in Technical Writing (Lauren)
 38. Re: Mark Baker's next book [was hijacked thread "Re:
   Structured stufffor the beginner"] (Helen OBoyle)
 39. Re: Ethics in Technical Writing (Gene Kim-Eng)
 40. Re: Ethics in Technical Writing (Robert Lauriston)
 41. RE: Structured stuff for the beginner (Janoff, Steven)
 42. Re: Structured stuff for the beginner (Simon North)
 43. RE: Structured stuff for the beginner (Janoff, Steven)
----------------------------------------------------------------------
Message: 1
Date: Tue, 2 May 2017 10:45:18 +0000 (UTC)
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: RE: Structured stuff for the beginner
Message-ID: <1062631945 -dot- 477853 -dot- 1493721918019 -at- mail -dot- yahoo -dot- com>
Content-Type: text/plain; charset=UTF-8
First let me say, this has wandered pretty far from the stated thread subject.? But that's the fun of it...
I have to take issue with some statements.? I'll start with this one:
============
Traditional document structures tie you to the document structure youchoose. If you chose to use a list, it stays a list. If you chose to use a
table, it stays a table, because we don't know enough about the information
in those structures to do anything else with them.
===========
In terms of markup that simply isn't true.? There are so many points to make:
I've switched over to LightWeight DITA -- XDITA as they call the XML implementation.? I could rant forever about how less is more, and I still haven't had time to fully exploit the subset of XDITA that I currently use...? But to the point, XDITA includes a DATA element, which means you can add arbitrary metadata to just about any element in the spec. This means you can capture whatever data you deem important...? You can express subject domain and more if you wish.
We specifically had to implement a list as a table - FrameMaker has trouble with conrefs to table pieces and we wanted variable tables that use different rows depending on context. We implemented a definition list, and display it as a table in HTML -- no problem.? I know that SAP injects javascript into their table representations to give them behavior -- a table is MORE than a table in that case.
But to really tackle this you have to ask what makes a table a table and not a list?? Is it just the way you display it?? Of course not.? What makes a table is the 2D or 3D set of relationships...? Or? pivot table might have more dimensions.? Rendering is just about taking advantage of those relationships.? On paper you're often stuck with what we call tables, even if you could imagine a better way to represent the same information.? Online docs can do other things -- I suggest you look at the d3.js gallery for ideas...? It's pretty amazing!https://github.com/d3/d3/wiki/gallery
You can imagine I would say this...? I've used d3 in docs to render tabular data in different ways.? I've even done this with real-time data from the product I'm documenting.? So a table can become an image, it can exhibit behavior, it can zoom in or out, it can express relationships in various ways.? This is because the key to markup is separating data from rendering.? So if you lump XML and even DITA, or even HTML in with "traditional document structure" then you simply cannot say a table is always and only a table.? Unless you mean a multidimensional set of relationships between data points will always be a multidimensional set of relationships between data points.
It gets more interesting.? I currently use DITA ordered lists (procedures) for the content of walk-throughs in the GUI...? Balloons that point to the GUI widgets and give instructions.? In the metadata I provide a selector for the widget and other display-related info.? I transform the DITA into JSON, and we can do anything with it that we want.? When I put the same procedure out to HTML or PDF, the metadata just falls through and it looks like a list in document.? So a list is not always a list, either.? Or well...? A list is always a sequential grouping of individual points, but you can display it however you want.
Now our subject is a product -- More specifically a product GUI.? I can exploit this domain to not only manage the narrative, but to also bring the product into the docs, and put the docs into the product.? Have I implemented a model that guides me through authoring for this?? No -- I have lots to say about that as you can imagine.? But in terms of reaching beyond a document domain and into a subject domain, I believe I can demonstrate that it's entirely possible with XDITA, and that XDITA is nicely suited to the task.?
Could there be something better than XDITA?? Of course.? But in the real world you have to use what's available.? Also, XDITA has the benefit of a standards body, and lots of compatible tooling -- much of it free.? And finally, XDITA is pretty simple.? In spite of that simplicity, I challenge anybody out there to exhaust its potential.? I'm sure I never will.
------------------------------
Message: 2
Date: Tue, 2 May 2017 07:16:51 -0400
From: <mbaker -at- analecta -dot- com>
To: "'Chris Despopoulos'" <despopoulos_chriss -at- yahoo -dot- com>,
ÂÂÂ <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: RE: Structured stuff for the beginner
Message-ID: <008301d2c335$99489700$cbd9c500$ -at- analecta -dot- com>
Content-Type: text/plain;ÂÂÂ charset="utf-8"
Chris,
If you take a traditional document structure and add a bunch of subject domain metadata to it so that you know what is in each row and column, then is it no longer a traditional document structure. You have turned it into a record set. Perhaps it is a little more verbose in its markup than if you had set out from scratch to create a record set, but it is still a record set, and as such can be transformed into all kinds of things.
The key is to apply the appropriate metadata to the content so that you preserve the possibilities inherent in it. The syntax matters, in that a more verbose syntax is more overhead, but the fundamental properties are the same.
Can you do this in DITA? Yes. You moved your content to the subject domain in DITA, and that gives you the advantages of the subject domain. Congratulations. That's a good thing and I am glad to hear about it.
Is DITA the most elegant tool imaginable for doing this? No.
Do I think people using DITA should use features like these to move their content to the subject domain when it is beneficial to do so? Yes.
Am I happy to see DITA moving in the direction of providing greater support for working in the subject domain? Yes, absolutely. Getting people moving to the subject domain is my priority.
Do I acknowledge the value of using a widely-supported technology, even if it is not ideal in all its particulars? Yes.
Do I think DITA represents an end state of documentation technology beyond which no worthwhile development is possible or should be contemplated? No.
Mark
> -----Original Message-----
> From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com
> [mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On
> Behalf Of Chris Despopoulos
> Sent: Tuesday, May 2, 2017 6:45 AM
> To: techwr-l -at- lists -dot- techwr-l -dot- com
> Subject: RE: Structured stuff for the beginner
>
> First let me say, this has wandered pretty far from the stated thread
> subject. But that's the fun of it...
> I have to take issue with some statements. I'll start with this one:
> ============
> Traditional document structures tie you to the document structure
> youchoose. If you chose to use a list, it stays a list. If you chose to use a table,
> it stays a table, because we don't know enough about the information in
> those structures to do anything else with them.
> ===========
> In terms of markup that simply isn't true. There are so many points to make:
> I've switched over to LightWeight DITA -- XDITA as they call the XML
> implementation. I could rant forever about how less is more, and I still
> haven't had time to fully exploit the subset of XDITA that I currently
> use... But to the point, XDITA includes a DATA element, which means you
> can add arbitrary metadata to just about any element in the spec. This
> means you can capture whatever data you deem important... You can
> express subject domain and more if you wish.
> We specifically had to implement a list as a table - FrameMaker has trouble
> with conrefs to table pieces and we wanted variable tables that use different
> rows depending on context. We implemented a definition list, and display it
> as a table in HTML -- no problem. I know that SAP injects javascript into their
> table representations to give them behavior -- a table is MORE than a table in
> that case.
> But to really tackle this you have to ask what makes a table a table and not a
> list? Is it just the way you display it? Of course not. What makes a table is
> the 2D or 3D set of relationships... Or pivot table might have more
> dimensions. Rendering is just about taking advantage of those
> relationships. On paper you're often stuck with what we call tables, even if
> you could imagine a better way to represent the same information. Online
> docs can do other things -- I suggest you look at the d3.js gallery for
> ideas... It's pretty amazing!https://github.com/d3/d3/wiki/gallery
> You can imagine I would say this... I've used d3 in docs to render tabular
> data in different ways. I've even done this with real-time data from the
> product I'm documenting. So a table can become an image, it can exhibit
> behavior, it can zoom in or out, it can express relationships in various
> ways. This is because the key to markup is separating data from
> rendering. So if you lump XML and even DITA, or even HTML in with
> "traditional document structure" then you simply cannot say a table is always
> and only a table. Unless you mean a multidimensional set of relationships
> between data points will always be a multidimensional set of relationships
> between data points.
> It gets more interesting. I currently use DITA ordered lists (procedures) for
> the content of walk-throughs in the GUI... Balloons that point to the GUI
> widgets and give instructions. In the metadata I provide a selector for the
> widget and other display-related info. I transform the DITA into JSON, and
> we can do anything with it that we want. When I put the same procedure
> out to HTML or PDF, the metadata just falls through and it looks like a list in
> document. So a list is not always a list, either. Or well... A list is always a
> sequential grouping of individual points, but you can display it however you
> want.
>
> Now our subject is a product -- More specifically a product GUI. I can exploit
> this domain to not only manage the narrative, but to also bring the product
> into the docs, and put the docs into the product. Have I implemented a
> model that guides me through authoring for this? No -- I have lots to say
> about that as you can imagine. But in terms of reaching beyond a document
> domain and into a subject domain, I believe I can demonstrate that it's
> entirely possible with XDITA, and that XDITA is nicely suited to the task.
>
> Could there be something better than XDITA? Of course. But in the real
> world you have to use what's available. Also, XDITA has the benefit of a
> standards body, and lots of compatible tooling -- much of it free. And finally,
> XDITA is pretty simple. In spite of that simplicity, I challenge anybody out
> there to exhaust its potential. I'm sure I never will.
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as mbaker -at- analecta -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email
> archives @ http://techwr-l.com/archives
------------------------------
Message: 3
Date: Tue, 2 May 2017 12:11:31 +0000 (UTC)
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>,
ÂÂÂ "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Structured stuff for the beginner
Message-ID: <1978791409 -dot- 531120 -dot- 1493727091630 -at- mail -dot- yahoo -dot- com>
Content-Type: text/plain; charset=UTF-8
So we're in violent agreement.?
A priority of mine is to define the terms of what we do in ways that open our thinking about it.? I'll insist that there is no necessary restriction of DITA to "traditional document structure".? Outside of our thinking about it, and the language we use to express our thinking, that is.? Sure there can always be something better.? But digging in and doing it now helps flesh out the issues to inform that evolution.
One detail though...? You don't necessarily need to add excessive metadata to your "record set".? One idea behind DITA is that you render the same things differently, depending on the render context.? In many cases, knowing the larger context, plus semantics (defList, ol, ul, glossary, etc.), is enough.? This is especially true if you render at the last minute (dynamic rendering at request time).
Yes, sometimes you need to add special-case metadata at a finer level.? But not always.? And anyway, in my experience determining the data values to add in is the big issue...? Squirting it into whatever markup is relatively trivial.
   From: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>
To: 'Chris Despopoulos' <despopoulos_chriss -at- yahoo -dot- com>; techwr-l -at- lists -dot- techwr-l -dot- com
Sent: Tuesday, May 2, 2017 7:18 AM
Subject: RE: Structured stuff for the beginner
Â
Chris,
If you take a traditional document structure and add a bunch of subject domain metadata to it so that you know what is in each row and column, then is it no longer a traditional document structure. You have turned it into a record set.? Perhaps it is a little more verbose in its markup than if you had set out from scratch to create a record set, but it is still a record set, and as such can be transformed into all kinds of things.
The key is to apply the appropriate metadata to the content so that you preserve the possibilities inherent in it. The syntax matters, in that a more verbose syntax is more overhead, but the fundamental properties are the same.
Can you do this in DITA? Yes. You moved your content to the subject domain in DITA, and that gives you the advantages of the subject domain. Congratulations. That's a good thing and I am glad to hear about it.
Is DITA the most elegant tool imaginable for doing this? No.
Do I think people using DITA should use features like these to move their content to the subject domain when it is beneficial to do so? Yes.
Am I happy to see DITA moving in the direction of providing greater support for working in the subject domain? Yes, absolutely. Getting people moving to the subject domain is my priority.
Do I acknowledge the value of using a widely-supported technology, even if it is not ideal in all its particulars? Yes.
Do I think DITA represents an end state of documentation technology beyond which no worthwhile development is possible or should be contemplated? No.
Mark
Â
------------------------------
Message: 4
Date: Tue, 2 May 2017 08:48:58 -0400
From: <mbaker -at- analecta -dot- com>
To: "'Chris Despopoulos'" <despopoulos_chriss -at- yahoo -dot- com>,ÂÂÂ "'TECHWR-L'"
ÂÂÂ <techwr-l -at- techwr-l -dot- com>
Subject: RE: Structured stuff for the beginner
Message-ID: <00d101d2c342$7755df60$66019e20$ -at- analecta -dot- com>
Content-Type: text/plain;ÂÂÂ charset="utf-8"
Yes, all context information is also metadata. (That is not a DITA idea. It is a structured writing idea.)
The recipe ingredients examples is one in which your need the fine grained metadata because ordinary list or table markup would not distinguish ingredient, quantity, and unit even if the list was inside an ?ingredients? structure that provided the context that these were ingredients.
But on the other hand, you can use an ordinary ordered list under a ?preparation? structure and still render it differently from other ordered lists because you know from its context that it is actually a set of preparation steps.
Context is extremely powerful, which is precisely why you want custom subject domain markup languages, not semantic overlays on generic document domain languages. (At least for writing. The semantic overlay makes sense for publishing, in some cases.)
How much syntax matters depend on who your contributors are. For someone who groks how the whole system works and works with it every day, squirting the data into whatever markup may be trivial (though personally, I still want to optimize it for my own use). For an occasional contributor, or even a fulltime writer who is not conversant with be guts of the machine, the difference syntax makes is like night and day. Getting the maximum reliable metadata out of the least intrusive most intuitive syntax is crucial.
Part of my crusade is to get away from the situation we have had for several decades now in which the writer is required to be conversant with the guts of the publishing system. It warps everything we do: how we train, how we hire, how we work, and how we work with others. We need to get away from this and let content engineers be content engineers and writers be writers again.
Mark
From: Chris Despopoulos [mailto:despopoulos_chriss -at- yahoo -dot- com]
Sent: Tuesday, May 2, 2017 8:12 AM
To: mbaker -at- analecta -dot- com; techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Structured stuff for the beginner
So we're in violent agreement.Â
A priority of mine is to define the terms of what we do in ways that open our thinking about it. I'll insist that there is no necessary restriction of DITA to "traditional document structure". Outside of our thinking about it, and the language we use to express our thinking, that is. Sure there can always be something better. But digging in and doing it now helps flesh out the issues to inform that evolution.
One detail though... You don't necessarily need to add excessive metadata to your "record set". One idea behind DITA is that you render the same things differently, depending on the render context. In many cases, knowing the larger context, plus semantics (defList, ol, ul, glossary, etc.), is enough. This is especially true if you render at the last minute (dynamic rendering at request time).
Yes, sometimes you need to add special-case metadata at a finer level. But not always. And anyway, in my experience determining the data values to add in is the big issue... Squirting it into whatever markup is relatively trivial.
 _____Â
From: "mbaker -at- analecta -dot- com <mailto:mbaker -at- analecta -dot- com> " <mbaker -at- analecta -dot- com <mailto:mbaker -at- analecta -dot- com> >
To: 'Chris Despopoulos' <despopoulos_chriss -at- yahoo -dot- com <mailto:despopoulos_chriss -at- yahoo -dot- com> >; techwr-l -at- lists -dot- techwr-l -dot- com <mailto:techwr-l -at- lists -dot- techwr-l -dot- com>Â
Sent: Tuesday, May 2, 2017 7:18 AM
Subject: RE: Structured stuff for the beginner
Chris,
If you take a traditional document structure and add a bunch of subject domain metadata to it so that you know what is in each row and column, then is it no longer a traditional document structure. You have turned it into a record set. Perhaps it is a little more verbose in its markup than if you had set out from scratch to create a record set, but it is still a record set, and as such can be transformed into all kinds of things.
The key is to apply the appropriate metadata to the content so that you preserve the possibilities inherent in it. The syntax matters, in that a more verbose syntax is more overhead, but the fundamental properties are the same.
Can you do this in DITA? Yes. You moved your content to the subject domain in DITA, and that gives you the advantages of the subject domain. Congratulations. That's a good thing and I am glad to hear about it.
Is DITA the most elegant tool imaginable for doing this? No.
Do I think people using DITA should use features like these to move their content to the subject domain when it is beneficial to do so? Yes.
Am I happy to see DITA moving in the direction of providing greater support for working in the subject domain? Yes, absolutely. Getting people moving to the subject domain is my priority.
Do I acknowledge the value of using a widely-supported technology, even if it is not ideal in all its particulars? Yes.
Do I think DITA represents an end state of documentation technology beyond which no worthwhile development is possible or should be contemplated? No.
Mark
------------------------------
Message: 5
Date: Tue, 2 May 2017 13:38:38 +0000
From: "Wright, Lynne" <Lynne -dot- Wright -at- Kronos -dot- com>
To: Robert Lauriston <robert -at- lauriston -dot- com>, TECHWR-L Writing
ÂÂÂ <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: RE: Ethics in Technical Writing
Message-ID:
ÂÂÂ <BAD146C4BAEA60428CA4F7C691AF0DFB2B1DB797 -at- MTL-MBX01 -dot- KRONOS -dot- com>
Content-Type: text/plain; charset="utf-8"
I found this whole ethics thing to be an odd tangent too.
Trying to produce the best possible work and taking responsibility if you screw up is just being professional. I don't see it as an ethical triumph; its just the baseline standard for any professional-level job.
If the original poster didn't see any syntaxical ambiguity in the problematic text that they posted, it doesn't imply a lapse in ethics -- it just means that they didn't see it.... and/or they realized that the sentence needed clarification, which is why they posted their question in the first place. Either way, to use their (grammatical) question as a springboard for a discussion on the lack of ethical rigour seems a little misplaced.
-----Original Message-----
From: techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Robert Lauriston
Sent: May-01-17 6:39 PM
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Ethics in Technical Writing
I'd verify whether the phrase was verbatim or some random jargon the original poster made up before questioning their professional competence or ethics.
Absent that information, discussing ethics as if it were relevant to the post seems rude to me.
https://www.youtube.com/watch?v=kQFKtI6gn9Y
On Mon, May 1, 2017 at 12:42 PM, Lauren <lauren -at- writeco -dot- net> wrote:
> I?m not discussing the ?phrase in question,? I?m discussing the
> ethical principle that the discussion about the phrase raised. Perhaps
> you do not value ethics in technical writing. Your statement about the
> phrase being ?an actual quote or just some random jargon,? underscores
> the need of technical writing ethics. ...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as Lynne -dot- Wright -at- kronos -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
------------------------------
Message: 6
Date: Tue, 2 May 2017 07:53:03 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Mark Baker's next book [was hijacked thread "Re: Structured
ÂÂÂ stuff forÂÂÂ the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4BbmvP01c23=cpz3kpvgRM+488F+T0e0OGhEPEEP2w0uA -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
What on earth are you talking about?
Few tech writers currently have to be very conversant with the guts of
our tools. Small teams use FrameMaker or Flare or some other
commercial software that hides the gory details. Large teams with
custom tool chains have developers on staff.
Who were these "content engineers" from "several decades" ago that let
"writers be writers"? Layout artists with hot wax and blue pencils?
Hot lead typesetters and printing press operators?
On Tue, May 2, 2017 at 5:48 AM, <mbaker -at- analecta -dot- com> wrote:
> ... Part of my crusade is to get away from the situation we have had for several decades now in which the writer is required to be conversant with the guts of the publishing system. It warps everything we do: how we train, how we hire, how we work, and how we work with others. We need to get away from this and let content engineers be content engineers and writers be writers again. ...
------------------------------
Message: 7
Date: Tue, 2 May 2017 08:50:26 -0700
From: Gene Kim-Eng <techwr -at- genek -dot- com>
To: Robert Lauriston <robert -at- lauriston -dot- com>,ÂÂÂ TECHWR-L Writing
ÂÂÂ <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Ethics in Technical Writing
Message-ID: <829fc9d3-67b9-85ec-113d-dcdc255b5bc2 -at- genek -dot- com>
Content-Type: text/plain; charset=utf-8; format=flowed
Ethical issues in technical writing arise when your employer or client
wants you to put things in documents that you know are false, like
safety certifications for products you know haven't had their safety
evaluated, or to leave out critical items like hazard warnings.
Worrying about about questions of correct grammar vs jargon in
noncritical verbiage that doesn't impact actual usage may be a little
bit pedantic, but being a little bit pedantic is one of the things
technical writers are paid to do. Being VERY pedantic and conflating
pedantic matters with "ethics" is one reason why many people regard
technical writers as crybabies.
Gene Kim-Eng
---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus
------------------------------
Message: 8
Date: Tue, 2 May 2017 09:09:22 -0700
From: Gene Kim-Eng <techwr -at- genek -dot- com>
To: Robert Lauriston <robert -at- lauriston -dot- com>, TECHWR-L
ÂÂÂ <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID: <7af54fcb-c076-ec3b-c0c3-9096f3805eca -at- genek -dot- com>
Content-Type: text/plain; charset=windows-1252; format=flowed
My very first job as a technical writer in 1991 was for a company that
had illustrators, DTP operators and editors on staff. I wrote my drafts
in unformatted Word, sent them in and got printouts of formatted
documents back to review. Was actually kind of nice.
Prior to that, in my last job as an engineer I sent handwritten drafts
to the "technical writers," who did stuff on a mainframe that I never
actually watched them do and returned printouts of text and graphics to
me to review. That was the last place I saw final documents being made
with cameras, frisket and blue pencils.
Gene Kim-Eng
On 5/2/2017 7:53 AM, Robert Lauriston wrote:
>
> Who were these "content engineers" from "several decades" ago that let
> "writers be writers"? Layout artists with hot wax and blue pencils?
> Hot lead typesetters and printing press operators?
---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus
------------------------------
Message: 9
Date: Tue, 2 May 2017 16:13:41 +0000
From: "Wright, Lynne" <Lynne -dot- Wright -at- Kronos -dot- com>
To: Gene Kim-Eng <techwr -at- genek -dot- com>, Robert Lauriston
ÂÂÂ <robert -at- lauriston -dot- com>, ÂÂÂ TECHWR-L Writing
ÂÂÂ <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: RE: Ethics in Technical Writing
Message-ID:
ÂÂÂ <BAD146C4BAEA60428CA4F7C691AF0DFB2B1DB7F5 -at- MTL-MBX01 -dot- KRONOS -dot- com>
Content-Type: text/plain; charset="us-ascii"
"crybabies" brings to mind a particularly emotional meeting of the tech writing team that I once worked with.
As editor, I decided that we needed to nail down a style guide. My supervisor *suggested* that it would be good for team-building to hold regular meetings to try to get consensus on points of style, so I resigned myself to a process that I knew would just be unproductive chaos.
By the third meeting, I was bracing myself for yet another futile debate over whether to add punctuation to bulleted list points; which would absolutely be a battle of pedantics, as the previous meetings had been.
Instead, somebody started complaining about the fact that I used red ink to edit the hard copies of their work (as was the norm back in those days). They felt that red was "too violent and upsetting", and I should use green or purple ink instead. When I tried to reason that red ink just stands out best, things went off the rails, as each person chimed in with their "ethical" 2 cents about ink colors, and egos ran wild.Â
That was the last style meeting I called.
-----Original Message-----
From: techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Gene Kim-Eng
Sent: May-02-17 11:50 AM
To: Robert Lauriston <robert -at- lauriston -dot- com>; TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Ethics in Technical Writing
Ethical issues in technical writing arise when your employer or client wants you to put things in documents that you know are false, like safety certifications for products you know haven't had their safety evaluated, or to leave out critical items like hazard warnings.
Worrying about about questions of correct grammar vs jargon in noncritical verbiage that doesn't impact actual usage may be a little bit pedantic, but being a little bit pedantic is one of the things technical writers are paid to do. Being VERY pedantic and conflating pedantic matters with "ethics" is one reason why many people regard technical writers as crybabies.
Gene Kim-Eng
---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as Lynne -dot- Wright -at- kronos -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
------------------------------
Message: 10
Date: Tue, 2 May 2017 18:31:08 +0200
From: Simon North <simonxml -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CAOPA_kWvV55xVWEXmpRxxj792hkAFGgT_omTf_sxafRrYfBXZw -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
Happy days.
At a certain jet aircraft undercarriage company you had to send your
handwritten copy to the typing pool, correct the typed drafts by hand and
send them back for correction.
At a certain world famous electronics company in the Netherlands, we made
screen shots with a camera (a double exposure, once with the room lights
on, once with them off worked wonders), mounted the prints under talc and
wrote borders and scaling factors on them with a blue pencil (still have
some) and pasted the scaled prints with scissors and glue onto the final
camera copy.
I did my internship in a letterset printer, made printing plates using a
rostrum camera, learned DTP, taught myself Lisp so I could get the most out
of Interleaf, learned DSSSL to get the most out of SGML, learned Perl,
Python and C so I could do more with text, learned MIF and RTF/WordBasic so
I could get the most out of Frame and Word, wrapped my head round HyTime
and co-wrote the first ever book on XML .... how can you be a serious
*technical
*writer without wanting to know how your tools work? their weaknesses and
strengths, their flaws and how to get the best out of them? Without that
you're just a wordsmith.
Simon.
On Tue, May 2, 2017 at 6:09 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
> My very first job as a technical writer in 1991 was for a company that had
> illustrators, DTP operators and editors on staff. I wrote my drafts in
> unformatted Word, sent them in and got printouts of formatted documents
> back to review. Was actually kind of nice.
>
> Prior to that, in my last job as an engineer I sent handwritten drafts to
> the "technical writers," who did stuff on a mainframe that I never actually
> watched them do and returned printouts of text and graphics to me to
> review. That was the last place I saw final documents being made with
> cameras, frisket and blue pencils.
>
> Gene Kim-Eng
>
>
> On 5/2/2017 7:53 AM, Robert Lauriston wrote:
>
>>
>> Who were these "content engineers" from "several decades" ago that let
>> "writers be writers"? Layout artists with hot wax and blue pencils?
>> Hot lead typesetters and printing press operators?
>>
>
>
> ---
> This email has been checked for viruses by Avast antivirus software.
> https://www.avast.com/antivirus
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as Simonxml -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
------------------------------
Message: 11
Date: Tue, 2 May 2017 16:34:43 +0000
From: Doug Grossman <Doug -dot- Grossman -at- sas -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID: <ee318111189442f6a9f82914876b0dbc -at- MERCMBX41R -dot- na -dot- SAS -dot- com>
Content-Type: text/plain; charset="us-ascii"
What's wrong with being a wordsmith? Wordsmiths have their place in the world, just as any other profession.
-----Original Message-----
From: techwr-l-bounces+doug -dot- grossman=sas -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+doug -dot- grossman=sas -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Simon North
Subject: Re: Mark Baker's next book [was hijacked thread "Re: Structured stuff for the beginner"]
how can you be a serious *technical *writer without wanting to know how your tools work? their weaknesses and strengths, their flaws and how to get the best out of them? Without that you're just a wordsmith.
------------------------------
Message: 12
Date: Tue, 2 May 2017 11:41:39 -0500
From: Sarah Kiniry <sarah -dot- kiniry -at- cpanel -dot- net>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID: <86A267BA-D64C-42D4-BBB5-6840F4D679D7 -at- cpanel -dot- net>
Content-Type: text/plain;ÂÂÂ charset=utf-8
More importantly, where does that logical chain end? Do I have to learn how to build the laptop that I work on before I become more than a mere typist? Do I have to learn how to generate electricity before I can use it to do my job?
Let the people whose job it is to build tools build them well, and let?s focus on how we use them to do that wordsmithing that keeps us from just being content-focused system administrators. As technology advances, the whole point is allowing the tools to do the work so that we can specialize in the stuff they *can?t* do.
Sarah Kiniry
Technical Writer II
cPanel, Inc.
sarah -dot- kiniry -at- cpanel -dot- net
> On May 2, 2017, at 11:34 AM, Doug Grossman <Doug -dot- Grossman -at- sas -dot- com> wrote:
>
> What's wrong with being a wordsmith? Wordsmiths have their place in the world, just as any other profession.
>
> -----Original Message-----
> From: techwr-l-bounces+doug -dot- grossman=sas -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+doug -dot- grossman=sas -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Simon North
> Subject: Re: Mark Baker's next book [was hijacked thread "Re: Structured stuff for the beginner"]
>
> how can you be a serious *technical *writer without wanting to know how your tools work? their weaknesses and strengths, their flaws and how to get the best out of them? Without that you're just a wordsmith.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as sarah -dot- kiniry -at- cpanel -dot- net -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
------------------------------
Message: 13
Date: Tue, 2 May 2017 13:14:24 -0400
From: <mbaker -at- analecta -dot- com>
To: "'Sarah Kiniry'" <sarah -dot- kiniry -at- cpanel -dot- net>,ÂÂÂ "'TECHWR-L'"
ÂÂÂ <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stuffÂÂÂ for the beginner"]
Message-ID: <00f801d2c367$8bff2e10$a3fd8a30$ -at- analecta -dot- com>
Content-Type: text/plain;ÂÂÂ charset="utf-8"
> More importantly, where does that logical chain end?
This exactly. For too many years now writers have had this chain end in a cumbersome publishing and/or content management system that requires them to perform all kinds of management, organization, and document design tasks in addition to writing. These tools have impinged so much on the writer's task, that experience in them has frequently become non-negotiable job requirements. That has been true of FrameMaker for decade and is increasingly becoming true of DITA today.
Yet with a little simple markup to capture the metadata that only the writer can provide, we can make all that go away.
Technical writers already have to be masters of three things: writing, knowledge of the technology, and knowledge of the user. Adding mastery of complex publishing tools to that list sets the bar very high and it is a sad fact that in many cases it has pushed knowledge of the technology and knowledge of the user off the table, to the significant detriment of content quality.
Worse, even if a writer has all four skills, having to exercise them all at once lessens the amount of attention that can be given to each. DTP sought to put all the tools in the user's hands in order to get away from all of the time-consuming handoffs involved in the older pre-computer process. But that also put all the responsibility in the writer's hands, forcing them to become masters of trades other than their own.
Structured writing, particularly subject domain structured writing, has the capacity to deflect those responsibilities away from the writer without reintroducing the multiple handoffs of the old process. Writers have been lumbered with these additional responsibilities for so long that many have come to think of them as normal. But that is no reason for not making progress, both towards simplifying the role of the writer, and towards making our content far more versatile, more precise, and more complete than it has ever been before.
Mark
------------------------------
Message: 14
Date: Tue, 2 May 2017 10:34:29 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4BmhQpoGpbwZc2yLHwFru2ym-Qojg3veektcfJ5Fd+kGw -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
In the software industry, the knowledge and skills I need to do the
research required to write the content are the same as required to do
the "content engineering."
I'm generally much better off installing and managing my own tools
than depending on IT or some developer to do it. Confluence behaved a
lot better in the instance I installed and managed myself than in the
other instances I've used. SharePoint was not entirely unusable when I
had superuser privileges.
On Tue, May 2, 2017 at 9:41 AM, Sarah Kiniry <sarah -dot- kiniry -at- cpanel -dot- net> wrote:
> More importantly, where does that logical chain end? Do I have to learn how to build the laptop that I work on before I become more than a mere typist? Do I have to learn how to generate electricity before I can use it to do my job?
>
> Let the people whose job it is to build tools build them well, and let?s focus on how we use them to do that wordsmithing that keeps us from just being content-focused system administrators. As technology advances, the whole point is allowing the tools to do the work so that we can specialize in the stuff they *can?t* do.
------------------------------
Message: 15
Date: Tue, 2 May 2017 17:40:41 +0000
From: "Wright, Lynne" <Lynne -dot- Wright -at- Kronos -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>, 'Sarah Kiniry'
ÂÂÂ <sarah -dot- kiniry -at- cpanel -dot- net>, 'TECHWR-L' <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <BAD146C4BAEA60428CA4F7C691AF0DFB2B1DB842 -at- MTL-MBX01 -dot- KRONOS -dot- com>
Content-Type: text/plain; charset="us-ascii"
I can't agree with this notion that technical writers are primarily "wordsmiths" who shouldn't be burdened with needing other skills besides knowing how to construct an active-voice sentence.
Our job isn't to create elegant prose; its to deliver information in whatever medium is appropriate. And that necessarily entails a wide range of knowledge and skills.
For me, using a range of software tools, doing graphics and design work, advising developers on language usage and interface usability, and all the things I do besides writing are huge pluses; it would be way less interesting and fulfilling if all I did was write procedures all day.
-----Original Message-----
From: techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of mbaker -at- analecta -dot- com
Sent: May-02-17 1:14 PM
To: 'Sarah Kiniry' <sarah -dot- kiniry -at- cpanel -dot- net>; 'TECHWR-L' <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re: Structured stuff for the beginner"]
> More importantly, where does that logical chain end?
This exactly. For too many years now writers have had this chain end in a cumbersome publishing and/or content management system that requires them to perform all kinds of management, organization, and document design tasks in addition to writing. These tools have impinged so much on the writer's task, that experience in them has frequently become non-negotiable job requirements. That has been true of FrameMaker for decade and is increasingly becoming true of DITA today.
Yet with a little simple markup to capture the metadata that only the writer can provide, we can make all that go away.
Technical writers already have to be masters of three things: writing, knowledge of the technology, and knowledge of the user. Adding mastery of complex publishing tools to that list sets the bar very high and it is a sad fact that in many cases it has pushed knowledge of the technology and knowledge of the user off the table, to the significant detriment of content quality.
Worse, even if a writer has all four skills, having to exercise them all at once lessens the amount of attention that can be given to each. DTP sought to put all the tools in the user's hands in order to get away from all of the time-consuming handoffs involved in the older pre-computer process. But that also put all the responsibility in the writer's hands, forcing them to become masters of trades other than their own.
Structured writing, particularly subject domain structured writing, has the capacity to deflect those responsibilities away from the writer without reintroducing the multiple handoffs of the old process. Writers have been lumbered with these additional responsibilities for so long that many have come to think of them as normal. But that is no reason for not making progress, both towards simplifying the role of the writer, and towards making our content far more versatile, more precise, and more complete than it has ever been before.
Mark
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as Lynne -dot- Wright -at- kronos -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
------------------------------
Message: 16
Date: Tue, 2 May 2017 10:45:09 -0700
From: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
To: Simon North <simonxml -at- gmail -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CACi8M=6oXwjYr4ykVQCgp3PkXkSr-9b0BNoKwww1TmszM7oVkg -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
I got to know the guts of many tools and have occasionally fixed build
scripts.
I think, however, that hiding behind tools knowledge can be a cop-out to
get away from the really hard work of writing.
What then can happen is that talented managers and programmers start to
step in to the relative vacuum left by the fact that so few people actually
bother to learn advanced writing skills.
Not enough people actually bother to learn what those tools are, and the
fact that this is true has been shocking to me.
I'd like to learn how to better promote the idea that advanced writing
skills are worth learning.
Suggestions are welcome.
-Elisa
On Tue, May 2, 2017 at 9:31 AM, Simon North <simonxml -at- gmail -dot- com> wrote:
> Happy days.
>
> At a certain jet aircraft undercarriage company you had to send your
> handwritten copy to the typing pool, correct the typed drafts by hand and
> send them back for correction.
>
> At a certain world famous electronics company in the Netherlands, we made
> screen shots with a camera (a double exposure, once with the room lights
> on, once with them off worked wonders), mounted the prints under talc and
> wrote borders and scaling factors on them with a blue pencil (still have
> some) and pasted the scaled prints with scissors and glue onto the final
> camera copy.
>
> I did my internship in a letterset printer, made printing plates using a
> rostrum camera, learned DTP, taught myself Lisp so I could get the most out
> of Interleaf, learned DSSSL to get the most out of SGML, learned Perl,
> Python and C so I could do more with text, learned MIF and RTF/WordBasic so
> I could get the most out of Frame and Word, wrapped my head round HyTime
> and co-wrote the first ever book on XML .... how can you be a serious
> *technical
> *writer without wanting to know how your tools work? their weaknesses and
> strengths, their flaws and how to get the best out of them? Without that
> you're just a wordsmith.
>
> Simon.
>
> On Tue, May 2, 2017 at 6:09 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
>
> > My very first job as a technical writer in 1991 was for a company that
> had
> > illustrators, DTP operators and editors on staff. I wrote my drafts in
> > unformatted Word, sent them in and got printouts of formatted documents
> > back to review. Was actually kind of nice.
> >
> > Prior to that, in my last job as an engineer I sent handwritten drafts to
> > the "technical writers," who did stuff on a mainframe that I never
> actually
> > watched them do and returned printouts of text and graphics to me to
> > review. That was the last place I saw final documents being made with
> > cameras, frisket and blue pencils.
> >
> > Gene Kim-Eng
> >
> >
> > On 5/2/2017 7:53 AM, Robert Lauriston wrote:
> >
> >>
> >> Who were these "content engineers" from "several decades" ago that let
> >> "writers be writers"? Layout artists with hot wax and blue pencils?
> >> Hot lead typesetters and printing press operators?
> >>
> >
> >
> > ---
> > This email has been checked for viruses by Avast antivirus software.
> > https://www.avast.com/antivirus
> >
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Visit TechWhirl for the latest on content technology, content strategy
> and
> > content development | http://techwhirl.com
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as Simonxml -at- gmail -dot- com -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> >
> > Looking for articles on Technical Communications? Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our public
> > email archives @ http://techwr-l.com/archives
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
------------------------------
Message: 17
Date: Tue, 2 May 2017 10:51:49 -0700
From: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
To: Sarah Kiniry <sarah -dot- kiniry -at- cpanel -dot- net>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CACi8M=7EikWKJuyYPGWp1fDE-hU9ggMHpKxX6y=+mu2_1+fSTg -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
We don't even have a common understanding in our profession of whether
there is a difference between copy editing, wordsmithing, and writing. It
appears that an in-depth understanding of editing has been disappearing.
On Tue, May 2, 2017 at 9:41 AM, Sarah Kiniry <sarah -dot- kiniry -at- cpanel -dot- net>
wrote:
> More importantly, where does that logical chain end? Do I have to learn
> how to build the laptop that I work on before I become more than a mere
> typist? Do I have to learn how to generate electricity before I can use it
> to do my job?
>
> Let the people whose job it is to build tools build them well, and let?s
> focus on how we use them to do that wordsmithing that keeps us from just
> being content-focused system administrators. As technology advances, the
> whole point is allowing the tools to do the work so that we can specialize
> in the stuff they *can?t* do.
>
> Sarah Kiniry
> Technical Writer II
> cPanel, Inc.
> sarah -dot- kiniry -at- cpanel -dot- net
>
>
> > On May 2, 2017, at 11:34 AM, Doug Grossman <Doug -dot- Grossman -at- sas -dot- com>
> wrote:
> >
> > What's wrong with being a wordsmith? Wordsmiths have their place in the
> world, just as any other profession.
> >
> > -----Original Message-----
> > From: techwr-l-bounces+doug -dot- grossman=sas -dot- com -at- lists -dot- techwr-l -dot- com [mailto:
> techwr-l-bounces+doug -dot- grossman=sas -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of
> Simon North
> > Subject: Re: Mark Baker's next book [was hijacked thread "Re: Structured
> stuff for the beginner"]
> >
> > how can you be a serious *technical *writer without wanting to know how
> your tools work? their weaknesses and strengths, their flaws and how to get
> the best out of them? Without that you're just a wordsmith.
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Visit TechWhirl for the latest on content technology, content strategy
> and content development | http://techwhirl.com
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as sarah -dot- kiniry -at- cpanel -dot- net -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources
> and info.
> >
> > Looking for articles on Technical Communications? Head over to our
> online magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
------------------------------
Message: 18
Date: Tue, 2 May 2017 10:51:49 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4A2ih53iJ1P1b1FnVzjhZkgwX2HPxyLJ=5xMy698T2uXA -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
The hell you say. I spend 90% of my time researching and writing
content. Scripts and templates automate the output. That's been true
for Paligo, Confluence, FrameMaker, Flare, and various other tools.
I've been the technical lead on several teams, as well as a solo
writer, and infrastructure takes up very little of my time. Once in a
long while I'll have to spend most of my time for a few weeks doing
something such as developing a template for a new output format or
migrating to a different tool or source control system, or a few hours
or days troubleshooting a bug. The rest of the time the tools are on
autopilot.
Tools are not that big a deal. Any good docs manager or technical lead
can train a good writer to use any tool in a few weeks.
On Tue, May 2, 2017 at 10:14 AM, <mbaker -at- analecta -dot- com> wrote:
>> ... For too many years now writers have had this chain end in a cumbersome publishing and/or content management system that requires them to perform all kinds of management, organization, and document design tasks in addition to writing. These tools have impinged so much on the writer's task, that experience in them has frequently become non-negotiable job requirements. That has been true of FrameMaker for decade and is increasingly becoming true of DITA today.
>
> Yet with a little simple markup to capture the metadata that only the writer can provide, we can make all that go away.
>
> Technical writers already have to be masters of three things: writing, knowledge of the technology, and knowledge of the user. Adding mastery of complex publishing tools to that list sets the bar very high and it is a sad fact that in many cases it has pushed knowledge of the technology and knowledge of the user off the table, to the significant detriment of content quality.
>
> Worse, even if a writer has all four skills, having to exercise them all at once lessens the amount of attention that can be given to each. DTP sought to put all the tools in the user's hands in order to get away from all of the time-consuming handoffs involved in the older pre-computer process. But that also put all the responsibility in the writer's hands, forcing them to become masters of trades other than their own.
>
> Structured writing, particularly subject domain structured writing, has the capacity to deflect those responsibilities away from the writer without reintroducing the multiple handoffs of the old process. Writers have been lumbered with these additional responsibilities for so long that many have come to think of them as normal. But that is no reason for not making progress, both towards simplifying the role of the writer, and towards making our content far more versatile, more precise, and more complete than it has ever been before.
------------------------------
Message: 19
Date: Tue, 2 May 2017 11:04:06 -0700
From: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>
To: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>, "Simon North"
ÂÂÂ <simonxml -at- gmail -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID: <34D7BBBC65774451A29C12E667AAB631 -at- WQI1509Dell>
Content-Type: text/plain; format=flowed; charset="iso-8859-1";
ÂÂÂ reply-type=original
> I'd like to learn how to better promote the idea that advanced writing
skills are worth learning.
Unfortunately, I think that in 2017, at least in the software industry, it's
a lost battle. Whether or not a shop is "officially agile", the plain truth
is that writers are told to do work that's "good enough". I see job ads that
explicitly state that the candidate must balance accuracy and speed, and
that speed is definitely the more important "quality". (I wish I could
remember the exact wording, but I'm sure I'll see it again.) What goes out
the door is often pretty much a first draft. Everyone knows that at best the
writing isn't great and that it will cause users some confusion, and that at
worst there are multiple errors (often due to late-changing software, not
due to writers not being diligent) that we'll just correct after customers
submit support problems.
This is a major failing in business at large, not simply a failing of a
specific industry or job function. I seriously looked into switching to
medical writing not too long ago, largely because I wanted to work in an
industry that valued quality. But I was extremely disheartened to find that
even n the medical industry, speed and price are more important than
quality. I currently subscribe to the AMWA (American Medical Writers
Association) member email list, and the issues posted there are very similar
to our Tech-WR-L issues.
> We don't even have a common understanding in our profession of whether
there is a difference between copy editing, wordsmithing, and writing. It
appears that an in-depth understanding of editing has been disappearing.
Yes, that's for sure. And I don't see it ever returning :-(.
Sigh. Now back to my day, playing with Jekyll. Yes, I'm a content writer,
and a tools person, and in 2017 a writer must be both.
-Monique
------------------------------
Message: 20
Date: Tue, 2 May 2017 11:17:10 -0700
From: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID:
ÂÂÂ <CACi8M=4_VPoo6EYXpJz7hwkm5QtjPJrft0Qt9-_-1goB_6KbEw -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
Yes, a writer must be both. Today I am starting to tweak pdf output from
asciidoc. It looks pretty straightforward. I also am looking into the pub
output from asciidoc, which also looks fairly straightforward. Kudos to Dan
Allen, whose commitment to asciidoctor has made it the awesome tool it is
today!
BTW, I'm not completely against Agile. I've enjoyed working with some
*well-managed* agile teams that valued my contribution as a writer.
Some, but not all. :-)
-Elisa
On Tue, May 2, 2017 at 11:04 AM, Monique Semp <monique -dot- semp -at- earthlink -dot- net>
wrote:
> I'd like to learn how to better promote the idea that advanced writing
>>
> skills are worth learning.
>
> Unfortunately, I think that in 2017, at least in the software industry,
> it's a lost battle. Whether or not a shop is "officially agile", the plain
> truth is that writers are told to do work that's "good enough". I see job
> ads that explicitly state that the candidate must balance accuracy and
> speed, and that speed is definitely the more important "quality". (I wish I
> could remember the exact wording, but I'm sure I'll see it again.) What
> goes out the door is often pretty much a first draft. Everyone knows that
> at best the writing isn't great and that it will cause users some
> confusion, and that at worst there are multiple errors (often due to
> late-changing software, not due to writers not being diligent) that we'll
> just correct after customers submit support problems.
>
> This is a major failing in business at large, not simply a failing of a
> specific industry or job function. I seriously looked into switching to
> medical writing not too long ago, largely because I wanted to work in an
> industry that valued quality. But I was extremely disheartened to find that
> even n the medical industry, speed and price are more important than
> quality. I currently subscribe to the AMWA (American Medical Writers
> Association) member email list, and the issues posted there are very
> similar to our Tech-WR-L issues.
>
> We don't even have a common understanding in our profession of whether
>>
> there is a difference between copy editing, wordsmithing, and writing. It
> appears that an in-depth understanding of editing has been disappearing.
>
> Yes, that's for sure. And I don't see it ever returning :-(.
>
> Sigh. Now back to my day, playing with Jekyll. Yes, I'm a content writer,
> and a tools person, and in 2017 a writer must be both.
>
> -Monique
>
>
>
--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
------------------------------
Message: 21
Date: Tue, 2 May 2017 11:23:40 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4Ct-yT+EfqRC0ds9=hZyzifMZJ4NdU9d7xxtQCBUGnFLw -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
Accurate and comprehensive docs reduce support costs. In enterprise
software, it's common for service-level agreements to reference the
documentation to define what's supported, so inaccuracy can be
expensive.
I wonder if companies that skimp on docs have a harder time hiring and
keeping writers, so they place more help-wanted ads, giving a false
impression that skimping is common.
------------------------------
Message: 22
Date: Tue, 2 May 2017 11:27:31 -0700
From: Gene Kim-Eng <techwr -at- genek -dot- com>
To: Monique Semp <monique -dot- semp -at- earthlink -dot- net>,ÂÂÂ "Elisa R. Sawyer"
ÂÂÂ <elisawyer -at- gmail -dot- com>, Simon North <simonxml -at- gmail -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID: <ee9e909b-6c91-31af-fd6f-4bac3def3bfa -at- genek -dot- com>
Content-Type: text/plain; charset=windows-1252; format=flowed
Balancing ideals of quality against the need to get stuff out the door
and make money is just reality rearing its ugly head, and everybody gets
the same thing, in every industry.
You make gains by putting forth a convincing argument that your idea of
"good enough" is the right balance, not by arguing for lofty "valuing
quality" goals. Otherwise, you go into marketing, where you get points
for talking like that even if nobody else in the company is taking it
seriously.
Gene Kim-Eng
On 5/2/2017 11:04 AM, Monique Semp wrote:
>
>
> Unfortunately, I think that in 2017, at least in the software
> industry, it's a lost battle. Whether or not a shop is "officially
> agile", the plain truth is that writers are told to do work that's
> "good enough".
---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus
------------------------------
Message: 23
Date: Tue, 2 May 2017 11:36:57 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4AxaGQAWp4CyS6znivvwVDCtk7zraS1PQ5QkmBC=StEcw -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
In my work, "good enough" is most of the way to first-rate. The tech
is sufficiently complicated and non-self-explanatory that if the docs
are wrong or incomplete customers will get stuck. In the long run,
it's more efficient to get things right the first time as often as
possible.
On Tue, May 2, 2017 at 11:27 AM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
> Balancing ideals of quality against the need to get stuff out the door and
> make money is just reality rearing its ugly head, and everybody gets the
> same thing, in every industry.
>
> You make gains by putting forth a convincing argument that your idea of
> "good enough" is the right balance, not by arguing for lofty "valuing
> quality" goals. ...
------------------------------
Message: 24
Date: Tue, 2 May 2017 11:37:30 -0700
From: Gene Kim-Eng <techwr -at- genek -dot- com>
To: Robert Lauriston <robert -at- lauriston -dot- com>, TECHWR-L
ÂÂÂ <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID: <4bb92847-ad73-8b23-2895-32a2b03f4478 -at- genek -dot- com>
Content-Type: text/plain; charset=windows-1252; format=flowed
I expect they mostly use temps, leading to lots of ads from temp agencies.
Gene Kim-Eng
On 5/2/2017 11:23 AM, Robert Lauriston wrote:
>
> I wonder if companies that skimp on docs have a harder time hiring and
> keeping writers, so they place more help-wanted ads, giving a false
> impression that skimping is common.
---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus
------------------------------
Message: 25
Date: Tue, 2 May 2017 20:58:20 +0200
From: Simon North <simonxml -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID: <7E1ABA93-E622-4DBB-B92F-2F85E271C1AB -at- gmail -dot- com>
Content-Type: text/plain;ÂÂÂ charset=us-ascii
Sadly, I've been forced into that 'good enough' corner. The company where I've worked for the last 13 years was almost a startup (50 people) when I joined. It's now nearly 1200 and I'm still the only technical writer. I limit myself to R&D, where I can make the most difference, but where I once was able to keep up with 6 developers, with 65 split into 8 'agile' teams with a four-month release cycle I was forced to give up a long time ago. I gave them a wiki and now I manage, supervise, edit, train and coach, while the developers do most of the writing themselves. Most of the documentation is very technical, C++ class documentation, a programming language, GUI design tool and modeller so quality takes second place to quantity and accuracy.Â
It's become more of a challenge of late since 'my' developers are nearly all non-native speakers (we are forced to recruit from as far afield as Russia, Greece, Romania, Mexico) but accuracy and completeness are key criteria for my audience so I have learned to let go of the details.
And before anyone accuses me of being a 'techie' (yes, my comment about wordsmiths was a little tongue in cheek), apart from a degree in electronics, I do have a masters in technical writing and a bachelor degree in French and English Literature.
Simon.
> On May 2, 2017, at 20:27, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
>
> Balancing ideals of quality against the need to get stuff out the door and make money is just reality rearing its ugly head, and everybody gets the same thing, in every industry.
>
> You make gains by putting forth a convincing argument that your idea of "good enough" is the right balance, not by arguing for lofty "valuing quality" goals. Otherwise, you go into marketing, where you get points for talking like that even if nobody else in the company is taking it seriously.
>
> Gene Kim-Eng
>
>
>> On 5/2/2017 11:04 AM, Monique Semp wrote:
>>
>>
>> Unfortunately, I think that in 2017, at least in the software industry, it's a lost battle. Whether or not a shop is "officially agile", the plain truth is that writers are told to do work that's "good enough".
>
>
> ---
> This email has been checked for viruses by Avast antivirus software.
> https://www.avast.com/antivirus
>
------------------------------
Message: 26
Date: Tue, 2 May 2017 12:13:29 -0700
From: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
To: Bee Hanson <beelia -at- pacbell -dot- net>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CACi8M=66ha54vqo-QbTYihzxLWTiDqrccfoC9k2KU4dbObHqwQ -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
Bee, I can relate. In one of my contracts, was essentially given the role
of teaching a team of developers how to improve their writing. It was a
good team and they learned quickly. I was teaching mostly be example and I
enjoyed that project.
Are you stuck with DITA? If you found a better tool would you be allowed to
convert?
-Elisa
On Tue, May 2, 2017 at 11:42 AM, Bee Hanson <beelia -at- pacbell -dot- net> wrote:
> I consider myself a survivor of the tools wars, from LaTeX and Interleaf
> to FrameMaker and XMetaL. I think our profession came to a major crossroads
> in the late 90s when DITA started becoming dominant. I spent many years
> on Trisoft/SDL LCA/Astoria/AEM, but intend to never have another job that
> requires those tools. Because it takes so much time to learn DITA tools and
> processes, many writers end up just publishing content that is mediocre at
> best, so using their brains to provide useful information has to come last.
>
> Priorities have changed because of globalization. When content has to be
> localized in so many languages, it inevitably gets watered down because
> there is so much low-level work ("patterning", for example) to be done
> before translation can even start. When you have to think about stuff like
> how the Japanese language handles commas, how can you take the time to do a
> good job of explaining products?
>
> Like any other profession, we have to consider what automation and
> globalization is going to do to our jobs. I suspect that DITA tools might
> become sophisticated enough to dispense with writers altogether, and
> corporate publishing tasks might be able to be handled by a single
> information architect.
>
> I can relate to Simon's post about making it our business to continue to
> keep up with cutting-edge tools - and these days, it seems what is needed
> are engineering rather than writing tools. API and SDK tasks require
> understanding of code as well as mastery of Git, RST, cURL, Postman,
> Eclipse, and countless other engineering tools and processes. I may be
> wrong, but I think that moving in that direction is the only logical career
> path for writers who want to use their brains instead of mastering mice.
>
> I welcome dissent, but hope someone out there can relate to my DITA pain. [image:
> *~X( at wits' end]
>
> Bee
>
>
>
>
>
>
>
>
> On Tuesday, May 2, 2017 10:45 AM, Elisa R. Sawyer <elisawyer -at- gmail -dot- com>
> wrote:
>
>
> I got to know the guts of many tools and have occasionally fixed build
> scripts.
>
> I think, however, that hiding behind tools knowledge can be a cop-out to
> get away from the really hard work of writing.
>
> What then can happen is that talented managers and programmers start to
> step in to the relative vacuum left by the fact that so few people actually
> bother to learn advanced writing skills.
>
> Not enough people actually bother to learn what those tools are, and the
> fact that this is true has been shocking to me.
>
> I'd like to learn how to better promote the idea that advanced writing
> skills are worth learning.
>
> Suggestions are welcome.
>
> -Elisa
>
>
> On Tue, May 2, 2017 at 9:31 AM, Simon North <simonxml -at- gmail -dot- com> wrote:
>
> > Happy days.
> >
> > At a certain jet aircraft undercarriage company you had to send your
> > handwritten copy to the typing pool, correct the typed drafts by hand and
> > send them back for correction.
> >
> > At a certain world famous electronics company in the Netherlands, we made
> > screen shots with a camera (a double exposure, once with the room lights
> > on, once with them off worked wonders), mounted the prints under talc and
> > wrote borders and scaling factors on them with a blue pencil (still have
> > some) and pasted the scaled prints with scissors and glue onto the final
> > camera copy.
> >
> > I did my internship in a letterset printer, made printing plates using a
> > rostrum camera, learned DTP, taught myself Lisp so I could get the most
> out
> > of Interleaf, learned DSSSL to get the most out of SGML, learned Perl,
> > Python and C so I could do more with text, learned MIF and RTF/WordBasic
> so
> > I could get the most out of Frame and Word, wrapped my head round HyTime
> > and co-wrote the first ever book on XML .... how can you be a serious
> > *technical
> > *writer without wanting to know how your tools work? their weaknesses and
> > strengths, their flaws and how to get the best out of them? Without that
> > you're just a wordsmith.
> >
> > Simon.
> >
> > On Tue, May 2, 2017 at 6:09 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
> >
> > > My very first job as a technical writer in 1991 was for a company that
> > had
> > > illustrators, DTP operators and editors on staff. I wrote my drafts in
> > > unformatted Word, sent them in and got printouts of formatted documents
> > > back to review. Was actually kind of nice.
> > >
> > > Prior to that, in my last job as an engineer I sent handwritten drafts
> to
> > > the "technical writers," who did stuff on a mainframe that I never
> > actually
> > > watched them do and returned printouts of text and graphics to me to
> > > review. That was the last place I saw final documents being made with
> > > cameras, frisket and blue pencils.
> > >
> > > Gene Kim-Eng
> > >
> > >
> > > On 5/2/2017 7:53 AM, Robert Lauriston wrote:
> > >
> > >>
> > >> Who were these "content engineers" from "several decades" ago that let
> > >> "writers be writers"? Layout artists with hot wax and blue pencils?
> > >> Hot lead typesetters and printing press operators?
> > >>
> > >
> > >
> > > ---
> > > This email has been checked for viruses by Avast antivirus software.
> > > https://www.avast.com/antivirus
> > >
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > Visit TechWhirl for the latest on content technology, content strategy
> > and
> > > content development | http://techwhirl.com
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >
> > > You are currently subscribed to TECHWR-L as Simonxml -at- gmail -dot- com -dot-
> > >
> > > To unsubscribe send a blank email to
> > > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> > >
> > >
> > > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > > http://www.techwhirl.com/email-discussion-groups/ for more resources
> and
> > > info.
> > >
> > > Looking for articles on Technical Communications? Head over to our
> > online
> > > magazine at http://techwhirl.com
> > >
> > > Looking for the archived Techwr-l email discussions? Search our public
> > > email archives @ http://techwr-l.com/archives
> > >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Visit TechWhirl for the latest on content technology, content strategy
> and
> > content development | http://techwhirl.com
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> >
> > Looking for articles on Technical Communications? Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions? Search our public
> > email archives @ http://techwr-l.com/archives
> >
>
>
>
> --
> Elisa Rood Sawyer
> ~~~~~^~~~~~
> Technical and Creative Writer
> "Apparently there is nothing that cannot happen today." Mark Twain
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as beelia -at- pacbell -dot- net -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
>
>
--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
------------------------------
Message: 27
Date: Tue, 2 May 2017 18:42:20 +0000 (UTC)
From: Bee Hanson <beelia -at- pacbell -dot- net>
To: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>, Simon North
ÂÂÂ <simonxml -at- gmail -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stuffÂÂÂ for the beginner"]
Message-ID: <1230578969 -dot- 769771 -dot- 1493750540634 -at- mail -dot- yahoo -dot- com>
Content-Type: text/plain; charset=UTF-8
I consider myself a survivor of the tools wars, from LaTeX and Interleaf to FrameMaker and XMetaL. I think our profession came to a major crossroads in the late 90s when DITA started becoming dominant.?I spent many years on Trisoft/SDL LCA/Astoria/AEM, but intend to never have another job that requires those tools. Because it takes so much time to learn DITA tools and processes, many writers end up just publishing content that is mediocre at best, so using their brains to provide useful information has to come last.?
Priorities have changed because of globalization. When content has to be localized in so many languages, it inevitably gets watered down because there is so much low-level work ("patterning", for example) to be done before translation can even start. When you have to think about stuff like how the Japanese language handles commas, how can you take the time to do a good job of explaining products?
Like any other profession, we have to consider what automation and globalization is going to do to our jobs. I suspect that DITA tools might become sophisticated enough to dispense with writers altogether, and corporate publishing tasks might be able to be handled by a single information architect.?
I can relate to Simon's post about making it our business to continue to keep up with cutting-edge tools - and these days, it seems what is needed are engineering rather than writing tools. API and SDK tasks require understanding of code as well as mastery of Git, RST, cURL, Postman, Eclipse, and countless other engineering tools and processes. I may be wrong, but I think that moving in that direction is the only logical career path for writers who want to use their brains instead of mastering mice.
I welcome dissent, but hope someone out there can relate to my DITA pain.?
Bee
??
?
  On Tuesday, May 2, 2017 10:45 AM, Elisa R. Sawyer <elisawyer -at- gmail -dot- com> wrote:
I got to know the guts of many tools and have occasionally fixed build
scripts.
I think, however, that hiding behind tools knowledge can be a cop-out to
get away from the really hard work of writing.
What then can happen is that talented managers and programmers start to
step in to the relative vacuum left by the fact that so few people actually
bother to learn advanced writing skills.
Not enough people actually bother to learn what those tools are, and the
fact that this is true has been shocking to me.
I'd like to learn how to better promote the idea that advanced writing
skills are worth learning.
Suggestions are welcome.
-Elisa
On Tue, May 2, 2017 at 9:31 AM, Simon North <simonxml -at- gmail -dot- com> wrote:
> Happy days.
>
> At a certain jet aircraft undercarriage company you had to send your
> handwritten copy to the typing pool, correct the typed drafts by hand and
> send them back for correction.
>
> At a certain world famous electronics company in the Netherlands, we made
> screen shots with a camera (a double exposure, once with the room lights
> on, once with them off worked wonders), mounted the prints under talc and
> wrote borders and scaling factors on them with a blue pencil (still have
> some) and pasted the scaled prints with scissors and glue onto the final
> camera copy.
>
> I did my internship in a letterset printer, made printing plates using a
> rostrum camera, learned DTP, taught myself Lisp so I could get the most out
> of Interleaf, learned DSSSL to get the most out of SGML, learned Perl,
> Python and C so I could do more with text, learned MIF and RTF/WordBasic so
> I could get the most out of Frame and Word, wrapped my head round HyTime
> and co-wrote the first ever book on XML .... how can you be a serious
> *technical
> *writer without wanting to know how your tools work? their weaknesses and
> strengths, their flaws and how to get the best out of them? Without that
> you're just a wordsmith.
>
> Simon.
>
> On Tue, May 2, 2017 at 6:09 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
>
> > My very first job as a technical writer in 1991 was for a company that
> had
> > illustrators, DTP operators and editors on staff. I wrote my drafts in
> > unformatted Word, sent them in and got printouts of formatted documents
> > back to review. Was actually kind of nice.
> >
> > Prior to that, in my last job as an engineer I sent handwritten drafts to
> > the "technical writers," who did stuff on a mainframe that I never
> actually
> > watched them do and returned printouts of text and graphics to me to
> > review. That was the last place I saw final documents being made with
> > cameras, frisket and blue pencils.
> >
> > Gene Kim-Eng
> >
> >
> > On 5/2/2017 7:53 AM, Robert Lauriston wrote:
> >
> >>
> >> Who were these "content engineers" from "several decades" ago that let
> >> "writers be writers"? Layout artists with hot wax and blue pencils?
> >> Hot lead typesetters and printing press operators?
> >>
> >
> >
> > ---
> > This email has been checked for viruses by Avast antivirus software.
> > https://www.avast.com/antivirus
> >
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Visit TechWhirl for the latest on content technology, content strategy
> and
> > content development | http://techwhirl.com
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as Simonxml -at- gmail -dot- com -dot-
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> >
> > Looking for articles on Technical Communications?? Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions?? Search our public
> > email archives @ http://techwr-l.com/archives
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications?? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions?? Search our public
> email archives @ http://techwr-l.com/archives
>
--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as beelia -at- pacbell -dot- net -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications?? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions?? Search our public email archives @ http://techwr-l.com/archives
Â
------------------------------
Message: 28
Date: Tue, 2 May 2017 15:31:42 -0400
From: <mbaker -at- analecta -dot- com>
To: "'Robert Lauriston'" <robert -at- lauriston -dot- com>,ÂÂÂ "'TECHWR-L'"
ÂÂÂ <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stuffÂÂÂ for the beginner"]
Message-ID: <010a01d2c37a$ba8524c0$2f8f6e40$ -at- analecta -dot- com>
Content-Type: text/plain;ÂÂÂ charset="us-ascii"
> Any good docs manager or technical lead can
> train a good writer to use any tool in a few weeks.
Yes, that is probably a reasonable number.
And it is absurd.
We are talking a period of a few weeks to train someone to use a tool for
**writing stuff down**.
That's nuts. And it is only because we have been living in a DTP bubble for
a the last few decades that we don't all immediately recognize that it is
nuts.
The suggestion to use a writing tool that take a "few weeks" to learn would
get you laughed out of court in any other field. In fact, it does regularly
get tech comm laughed out of court in support, training, development, and
the web world.
"We've just installed our brand new web CMS. With a few weeks of training,
you will all love it." Sorry, that's just not happening.
I'm talking about getting the training time down from a few weeks to a few
minutes, or to no time at all. That means getting all of the publishing and
content management overhead out of the writers face. Subject domain
structured writing can do that -- and does do that for the cases I have
mentioned before.
If the training time is a few weeks, that effectively means that no one but
full time tech writers can contribute to the doc set. And since that is
totally unacceptable to the rest of the organization, it means that they end
up creating parallel content sets using tools that they can learn in an
hour.
It may be great fun for some tech writers to own and control every part of
their product and to work in splendid isolation. But the days when it was
state of the art to publish a separate book every 18 months are long behind
us. Today we need integrated information sets to which everyone can
contribute and which are updated constantly.
To make that work we need tools that people can learn to use in minutes, or
hours at most, and we need rhetorical guidance to keep all of those varied
contributors on track.
As far as maintaining quality goes, and the importance of quality, I am all
for it, but I recognize that the number one quality that most organizations
care about (quite rightly) is immediacy. We can't maximize content quality
by monopolizing the right to create content, or hide behind tools that take
weeks to learn. Our contribution to quality has to take the form of
providing explicit rhetorical guidance to other contributors so that
information can be fully integrated and can flow in a timely manner while
still meeting essential quality goals.
Mark
------------------------------
Message: 29
Date: Tue, 2 May 2017 12:34:54 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4CYXgYRxpkhDSe67tM0YLOGsB4E5m9quTEntOeQKmaOpQ -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
DITA was never dominant outside of large organizations. Maybe 15% at
most of the job listings I've seen have called for it. It's not even
the last big thing any more. I've talked with several companies that
abandoned it in favor of various flavors of docs-as-code.
Paligo seems like a tools breakthrough to me since it gives small
teams and solo writers features that used to require an expensive CMS
server license and on-staff developers to support the associated
custom tools.
On Tue, May 2, 2017 at 11:42 AM, Bee Hanson <beelia -at- pacbell -dot- net> wrote:
> I consider myself a survivor of the tools wars, from LaTeX and Interleaf to FrameMaker and XMetaL. I think our profession came to a major crossroads in the late 90s when DITA started becoming dominant.
------------------------------
Message: 30
Date: Tue, 2 May 2017 19:43:39 +0000
From: "Wright, Lynne" <Lynne -dot- Wright -at- Kronos -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>, 'Robert Lauriston'
ÂÂÂ <robert -at- lauriston -dot- com>, 'TECHWR-L' <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <BAD146C4BAEA60428CA4F7C691AF0DFB2B1DB924 -at- MTL-MBX01 -dot- KRONOS -dot- com>
Content-Type: text/plain; charset="us-ascii"
But we're not talking about a few weeks of solid training.
You're primarily writing/creating content during the training period; you're just also learning to use the tool as you go along.
-----Original Message-----
From: techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+lynne -dot- wright=kronos -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of mbaker -at- analecta -dot- com
Sent: May-02-17 3:32 PM
To: 'Robert Lauriston' <robert -at- lauriston -dot- com>; 'TECHWR-L' <techwr-l -at- techwr-l -dot- com>
Subject: RE: Mark Baker's next book [was hijacked thread "Re: Structured stuff for the beginner"]
> Any good docs manager or technical lead can train a good writer to use
> any tool in a few weeks.
Yes, that is probably a reasonable number.
And it is absurd.
We are talking a period of a few weeks to train someone to use a tool for **writing stuff down**.
That's nuts. And it is only because we have been living in a DTP bubble for a the last few decades that we don't all immediately recognize that it is nuts.
The suggestion to use a writing tool that take a "few weeks" to learn would get you laughed out of court in any other field. In fact, it does regularly get tech comm laughed out of court in support, training, development, and the web world.
"We've just installed our brand new web CMS. With a few weeks of training, you will all love it." Sorry, that's just not happening.
I'm talking about getting the training time down from a few weeks to a few minutes, or to no time at all. That means getting all of the publishing and content management overhead out of the writers face. Subject domain structured writing can do that -- and does do that for the cases I have mentioned before.
If the training time is a few weeks, that effectively means that no one but full time tech writers can contribute to the doc set. And since that is totally unacceptable to the rest of the organization, it means that they end up creating parallel content sets using tools that they can learn in an hour.
It may be great fun for some tech writers to own and control every part of their product and to work in splendid isolation. But the days when it was state of the art to publish a separate book every 18 months are long behind us. Today we need integrated information sets to which everyone can contribute and which are updated constantly.
To make that work we need tools that people can learn to use in minutes, or hours at most, and we need rhetorical guidance to keep all of those varied contributors on track.
As far as maintaining quality goes, and the importance of quality, I am all for it, but I recognize that the number one quality that most organizations care about (quite rightly) is immediacy. We can't maximize content quality by monopolizing the right to create content, or hide behind tools that take weeks to learn. Our contribution to quality has to take the form of providing explicit rhetorical guidance to other contributors so that information can be fully integrated and can flow in a timely manner while still meeting essential quality goals.
Mark
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as Lynne -dot- Wright -at- kronos -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
------------------------------
Message: 31
Date: Tue, 2 May 2017 12:47:12 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CAN3Yy4C2Ry2y3H5a=-a8htyb43Kp1jEK1X09MEY0BjFhB5prOg -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
A new writer will spend most of their first few weeks getting up to
speed on the content, SMEs, and so on and beginning their first
assignments. They'll spend a small portion of their time getting up to
speed on any new tools.
I'm getting tired of your write-only approach to this discussion.
Nothing anyone says has any effect on your dystopian, fictional
version of the business.
On Tue, May 2, 2017 at 12:31 PM, <mbaker -at- analecta -dot- com> wrote:
>> Any good docs manager or technical lead can
>> train a good writer to use any tool in a few weeks.
>
> Yes, that is probably a reasonable number.
>
> And it is absurd.
>
> We are talking a period of a few weeks to train someone to use a tool for
> **writing stuff down**. ...
------------------------------
Message: 32
Date: Tue, 2 May 2017 12:51:38 -0700
From: Lauren <lauren -at- writeco -dot- net>
To: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
Cc: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Ethics in Technical Writing
Message-ID: <1ee7266d-d9df-4dfc-42d9-c4d9bdb47395 -at- writeco -dot- net>
Content-Type: text/plain; charset=utf-8; format=flowed
Elisa, you replied to my post.
On 5/1/2017 3:16 PM, Elisa R. Sawyer wrote:
> Please never, never question whether I value ethics.
I was responding to Robert in his comment against the discussion of
ethics as being about "the phrase in question" and not about my concerns
of fixing grammar when the instruction may be wrong.
> To suggest that I don't value ethics is the most insulting thing that
> you can ever do to me.
I didn't do that to you. I didn't even quote you or reference you when I
asked my general questions about ethics. You are discussing the subject
and not trying to push it aside. I value that.
------------------------------
Message: 33
Date: Tue, 2 May 2017 12:52:15 -0700
From: "Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>
To: Mark Baker <mbaker -at- analecta -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ Structured stuffÂÂÂ for the beginner"]
Message-ID:
ÂÂÂ <CACi8M=5pw_+7OCDeWiSnd30mus27Ti9Umj8oMBdHXY0tQmXPCg -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
Mark said:
"If the training time is a few weeks, that effectively means that no one but
full time tech writers can contribute to the doc set. And since that is
totally unacceptable to the rest of the organization, it means that they end
up creating parallel content sets using tools that they can learn in an
hour."
While I understand the point that you are trying to make, the reality is
that tools like Microsoft Word and Powerpoint take time to learn, and many
people turn to them. They learn these tools because it's expected of them.
I learned that Hollywood screenwriters actually share some issues with
technical writers. I've had some thoughts about why.
Anyone want to chime in with their thoughts?
-Elisa
On Tue, May 2, 2017 at 12:31 PM, <mbaker -at- analecta -dot- com> wrote:
> > Any good docs manager or technical lead can
> > train a good writer to use any tool in a few weeks.
>
> Yes, that is probably a reasonable number.
>
> And it is absurd.
>
> We are talking a period of a few weeks to train someone to use a tool for
> **writing stuff down**.
>
> That's nuts. And it is only because we have been living in a DTP bubble for
> a the last few decades that we don't all immediately recognize that it is
> nuts.
>
> The suggestion to use a writing tool that take a "few weeks" to learn would
> get you laughed out of court in any other field. In fact, it does regularly
> get tech comm laughed out of court in support, training, development, and
> the web world.
>
> "We've just installed our brand new web CMS. With a few weeks of training,
> you will all love it." Sorry, that's just not happening.
>
> I'm talking about getting the training time down from a few weeks to a few
> minutes, or to no time at all. That means getting all of the publishing and
> content management overhead out of the writers face. Subject domain
> structured writing can do that -- and does do that for the cases I have
> mentioned before.
>
> If the training time is a few weeks, that effectively means that no one but
> full time tech writers can contribute to the doc set. And since that is
> totally unacceptable to the rest of the organization, it means that they
> end
> up creating parallel content sets using tools that they can learn in an
> hour.
>
> It may be great fun for some tech writers to own and control every part of
> their product and to work in splendid isolation. But the days when it was
> state of the art to publish a separate book every 18 months are long behind
> us. Today we need integrated information sets to which everyone can
> contribute and which are updated constantly.
>
> To make that work we need tools that people can learn to use in minutes, or
> hours at most, and we need rhetorical guidance to keep all of those varied
> contributors on track.
>
> As far as maintaining quality goes, and the importance of quality, I am all
> for it, but I recognize that the number one quality that most organizations
> care about (quite rightly) is immediacy. We can't maximize content quality
> by monopolizing the right to create content, or hide behind tools that take
> weeks to learn. Our contribution to quality has to take the form of
> providing explicit rhetorical guidance to other contributors so that
> information can be fully integrated and can flow in a timely manner while
> still meeting essential quality goals.
>
> Mark
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
--
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
------------------------------
Message: 34
Date: Tue, 2 May 2017 12:59:35 -0700
From: Lauren <lauren -at- writeco -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Ethics in Technical Writing
Message-ID: <9795a0e0-99d2-f00d-a789-a9b3448d9c17 -at- writeco -dot- net>
Content-Type: text/plain; charset=utf-8; format=flowed
On 5/1/2017 3:38 PM, Robert Lauriston wrote:
> I'd verify whether the phrase was verbatim or some random jargon the
> original poster made up before questioning their professional
> competence or ethics.
I never suggested that anyone do that. I did ask if technical writers
have a duty of ethics in writing. Technical writers on this list were
focused on fixing grammar for an instruction that was unclear and few
(or none) raised the issue of what would happen if the grammar changed
the instruction. Clearly, the OP of the dubious phrase is out of the
loop at this point, as I am asking general questions about ethics in
technical writing, hence the subject line.
> Absent that information, discussing ethics as if it were relevant to
> the post seems rude to me.
I am not discussing the post. I keep wondering why you are latched on to
the original post as though it is a part of the discussion of ethics in
technical writing.
I don't know what your YouTube link was about, since it is a video.
Perhaps you can provide a written summary.
------------------------------
Message: 35
Date: Tue, 2 May 2017 20:08:18 +0000
From: "Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>, 'Lauren'
ÂÂÂ <lauren -at- writeco -dot- net>, "techwr-l -at- lists -dot- techwr-l -dot- com"
ÂÂÂ <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: RE: Structured stuff for the beginner
Message-ID:
ÂÂÂ <89d22173717d475cb065e6ffbf9f501d -at- USMARCORPEXCH07 -dot- hologic -dot- corp>
Content-Type: text/plain; charset="us-ascii"
So a form then is a subject-domain structure.
It might be worthwhile to present user documentation as a form of sorts.
Tripane and topnav online help does not seem cutting-edge. Most web sites, when viewed on a desktop or laptop, look designed for phone screens -- long, endless scrolling of a one-size-fits-all page.
You could have a menu system of dropdown menus to choose topics or information chunks. That may seem clunky. But maybe you could design a form, or a better presentation of online help, that serves the user better than the typical tripane stuff. I know topnav tries to accomplish that in some ways -- those are rollover menus.
It would be interesting to convert a user manual into the equivalent of a business form.
Steve
On Sunday, April 30, 2017 11:37 AM, mbaker -at- analecta -dot- com wrote:
Examples of subject domain structured writing are ubiquitous. If you have ever filled out a form, you have engaged in subject domain structured writing. You may think forms are not relevant because they are about data, not content. But consider how that same information got communicated before forms were invented. People wrote letters -- discursive documents -- to make their requests or report their information.
And not all forms are purely data fields. Many forms have essay sections as well. If you have ever filled out a college application or proposed as paper to a conference, you have done subject domain structured writing.
A lot of what technical and business writing does is to narrate data. We have had tools that turn data into narration for a long time. If you have received a benefits booklet from an insurer or read a corporate annual report, you have read a document that is composed partly of narrative generated from data. Companies like narrative science have been making strides in doing more complex and creative narration of data. Subject domain structured writing captures more of your content as data so that it is accessible to these algorithms.
Virtually all API documentation has been done using subject domain structured writing for many years. This includes both fielded data and constrained narrative passages. There are also custom web CMS systems that use the same principles and a number of proprietary inhouse systems as well.
Cinemania, as I have mentioned earlier, was done this way, and several other large data sets besides.
Subject domain structured writing works, and it has a history as long as document domain structured writing to show it works. That is not the issue.
The issue is, can it be extended into more of the areas of corporate and technical content that are currently being handled by document domain structured or media-domain structured systems. Technically it can, because it has been used successfully for that type of content. The real questions are more to do with implementation and culture change.
There are significant problem in this area because subject domain structured writing is inherently much more customized than document domain. There have been attempts to do industry wide subject domain content models but they have not had much success. They tend to become less subject-specific as they become more general, often turning back into essentially document domain models by the time everyone has their say. Realistically, you need to create subject domain models yourself, and while that is not particularly difficult, most companies don't have people with the mindset to do it, and vendors don't make a lot of tools that are truly helpful. Education and tooling are therefore key to making any progress on this.
A large part of the mindset issue has to do with the resistance of many writers to anything that is "cookie cutter". Here's the thing about cookie cutters, though. If you want consistent cookies, you should use a cookie cutter, no matter how experienced you are at making cookies. Your shapes will be more consistent and you will work quicker if you use one than if you don't. What distinguishes an experience cook from an inexperience one is not that the don't use cookie cutters, but that the design cookie cutters for their own use and that of their less experienced colleagues.
The question, of course, is, do you actually want all your cookies to be the same shape? Do you actually want all of your installation topics, or your programming topics, or your maintenance topics, to say the same things in the same way each time? In many case, you do. In many cases, there are very specific details that readers will always need to know, or that some readers will need to know sometimes, and you will serve you readers much better if you make sure that that information is included every single time.
I have gone through this exercise to know that even when a current set of topics seems quite diverse, when you look you find something that was said in one topic that, on reflection should be said in every topic, and something that was said in different ways in different topics that, on reflection, should be said the same way in every topic. Patterns emerge quickly once you start to look for them, and once the patterns start to emerge, people often start to realize that there are other things that should be in the patterns that are not in any of the current samples, and that there are things in some of the samples that don't belong in the pattern at all and should be elsewhere or nowhere.
This, of course, is why people stopped doing business communication with letters and started doing it with forms. People writing letters did not always know what the other person needed to know. They forgot to include critical information, or the expressed it in inconsistent ways. Often they included irrelevant information that simply slowed down the communication.
Using forms helps business correspondents ensure that they collect all the information they need in a consistent format that is easy to find, and that they communicate consistently and provide all needed information in a consistent way.
These are all the things that we say we want to accomplish in technical communication. Yet we resist using the very tools and techniques that would help us to accomplish them.
Of course, not every piece of communication can be reduced to a form. You can't create a form for a novel or a philosophical essay, or even a forum post. You always have to have the capacity to include freeform writing in your content set as well. But the fact that there are cases that don't fit the model is not an argument that the model does not work. It works for all kinds of things, and it improves communication wherever there are consistent patterns in the information needs to be met.
As to the difference between structured writing and structured authoring.
The terms are often used interchangeably, but sometimes structured writing is used to imply design and structured authoring to imply tools. But the real confusion here is that document domain structured writing/authoring systems like DITA, DocBook, and Information Mapping all use the terms structured writing and structured authoring to apply to themselves. This is perfectly fair -- they are all structured writing systems. But structured writing/authoring is a far broader concept than that.
This is why I use the idea of structured writing domains to distinguish between different approaches. DocBook and Information Mapping are document domain structured writing systems. DITA is at heart a document domain/management domain system with some ability to specialize into the subject domain. FrameMaker and Word are media domain structured writing systems. Structured Frame is a document domain structured writing systems.
What I am talking about is not structured writing vs. structured authoring therefore, but subject domain structured writing/authoring vs. media domain and document domain structured writing/authoring.
There are a number of problems that are solved by subject domain structured writing that are not solved by document domain structured writing. This includes, but is by no means limited to, the ability to design cookie cutters that make sure that you are following a consistent, reliable, proven rhetorical strategy for every piece of content you write. And yes, experienced writers will be much more consistent, and quicker, in creating that quality of content, just as business people and their customers are much more consistent and complete in communicating using forms than writing freeform letters.
But that misses the most important point. It takes experienced writers to design those cookie cutters. And being able to capture their experience, insight, and customer research in a cookie cutter give those experience writers a means to be more productive and produce higher quality content.
Equally important, it give them a means to test their designs and to consistently apply what they learn in testing to the future content they create.
If one of the principle reasons for adopting document domain structured writing it to be able to reuse content, one of the principle reasons for adopting subject domain structured writing is to reuse information designs.
There are a lot of other benefits as well. Enough to write a book about, in fact.
Mark
-----Original Message-----
From: On Behalf Of Lauren
Sent: Friday, April 28, 2017 4:06 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Structured stuff for the beginner
I want to see an example of this, as well. Mark's statement asserts a claim of proof, so there is either an example that supports the claim or there is no support for the claim and the claim is false.
How has structured writing "guided" a writer in a real world application of structured writing?
How has a reader's experience been "improved" in a real world application of structured writing?
Mark is describing "structured writing" as a cookie-cutter approach to producing documentation that seems like it would be helpful for new writers learning to write provided they are producing documentation that will have all needed information according to an established rhetorical pattern. If the "established rhetorical pattern" is incomplete, then the writer will still need to be able write without the crutch of structured writing.
In following this discussion, I see what looks like more than one discussion in that there seems to be a discussion of structured writing as a methodology for how to write and structured authoring as a technology for producing reusable documentation in multiple formats.
What problem does structured writing solve that is not solved by writing experience and structured authoring?
------------------------------
Message: 36
Date: Tue, 2 May 2017 13:15:34 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Ethics in Technical Writing
Message-ID:
ÂÂÂ <CAN3Yy4ANccBDo3Dm0VfWq3y-emaUFf1XmZzXouBtjeEFZvWnPQ -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
http://www.montypython.net/scripts/argument.php
On Tue, May 2, 2017 at 12:59 PM, Lauren <lauren -at- writeco -dot- net> wrote:
> ... I don't know what your YouTube link was about, since it is a video. Perhaps
> you can provide a written summary.
------------------------------
Message: 37
Date: Tue, 2 May 2017 13:18:11 -0700
From: Lauren <lauren -at- writeco -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Ethics in Technical Writing
Message-ID: <5e457456-9a2e-df94-91c0-fb71e3768bf5 -at- writeco -dot- net>
Content-Type: text/plain; charset=windows-1252; format=flowed
Nice segue. So back to my questions. Do technical writer have an ethical
duty to validate accuracy of instruction? Why are technical writing
ethics never discussed?
There are many cases of defective instructions that lead to litigation
in strict product liability claims. Sometimes, the documentation that
accompanies a product lacks adequate warnings and sometimes the
instructions are written in a way that leads to improper use. Grammar
?corrections? that lead to a missing comma have resulted in many
multi-million dollar claims. Changing a formula for calibration of
sensitive equipment to correct the grammar in an instruction can lead to
a misuse of a product that could result in damages.
It is unreasonable to assume that all technical writers have an equal
sense of ethical duty to make certain that an instruction is accurate.
So, in the general sense, do technical writers have an ethical duty to
make sure an instruction is accurate? Or is the matter of accuracy a
personal preference?
I think that this discussion is great for learning about how litigation
may arise from defective instructions. I thought my legal education
would lead me down a path to help people working in technical
communications but now I think it may be better fodder for product
liability litigation.
On 5/2/2017 8:50 AM, Gene Kim-Eng wrote:
> Ethical issues in technical writing arise when your employer or client
> wants you to put things in documents that you know are false, like
> safety certifications for products you know haven't had their safety
> evaluated, or to leave out critical items like hazard warnings.
>
> Worrying about about questions of correct grammar vs jargon in
> noncritical verbiage that doesn't impact actual usage may be a little
> bit pedantic, but being a little bit pedantic is one of the things
> technical writers are paid to do. Being VERY pedantic and conflating
> pedantic matters with "ethics" is one reason why many people regard
> technical writers as crybabies.
>
> Gene Kim-Eng
------------------------------
Message: 38
Date: Wed, 3 May 2017 07:18:58 +1000
From: Helen OBoyle <hoboyle -at- gmail -dot- com>
To: Simon North <simonxml -at- gmail -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Mark Baker's next book [was hijacked thread "Re:
ÂÂÂ StructuredÂÂÂ stufffor the beginner"]
Message-ID:
ÂÂÂ <CAJ2=HLYKYKsYzDeOZFHB7Hp8dGvLxRR8i0-sNAUAOWtC6ag0Rw -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
"Good enough" is actually a helpful goal for some technical writers, who
focus on elegance of prose, diligent adherence to arbitrary style guides,
and 100% completeness of object descriptions to the extent that the
throughput just isn't there. The documentation they produce looks great
and reads well, but product coverage is at about the 5% level. They're
happy with the quality, because they don't factor in the coverage
statistic. Management on the other hand, tasked with supplying "product
documentation" rather than "as much perfect documentation as we can", is
not.
I've worked in large and small shops, and have inevitably encountered
writers in each who want their content to be pristinely perfect. In the
old days where from year to year, after a product was initially released,
only incremental changes were made to the product they've documented,
spending time to reach that level of quality made sense. Once written, the
documentation would likely continue to apply for the the next 10-15 years
of the product (assuming the company lasted that long.)
These days in the "agile" world, that feature documented last month is
likely to work differently 4-6 months from now, and perhaps have a
completely different UI. Factor in that a product might have had 200 small
changes from year to year 20 years ago, but is now likely to have 15 major
feature additions along with 200 small changes. The technical writing team
hasn't increased in size, and may have been reduced. Development teams are
pressed to develop more and more new features so that marketing has
something to sell, or so that the company can deliver something sales sold
that the product didn't quite do at the time. Something has to give.
Sometimes this means that drafts are what goes out.
One practical challenge I've found with the 80/20 version of "good enough"
is around how to define the 80% that one should deliver. Is it ensuring
that the document has no, "New method to be documented in the future,"
entries? Is it including exhaustive descriptions of the side effects of
calling a method, for as many methods as possible, so that at least for the
documented methods, the writer knows that their documentation is the full
source of truth for information about those methods? Is it a tradeoff
between adding more content, and performing a copy-edit pass? As often as
not, it seems to be defined by one's manager saying, "(This) should be
documented for this method. Why isn't it?" -- because one person's "80%
there" differs from another person's "80% there".
"Good enough" is a fuzzy metric. Learning what constitutes the acceptable
80% level adds yet another complexity to the job. It's a combination of
subject matter expertise, audience knowledge and organisational knowledge
(what is your manager going to notice).
Almost half of our team spends 20% of their time on tools, to increase our
team's throughput by about 40% overall. Even on tools, there are 80/20
"discussions" over spending N extra hours to ensure the tool perfectly
handles 10 edge cases out of 9000 web pages of documentation.
On Wed, May 3, 2017 at 4:58 AM, Simon North <simonxml -at- gmail -dot- com> wrote:
> Sadly, I've been forced into that 'good enough' corner. The company where
> I've worked for the last 13 years was almost a startup (50 people) when I
> joined. It's now nearly 1200 and I'm still the only technical writer. I
> limit myself to R&D, where I can make the most difference, but where I once
> was able to keep up with 6 developers, with 65 split into 8 'agile' teams
> with a four-month release cycle I was forced to give up a long time ago. I
> gave them a wiki and now I manage, supervise, edit, train and coach, while
> the developers do most of the writing themselves. Most of the documentation
> is very technical, C++ class documentation, a programming language, GUI
> design tool and modeller so quality takes second place to quantity and
> accuracy.
>
> It's become more of a challenge of late since 'my' developers are nearly
> all non-native speakers (we are forced to recruit from as far afield as
> Russia, Greece, Romania, Mexico) but accuracy and completeness are key
> criteria for my audience so I have learned to let go of the details.
>
> And before anyone accuses me of being a 'techie' (yes, my comment about
> wordsmiths was a little tongue in cheek), apart from a degree in
> electronics, I do have a masters in technical writing and a bachelor degree
> in French and English Literature.
>
> Simon.
>
> > On May 2, 2017, at 20:27, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
> >
> > Balancing ideals of quality against the need to get stuff out the door
> and make money is just reality rearing its ugly head, and everybody gets
> the same thing, in every industry.
> >
> > You make gains by putting forth a convincing argument that your idea of
> "good enough" is the right balance, not by arguing for lofty "valuing
> quality" goals. Otherwise, you go into marketing, where you get points for
> talking like that even if nobody else in the company is taking it seriously.
> >
> > Gene Kim-Eng
> >
> >
> >> On 5/2/2017 11:04 AM, Monique Semp wrote:
> >>
> >>
> >> Unfortunately, I think that in 2017, at least in the software industry,
> it's a lost battle. Whether or not a shop is "officially agile", the plain
> truth is that writers are told to do work that's "good enough".
> >
> >
> > ---
> > This email has been checked for viruses by Avast antivirus software.
> > https://www.avast.com/antivirus
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as hoboyle -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>
------------------------------
Message: 39
Date: Tue, 2 May 2017 14:38:29 -0700
From: Gene Kim-Eng <techwr -at- genek -dot- com>
To: Lauren <lauren -at- writeco -dot- net>, techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Ethics in Technical Writing
Message-ID: <f7574e8c-b5f3-dffd-dca3-258ddf82f401 -at- genek -dot- com>
Content-Type: text/plain; charset=windows-1252; format=flowed
Yes, I'd say that as a writer you have an ethical duty to ensure that
you are not putting inaccurate information in your documents. By that, I
mean inaccurate PRODUCT information. Bad grammar and funny jargon may
reflect badly on you and/or your product, but that doesn't make it an
issue of ethics.
As for why we don't see real issues of ethics being discussed...
Best case scenario, there aren't a lot of people being asked to do
things that are critically wrong enough to be unethical.
Worst case scenario, a lot of people are obsessed with "wordsmithing"
noncritical grammar and phrasing because they lack the in-depth
technical knowledge of what they're writing about that would enable them
to catch all the critically wrong stuff that SMEs are slipping into
their documents.
Since the news is not a regular flood of reports on disasters caused by
someone following directions that turned out to be dangerously
inaccurate, I have to think the former is more likely or I'd never step
out my front door.
Gene Kim-Eng
On 5/2/2017 1:18 PM, Lauren wrote:
> Nice segue. So back to my questions. Do technical writer have an
> ethical duty to validate accuracy of instruction? Why are technical
> writing ethics never discussed?
---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus
------------------------------
Message: 40
Date: Tue, 2 May 2017 14:53:41 -0700
From: Robert Lauriston <robert -at- lauriston -dot- com>
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Ethics in Technical Writing
Message-ID:
ÂÂÂ <CAN3Yy4BQiW9Y8pS4cL_xFY6fzVUeAUMMo7vGazrFh67cXJ=bJQ -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset=UTF-8
It's my job to make my docs as accurate as I can. I don't see anything
to discuss there.
Is it unethical to take a job you can't or won't do properly? I don't
find that an interesting question.
------------------------------
Message: 41
Date: Wed, 3 May 2017 00:29:51 +0000
From: "Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>, 'Robert Lauriston'
ÂÂÂ <robert -at- lauriston -dot- com>, 'TECHWR-L' <techwr-l -at- techwr-l -dot- com>
Subject: RE: Structured stuff for the beginner
Message-ID:
ÂÂÂ <93955cb8425b4a01aab72e33e9033185 -at- USMARCORPEXCH07 -dot- hologic -dot- corp>
Content-Type: text/plain; charset="us-ascii"
Thanks, Mark.
Okay, let's take it a little further.
You seem to be saying that all tags are metadata. So in HTML, which is a document-domain structure, the "li" tag contains sufficient metadata for the document domain -- this is a list item -- but it is very subject-metadata poor for the subject domain, because it contains absolutely nothing about the subject.
In fact, all or almost all HTML tags would be subject-metadata poor. They tell you nothing about the subject, only about how the particular chunk of content looks in a document. HTML came out of the need to create online documents.
Whereas, a tag like the "recipe ingredient" tag in a subject-domain structure would be very metadata-rich, because it contains a lot of information about the subject.
So it sounds like we need to become much more adept at writing both subject-domain tags, and subject-domain structures, which would be aggregates of tags into a kind of mini-specification, customized for our subject.
And in fact, it sounds like the actual writers would not be doing this. Someone behind the scenes would be coming up with the subject-domain structures and the tags within them, and then writers would focus on developing the content and adding it to those tags and structures. So writers would need to become more adept at writing within subject-domain tags and structures.
That would be a boon, actually, because you're right, so much of our time is spent -- in some ways wasted -- on formatting issues, styling, and the like, because of the document domain we're forced to work in.
When I think about it, the work I do today is not much different from what I was doing back in the early 2000's, when I was hand-coding in HomeSite and styling in CSS -- this was in the pre-Dreamweaver days. And then you had Dreamweaver itself which kicked off a big WYSIWYG revolution in Web design (certainly that was not the only thing).
But FrameMaker is in many ways like working in Dreamweaver (and of course Word). Even Flare has started a new revolution of contemporary CSS styling -- that goes even beyond what we were doing back then. It makes it accessible to many more writers. But even though it's a fun thing, it's not necessarily a good thing, for the economies of the profession.
And entering content into subject-domain tags and structures is not a wooden endeavor. This would not be like the old days of data entry, or data processing, or word processing. There is some work involved in doing the research to extract the information necessary. But we wouldn't have to hassle with issues like formatting. Remember the promise of "no more formatting"? Everybody was all excited. If anything, it seems to me that a lot of writers are doing *more* formatting than earlier in their careers.
Oh yeah, linking and reuse -- couple other things that take away from actual content development.
So the secret sauce is in creating subject-domain structures and tags. And then somebody I guess has to write scripts or transformations to output that information into the various output formats, whether documents or otherwise (although I'm only guessing that there is even an "otherwise").
I think it's great. Tough finding time to read all this but it's worth it.
Thanks again,
Steve
PS - I also see that under this system you don't really need a WYSIWYG editor (although I understand that in fact it doesn't lend itself to this), and that you can do all the writing in a simple text editor like Notepad. Although, it would be nice if there were a way for a writer to select a particular tag for the subject structure, similar to specifying a tag in Oxygen. That way you spend minimal time entering tags, and the bulk of your time developing and entering content. No big CMS needed, no WYSIWYG system needed. So not much of an economic promise for vendors. (I think HomeSite had minimal tagging via auto-complete. That was a fun editor to work in. You could really rip.)
On Monday, May 01, 2017 1:31 PM, mbaker -at- analecta -dot- com wrote:
Steve:
> It seems as though you're saying that once you capture the information
into
> subject-based structures, you can transform those to a variety of
> document structures --
Exactly. So if I capture recipe ingredients as a record (name, quantity,
unit) then I can transform that to a table or a list for output. Or I can take all the ingredients for a set of recipes you select, combine the amounts for ingredients that occur in more than one recipe, and print out a shopping list, or send it to a shopping list app, or to an online grocery delivery service.
> and that DITA and DocBook are only two of these, whereas there are
> instead a multitude.
Right. We can export to DITA or DocBook if print is our target and we want to take advantage of their publishing chains. But there are many other things we can do with the data as well.
> And we are sort of confined to the traditional document structures.
Traditional document structures tie you to the document structure you choose. If you chose to use a list, it stays a list. If you chose to use a table, it stays a table, because we don't know enough about the information in those structures to do anything else with them.
All the structures we apply to content are metadata. Metadata retains possibilities. Document domain metadata preserves more possibilities than media domain metadata. Subject domain metadata preserves more possibilities than document domain metadata. Metadata the says "this is an ingredient consisting of a name, a quantity, and a unit of measure" retains more possibilities than metadata saying "this is a list item".
Preserving possibilities means that we can change who is responsible for decisions, which allows us to remove complexity from the author's world, such are removing responsibility for presentation, formatting, linking, reuse, etc. This can allow writers to focus more on research and rhetoric.
> So I'm thinking that in the chess example, chess is the subject
> matter,
and
> representation of a move in chess can be captured in a subject
> structure
--
> per the Javadoc example you gave earlier (from rank, to rank, etc.).Â
> So
now
> you have that information captured in a subject structure, and you can
sort
> of distribute that to a variety of document structures, not just DITA
> and DocBook but multiple different ones.
Exactly. Documents are a presentation vehicle for information. We can model the information and generate the presentation. Not in all cases, to be sure, but in many more than we do now.Â
> Whereas, as you said, the industry
> tends to gather around document structures (in building their tools)
> that present the most economic viability -- DITA probably being
> foremost, although HTML and PDF (HATs, FrameMaker, etc.) are even more
> prevalent and traditional.
Right. Document domain structures are common. A document is a document.
Simple document formats like MarkDown are simply incomplete, not different.
But the document domain metadata does not preserve many possibilities, so the writer has to execute most of the choices on the spot, requiring them to operate elaborate interfaces to complex back end systems.
This means you can sell the same system to many people (since they all produce documents) and you can charge them proportional to their use (since individual writers have to spend all day working in the interface).
> In the recipe example, I'm not sure if the subject is recipes or food,
> but structure of recipes is pretty consistent. So you capture
> ingredients
and/or
> measurements, and instructions, and that can be distributed as
> documents using multiple document structures.
The word recipe refers both a process (preparing a dish) and to a document that describes that process (a printed recipe). The subject domain version of the recipe is closer to capturing the process (though it is not precise enough to run a kitchen robot, say). A pure document domain version does not capture any metadata specific to the process. It just captures what is needed to format a document.Â
> You can see I'm struggling with this.
The hardest part for many people is that it involves moving a bunch of decisions, and therefore responsibility from the writer. It seems to be hard to trust that all those things are still going to be taken care of.
> You also said that it wouldn't be worth it to create a subject-based
structure
> unless you were going to distribute to multiple documents. Do I have
> that correct?
A major value of a subject domain structure is that it can capture the optimal rhetorical pattern for a particular topic. Suppose we decide that every recipe must specify prep time and servings. A subject domain model calls those items out explicitly, and can check for them, both reminding the writer of the requirement and enforcing it if they still forget. This is valuable regardless of whether we have one output format or a dozen.
But modeling and enforcing the optimal rhetorical pattern is only useful if it repeats, since if you only do it once, you will have finished your document by the time you have developed the model. So it is having only a single instance of the pattern that makes modeling pointless, not only having a single output format.
That said, people often believe that their documents have no repeating pattern when in fact there is one, or, at least, there is a repeating user need that implies an optimal repeatable rhetorical pattern that would be there if they looked for it.
> So as a writer, you would have to do a different kind of writing to
> create
a
> subject-based structure for your content. Sort of like the recipe,
> and
the
> chess move. Those are not exactly narrative. It's almost more like
coding.
> You would capture the text/information in subject-based fields. They
might
> be sentences or paragraphs but they might be fragments.
Right. A lot of things can be pulled out into fields and other data structures, but there will be sections that require discursive text as well.
That shows up in the recipe example (a discursive introduction) and in the API reference docs (a discursive description of usage). You can even have discursive descriptions of individual field or return values in an API reference. But we can place subject domain constraints on the discursive sections as well, and identify subjects mentioned in those sections -- again preserving options with our metadata.
> Traditionally we write content in a document structure, whereas we
> should be capturing the information in a subject structure, so that we
> can
distribute
> it through multiple document structures. So reuse within DITA is only
about
> DITA. We can't reuse the information in other, non-DITA document
> structures.
Sort of. You could reuse DITA content in DocBook or vice versa, to an extent, because they are both document structures with fundamentally similar semantics. You would have to translate the syntax to do the reuse, but that is certainly doable.
The real limitation is that the document domain metadata of these systems does not preserve the possibility of using this content in other ways, and, of course, that it does not enforce the ideal rhetorical pattern for content of a particular type. (DITA specialization could allow you to do some of this, though it comes with a lot of baggage.)
> It seems to be that what you're suggesting, if implemented, would be
> much more efficient. Because as it stands, we're having to repeat so
> much content generation.
It is a lot more efficient in a number of ways. But we have to bear in mind that is it also a much more custom solution, so there are costs on that side of the ledger as well. I hate it when DITA advocates, for example, don't point out the costs associated DITA reuse and represent it as pure profit.
So I don't want to overstate the case for this approach. Fundamentally, I believe in this approach because of the improvements in quality and consistency it brings. I'd much rather argue for it that way than as a source of cost reduction.
> If information captured in a subject structure applies to multiple
subjects,
> I'm not sure how you'd sort that out.
You need different subject structures for different subjects. This is why it is critical for this to succeed that we come up with ways to make developing subject models and their associated processing as easy and inexpensive as possible.
Mark
------------------------------
Message: 42
Date: Wed, 3 May 2017 02:56:00 +0200
From: Simon North <simonxml -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Structured stuff for the beginner
Message-ID: <6D55C93E-2707-4127-9D1B-6A3AB4F2F81A -at- gmail -dot- com>
Content-Type: text/plain;ÂÂÂ charset=us-ascii
It used to be called semantic markup. I can give a real world example. Integrated circuits have quite extensive data sheets containing pin, signal, and performance data. Sheets are published individually or in compendium form. The project I managed for this used FrameBuilder. To give the data the portability and accessibility to computer query, a range in a table, for example would be marked up as <table> <row> <cell> <celldata> <datatype> <range><high value> <low value> <unit> and so on. This kind of rich markup can be used for quite unanticipated tricks like converting from one unit to another automatically.
Taking it a step further, using architectural forms, you can abstract the semantics/structure and, for example, state that in this structure (DTD, schema) this markup will identify an element, but in this structure it must become a set of nested elements with this and this attribute.
Simon
> On May 3, 2017, at 02:29, Janoff, Steven <Steven -dot- Janoff -at- hologic -dot- com> wrote:
>
> Thanks, Mark.
>
> Okay, let's take it a little further.
>
> You seem to be saying that all tags are metadata. So in HTML, which is a document-domain structure, the "li" tag contains sufficient metadata for the document domain -- this is a list item -- but it is very subject-metadata poor for the subject domain, because it contains absolutely nothing about the subject.
>
> In fact, all or almost all HTML tags would be subject-metadata poor. They tell you nothing about the subject, only about how the particular chunk of content looks in a document. HTML came out of the need to create online documents.
>
> Whereas, a tag like the "recipe ingredient" tag in a subject-domain structure would be very metadata-rich, because it contains a lot of information about the subject.
>
> So it sounds like we need to become much more adept at writing both subject-domain tags, and subject-domain structures, which would be aggregates of tags into a kind of mini-specification, customized for our subject.
>
> And in fact, it sounds like the actual writers would not be doing this. Someone behind the scenes would be coming up with the subject-domain structures and the tags within them, and then writers would focus on developing the content and adding it to those tags and structures. So writers would need to become more adept at writing within subject-domain tags and structures.
>
> That would be a boon, actually, because you're right, so much of our time is spent -- in some ways wasted -- on formatting issues, styling, and the like, because of the document domain we're forced to work in.
>
> When I think about it, the work I do today is not much different from what I was doing back in the early 2000's, when I was hand-coding in HomeSite and styling in CSS -- this was in the pre-Dreamweaver days. And then you had Dreamweaver itself which kicked off a big WYSIWYG revolution in Web design (certainly that was not the only thing).
>
> But FrameMaker is in many ways like working in Dreamweaver (and of course Word). Even Flare has started a new revolution of contemporary CSS styling -- that goes even beyond what we were doing back then. It makes it accessible to many more writers. But even though it's a fun thing, it's not necessarily a good thing, for the economies of the profession.
>
> And entering content into subject-domain tags and structures is not a wooden endeavor. This would not be like the old days of data entry, or data processing, or word processing. There is some work involved in doing the research to extract the information necessary. But we wouldn't have to hassle with issues like formatting. Remember the promise of "no more formatting"? Everybody was all excited. If anything, it seems to me that a lot of writers are doing *more* formatting than earlier in their careers.
>
> Oh yeah, linking and reuse -- couple other things that take away from actual content development.
>
> So the secret sauce is in creating subject-domain structures and tags. And then somebody I guess has to write scripts or transformations to output that information into the various output formats, whether documents or otherwise (although I'm only guessing that there is even an "otherwise").
>
> I think it's great. Tough finding time to read all this but it's worth it.
>
> Thanks again,
>
> Steve
>
> PS - I also see that under this system you don't really need a WYSIWYG editor (although I understand that in fact it doesn't lend itself to this), and that you can do all the writing in a simple text editor like Notepad. Although, it would be nice if there were a way for a writer to select a particular tag for the subject structure, similar to specifying a tag in Oxygen. That way you spend minimal time entering tags, and the bulk of your time developing and entering content. No big CMS needed, no WYSIWYG system needed. So not much of an economic promise for vendors. (I think HomeSite had minimal tagging via auto-complete. That was a fun editor to work in. You could really rip.)
>
>
> On Monday, May 01, 2017 1:31 PM, mbaker -at- analecta -dot- com wrote:
>
> Steve:
>> It seems as though you're saying that once you capture the information
> into
>> subject-based structures, you can transform those to a variety of
>> document structures --
>
> Exactly. So if I capture recipe ingredients as a record (name, quantity,
> unit) then I can transform that to a table or a list for output. Or I can take all the ingredients for a set of recipes you select, combine the amounts for ingredients that occur in more than one recipe, and print out a shopping list, or send it to a shopping list app, or to an online grocery delivery service.
>
>> and that DITA and DocBook are only two of these, whereas there are
>> instead a multitude.
>
> Right. We can export to DITA or DocBook if print is our target and we want to take advantage of their publishing chains. But there are many other things we can do with the data as well.
>
>> And we are sort of confined to the traditional document structures.
>
> Traditional document structures tie you to the document structure you choose. If you chose to use a list, it stays a list. If you chose to use a table, it stays a table, because we don't know enough about the information in those structures to do anything else with them.
>
> All the structures we apply to content are metadata. Metadata retains possibilities. Document domain metadata preserves more possibilities than media domain metadata. Subject domain metadata preserves more possibilities than document domain metadata. Metadata the says "this is an ingredient consisting of a name, a quantity, and a unit of measure" retains more possibilities than metadata saying "this is a list item".
>
> Preserving possibilities means that we can change who is responsible for decisions, which allows us to remove complexity from the author's world, such are removing responsibility for presentation, formatting, linking, reuse, etc. This can allow writers to focus more on research and rhetoric.
>
>> So I'm thinking that in the chess example, chess is the subject
>> matter,
> and
>> representation of a move in chess can be captured in a subject
>> structure
> --
>> per the Javadoc example you gave earlier (from rank, to rank, etc.).Â
>> So
> now
>> you have that information captured in a subject structure, and you can
> sort
>> of distribute that to a variety of document structures, not just DITA
>> and DocBook but multiple different ones.
>
> Exactly. Documents are a presentation vehicle for information. We can model the information and generate the presentation. Not in all cases, to be sure, but in many more than we do now.Â
>
>> Whereas, as you said, the industry
>> tends to gather around document structures (in building their tools)
>> that present the most economic viability -- DITA probably being
>> foremost, although HTML and PDF (HATs, FrameMaker, etc.) are even more
>> prevalent and traditional.
>
> Right. Document domain structures are common. A document is a document.
> Simple document formats like MarkDown are simply incomplete, not different.
> But the document domain metadata does not preserve many possibilities, so the writer has to execute most of the choices on the spot, requiring them to operate elaborate interfaces to complex back end systems.
>
> This means you can sell the same system to many people (since they all produce documents) and you can charge them proportional to their use (since individual writers have to spend all day working in the interface).
>
>> In the recipe example, I'm not sure if the subject is recipes or food,
>> but structure of recipes is pretty consistent. So you capture
>> ingredients
> and/or
>> measurements, and instructions, and that can be distributed as
>> documents using multiple document structures.
>
> The word recipe refers both a process (preparing a dish) and to a document that describes that process (a printed recipe). The subject domain version of the recipe is closer to capturing the process (though it is not precise enough to run a kitchen robot, say). A pure document domain version does not capture any metadata specific to the process. It just captures what is needed to format a document.Â
>
>> You can see I'm struggling with this.
>
> The hardest part for many people is that it involves moving a bunch of decisions, and therefore responsibility from the writer. It seems to be hard to trust that all those things are still going to be taken care of.
>
>> You also said that it wouldn't be worth it to create a subject-based
> structure
>> unless you were going to distribute to multiple documents. Do I have
>> that correct?
>
> A major value of a subject domain structure is that it can capture the optimal rhetorical pattern for a particular topic. Suppose we decide that every recipe must specify prep time and servings. A subject domain model calls those items out explicitly, and can check for them, both reminding the writer of the requirement and enforcing it if they still forget. This is valuable regardless of whether we have one output format or a dozen.
>
> But modeling and enforcing the optimal rhetorical pattern is only useful if it repeats, since if you only do it once, you will have finished your document by the time you have developed the model. So it is having only a single instance of the pattern that makes modeling pointless, not only having a single output format.
>
> That said, people often believe that their documents have no repeating pattern when in fact there is one, or, at least, there is a repeating user need that implies an optimal repeatable rhetorical pattern that would be there if they looked for it.
>
>> So as a writer, you would have to do a different kind of writing to
>> create
> a
>> subject-based structure for your content. Sort of like the recipe,
>> and
> the
>> chess move. Those are not exactly narrative. It's almost more like
> coding.
>> You would capture the text/information in subject-based fields. They
> might
>> be sentences or paragraphs but they might be fragments.
>
> Right. A lot of things can be pulled out into fields and other data structures, but there will be sections that require discursive text as well.
> That shows up in the recipe example (a discursive introduction) and in the API reference docs (a discursive description of usage). You can even have discursive descriptions of individual field or return values in an API reference. But we can place subject domain constraints on the discursive sections as well, and identify subjects mentioned in those sections -- again preserving options with our metadata.
>
>> Traditionally we write content in a document structure, whereas we
>> should be capturing the information in a subject structure, so that we
>> can
> distribute
>> it through multiple document structures. So reuse within DITA is only
> about
>> DITA. We can't reuse the information in other, non-DITA document
>> structures.
>
> Sort of. You could reuse DITA content in DocBook or vice versa, to an extent, because they are both document structures with fundamentally similar semantics. You would have to translate the syntax to do the reuse, but that is certainly doable.
>
> The real limitation is that the document domain metadata of these systems does not preserve the possibility of using this content in other ways, and, of course, that it does not enforce the ideal rhetorical pattern for content of a particular type. (DITA specialization could allow you to do some of this, though it comes with a lot of baggage.)
>
>> It seems to be that what you're suggesting, if implemented, would be
>> much more efficient. Because as it stands, we're having to repeat so
>> much content generation.
>
> It is a lot more efficient in a number of ways. But we have to bear in mind that is it also a much more custom solution, so there are costs on that side of the ledger as well. I hate it when DITA advocates, for example, don't point out the costs associated DITA reuse and represent it as pure profit.
> So I don't want to overstate the case for this approach. Fundamentally, I believe in this approach because of the improvements in quality and consistency it brings. I'd much rather argue for it that way than as a source of cost reduction.
>
>> If information captured in a subject structure applies to multiple
> subjects,
>> I'm not sure how you'd sort that out.
>
> You need different subject structures for different subjects. This is why it is critical for this to succeed that we come up with ways to make developing subject models and their associated processing as easy and inexpensive as possible.
>
> Mark
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as Simonxml -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
>
> Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
------------------------------
Message: 43
Date: Wed, 3 May 2017 01:51:24 +0000
From: "Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>
To: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>, 'Robert Lauriston'
ÂÂÂ <robert -at- lauriston -dot- com>, 'TECHWR-L' <techwr-l -at- techwr-l -dot- com>
Subject: RE: Structured stuff for the beginner
Message-ID:
ÂÂÂ <3691778e00e94f17aa82a5c45877a70d -at- USMARCORPEXCH07 -dot- hologic -dot- corp>
Content-Type: text/plain; charset="us-ascii"
Mark, it also sounds like you're saying that we need to come up with more of the subject-specific markup languages than are out there now. Maybe you're saying (and you probably said this explicitly) that most of the markup languages out there now are document-domain oriented. HTML, SGML, DITA, DocBook, lightweight markup languages, and the like. I'm pretty new to this particular area so I'm not 100% sure that's what you're saying.
I get the sense, maybe wrongly, that XML is not really a document domain markup language, and I guess you've suggested as much or said as much. The goal of XML was to separate content from presentation.
Are things like MathML, MusicXML, and VoiceXML more what you have in mind? I know you mentioned RecipeML in one of the articles.
What markup languages would you recommend taking a look at to get a sense of what you're talking about regarding subject-specific markup languages?
Thanks,
Steve
On Monday, May 01, 2017 1:31 PM, mbaker -at- analecta -dot- com wrote:
Steve:
> It seems as though you're saying that once you capture the information
into
> subject-based structures, you can transform those to a variety of
> document structures --
Exactly. So if I capture recipe ingredients as a record (name, quantity,
unit) then I can transform that to a table or a list for output. Or I can take all the ingredients for a set of recipes you select, combine the amounts for ingredients that occur in more than one recipe, and print out a shopping list, or send it to a shopping list app, or to an online grocery delivery service.
> and that DITA and DocBook are only two of these, whereas there are
> instead a multitude.
Right. We can export to DITA or DocBook if print is our target and we want to take advantage of their publishing chains. But there are many other things we can do with the data as well.
> And we are sort of confined to the traditional document structures.
Traditional document structures tie you to the document structure you choose. If you chose to use a list, it stays a list. If you chose to use a table, it stays a table, because we don't know enough about the information in those structures to do anything else with them.
All the structures we apply to content are metadata. Metadata retains possibilities. Document domain metadata preserves more possibilities than media domain metadata. Subject domain metadata preserves more possibilities than document domain metadata. Metadata the says "this is an ingredient consisting of a name, a quantity, and a unit of measure" retains more possibilities than metadata saying "this is a list item".
Preserving possibilities means that we can change who is responsible for decisions, which allows us to remove complexity from the author's world, such are removing responsibility for presentation, formatting, linking, reuse, etc. This can allow writers to focus more on research and rhetoric.
<...>
------------------------------
_______________________________________________
You are currently subscribed to
TECHWR-L.
To unsubscribe send a blank email to
http://lists.techwr-l.com/mailman/listinfo/techwr-l
Send administrative questions to admin -at- techwr-l -dot- com -dot-
Visit
http://www.techwhirl.com/ for more resources and info.
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
End of TECHWR-L Digest, Vol 139, Issue 2
****************************************
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com
Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
Follow-Ups:
- Re: Mark Baker's next book [was hijacked thread "Re:, Peter Neilson
Previous by Author:
RE: Structured stuff for the beginner
Next by Author:
RE: Structured stuff for the beginner
Previous by Thread:
Re: Ethics in Technical Writing
Next by Thread:
Re: Mark Baker's next book [was hijacked thread "Re:
[Top of Archive] | [Author Index (this month)] | [Thread Index (this month)]
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads
Copyright INKtopia Limited. All Rights Reserved