[Framers] structured content - not always called for

Wed May 18 06:07:03 PDT 2016

Good points Monique. I'm in a similar situation, being a lone writer, and not having the time or resources to implement a structured workflow.

I deal with two main streams of documentation. For my operations guides and online help I use FrameMaker and WebWorks ePublisher. There's little reuse involved and I can use text insets to manage that. For our last major platform upgrade, I did a content analysis using DITA's concept/task/reference model to restructure the documentation and got good comments on the approach.

The other stream involves many technical specifications which go out to our clients. For these, I have to use Word. I've found that Thirty Six Software's SmartDocs tool gives me most of the benefits I'd get from moving to DITA and is much easier to set up and use. Yes, if I had a group of four or five writers, I'd probably move to DITA, but that's not going to happen.

Regards
Keith

--
Keith Soltys
Senior Technical Writer
Architecture
TMX Group
(416) 947-4397
http://www.tmx.com/

-----Original Message-----
From: Framers [mailto:framers-bounces+keith.soltys=tmx.com at lists.frameusers.com] On Behalf Of Monique Semp
Sent: Tuesday, May 17, 2016 6:20 PM
To: framers at lists.frameusers.com
Subject: [Framers] structured content - not always called for

> But then, working with unstructured FM content in the 21st century is really not done, if you ask me. Converting is fairly easy - we do it all the time - so if you do not have structured content yet, look in that direction for your best practices.

Oh, I disagree strongly with this. Working with unstructured content is done often, although I'll grant you with varying degrees of success :-).

I've worked with DITA—including at VMware, where I got to work directly with some of the thought leaders in structured content—and definitely see the great advantages **but only if appropriate **.

In my current assignment, I'm the sole writer (and part-time at that), for an organization that doesn't have very many products, that has no need for localization, and that has independent streams for Marketing and Tech Pubs deliverables (and no need to combine them or share actual content files). I've worked on-and-off at this company for 10+ years, and it's only now that I'm even looking into any sort of "reuse strategy". And truthfully, if I hadn't recently spent several years in a heavily structured-content environment, I doubt I'd have even thought of it. It's not too much content that I can't just copy/paste, make a few notes in the wiki about "if you change this in doc A, be sure to make the parallel change in doc B", and be done with it. But being a trainable monkey (as "they" say), I figured the docs (and I) would benefit from a bit of forethought.

I've seen conversions done, and yes, they're fairly easy. But there's no need to invest the time to migrate content, possibly purchase additional tools (at my own expense because I'm a consultant, not a direct employee), or develop new templates for publishing from structured FrameMaker. As well, doing so would make it even harder for my client to bring in another tech writer who's appropriately skilled in the tools with which I've created their docs, and experienced enough to figure things out (given the lack of detail in the Tech Pubs Processes and Procedures, which are lacking detail because there's no need for the client to pay for more detailed versions).

**** I'm not anti-DITA, anti-structure, or anything like that. In fact, I took a recent 18-month contract in large part because I'd get to keep working in the structured content world. In addition to the oft-cited benefits (reuse, localization, topic-based writing, semantic-styling), I found that I could write much more accurate content, much more quickly than otherwise. And when reviewers focused on minutia such as an occasional bad break in a PDF, I could just say, "sorry, nothing I can do about it" :-). ****

But structured authoring/DITA, is simply overkill for many situations, and is typically best with *at least* one "pubs tools guy/gal" in addition to the dedicated writers. I feel strongly about this, and in fact am developing a presentation along the lines of "Adopting the Best Practices of Structured Authoring—In Any Toolset". I'll be presenting nuts-and-bolts examples of how to do a bunch of "structured/DITA things" in Word, FrameMaker, Doxygen/Javadoc, and MadCap Flare. Word-for-word, this is how I pitched the presentation topic, which was very well received by the STC-Berkeley programs team:
  --
  All too often the “experts” seem to imply that you must use some giant system with lots of overhead (I’m thinking DITA at VMware or Salesforce, of the big Ponydocs ecosystem at Splunk) in order to get any of the benefits of structured/DITA writing. But that’s just not true. There are lots of things that are about writing technique and simple style management in whatever tool you’re using. But nobody presents it that way. They just shake their heads at the practicalities of needing to use cheap/free tools at a shop that’s not interested in investing in tools for writers. And I’d like to show that this needn’t prevent writers from gaining the benefits of structure and style that DITA enforces.
  --
Just some long rambling thoughts for consideration, -Monique _______________________________________________

This message is from the Framers mailing list

Send messages to framers at lists.frameusers.com Visit the list's homepage at  http://www.frameusers.com Archives located at http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listadmin at frameusers.com

NOTICE OF CONFIDENTIALITY This e-mail, including all materials contained in or attached to this e-mail, contains proprietary and confidential information solely for the internal use of the intended recipient. If you have received this email in error, please notify us immediately by return e-mail or otherwise and ensure that it is permanently deleted from your systems, and do not print, copy, distribute or read its contents.

AVIS DE CONFIDENTIALITÉ Le présent courriel, y compris tous les documents qu'il contient ou qui y sont joints, renferme des renseignements exclusifs et confidentiels destinés uniquement à l'usage interne du destinataire prévu. Si vous avez reçu le présent courriel par erreur, veuillez nous aviser immédiatement, notamment par retour de courriel, et vous assurer qu'il est supprimé de façon permanente de vos systèmes; veuillez également vous abstenir d'imprimer, de copier, de distribuer ou de lire son contenu.