Structured authoring AND the web
We read Tom Johnson’s post on Structured authoring versus the web with some dismay. Tom is a persuasive, influential writer, but his article misses the mark in important ways.
Sarah O’Keefe and Alan Pringle contributed to this post.
Let’s start from the conclusion:
I don’t want to come across as being against structured authoring. As I mentioned in the introduction, clearly structured authoring is a trend many companies are following. However, structured authoring has a few challenges before it can live in a web environment. In this post, I mentioned a few trends that I think pose challenges to structured authoring:
- SaaS decreases the requirement to support versioned content.
- Agile makes print publications potentially out of date every two weeks.
- Collaboration requires a form that SMEs can edit, update, and potentially author themselves.
- Mobile works best on a website with responsive design.
- Budget cutbacks force small teams to figure out their own publishing solutions.
- Open source platforms provide a lot of capabilities that we can easily leverage.
- Browser-based editing simplifies the update process, which helps us keep up with rapidly changing information.
Here are some counterpoints:
SaaS. What percentage of companies are producing just SaaS products? The dubious assertion that SaaS eliminates the requirement to version documents dismisses medical devices, pharmaceuticals, and all hardware products from consideration. Many companies that offer SaaS options also have packaged software.
Agile. Agile is definitely a challenge for print publications. But what does print have to do with structured authoring? The true question is, “Should we create print or not?” The underlying methodology is irrelevant—unless you are conceding that web-based authoring doesn’t really support print. And again, what of industries that require print or PDF?
Collaboration and SME editing. It’s possible to give subject matter experts direct editing access to either XML or HTML. Don’t want SMEs to have final say in the modifications they make to content? Set up their access to enable changes that require approval; there are hosted systems for managing structured content that provide tiered account access.
Responsive design. This one had us truly puzzled. Generating content that uses responsive design is a configuration issue, so it’s easily done in whatever technology you have that produces HTML and CSS. But then Tom asserts that using responsive design from XML means that you are ignoring multichannel publishing. This is true only if your multiple channels are “desktop” and “mobile.” But most companies are also producing PDF/print, and we are seeing increasing requirements for EPUB (yes, EPUB!!!), XML for consumption by other systems, and more.
Budget cutbacks. From the body of the post:
With many tech writing teams constrained with small budgets and few resources, hiring a dedicated publishing engineer to handle the transforms, or contracting out the work at a high cost, really isn’t a practical solution.
Look at all those scary adjectives! In response, we’ll ask our standard consultant questions: Is there a business case? Nobody hires “publishing engineers” (which, by the way, is a great description of the job) or contracts work out at “high cost” (another happy phrase when we’re on the receiving end!) unless there is value in doing so. What is the value?
Open source platforms. You’ll get no argument from us that open source platforms “provide a lot of capabilities”: WordPress has its place, as does the DITA Open Toolkit and all the open source technologies it includes. What’s important to remember about open source tools is that they usually require tailoring and the addition of new features to fully meet a company’s particular needs. Yep, it’s time to haul out the “free but not cheap” chestnut: the default implementation of any open source technology is rarely enough to meet your requirements, so be prepared to spend time and money to implement all the features you need. Some companies may calculate it’s cheaper to buy a tool that fulfills their requirements out of the box instead of trying to build a comparable open source solution.
Browser-based editing. Tom says that “you shouldn’t have to author outside the browser to publish on the web.” Well, you don’t have to. Multiple hosted systems for managing structured content include browser-based authoring and editing. That said, there are good reasons why a company may not want browser-based editing or any hosted tools: bandwidth limitations, security, and so on.
What’s missing from Tom’s discussion is a recognition that business requirements should drive the decision on structured authoring, the formats in which a company provides content, the selection of open source or proprietary tools, and so on. Instead, his post creates a narrow rhetorical funnel (if you make SaaS software and eliminate PDF and have no resources) and then asserts that a particular solution is best. Given the constraints Tom describes, you can make a case for web-only authoring. But what percentage of tech comm actually falls into this very narrow description?
Finally, we didn’t see any recognition of key tech comm requirements—localization and conditional content—that often drive tool decisions.
Structured authoring and the web aren’t mutually exclusive. You can combine both into a useful, dynamic approach to content.
About the author
craig wright
I read Tom’s article and have to agree with you. Structured authoring for the web is possible, it is just that the tech comm tools we have now haven’t really developed enough as far as the web is concerned…but I am sure they will. Flare is close to being a structured CMS in my view (but maybe that’s because I don’t know enough!).
Tom Johnson
Sarah, thanks for the response to my post. It’s great to read your careful feedback and rebuttal to some of my points. You certainly have a lot of experience with structured XML, working with a variety of clients in different industries. I’m sure that perspective helps in seeing the bigger picture and the various requirements (such as for print and EPUB) that clients have.
I mainly wanted to open up a discussion with my post about structured authoring and the web. I’m curious to read your thoughts on integrating the two. Do you ever have clients who say, I want my help to be on a modern-looking website (ie., not tripane help), but some web CMS platform? If so, what kinds of solutions do you recommend for this workflow?
Do you see any challenges with structured authoring and web publishing? Are most clients not really interested in housing their help in a web-like system?
To clarify a couple of points about print and mobile (sorry that I didn’t articulate these well — I was writing late at night), basically, if you remove the requirement for a separate print and mobile output from your tech pub needs, then you have less of a need to use a structured authoring setup, because you have just one publishing destination: the web.
If you have just one publishing destination, then it doesn’t make much sense to author content in structured XML just so you can render it to an HTML output. Why not just write it in HTML from the start?
While removing mobile and print requirements may seem like a strong measure, I tried to argue that mobile views are included in the web output. And print requirements don’t fit the agile environments of rapidly changing technology, so perhaps they can be dropped.
But certainly, if you must produce a PDF and a web view and an EPUB version and send it all out for translation, then yeah, you would definitely want a structured authoring solution there. But if not, then there isn’t a strong case for it.
Thanks again for your post!
Sarah O'Keefe
Hi Tom,
The answer to every one of your questions is “It depends.” 🙂 But I’ll take a shot at more specifics…
>Do you ever have clients who say, I want my help to be on a modern-looking website (ie., not tripane help), but some web CMS platform? If so, what kinds of solutions do you recommend for this workflow?
Either build output from XML that meets their requirements, or build a connector from the XML to the platform that generates the look-and-feel you want. So, maybe you author in XML and publish to Drupal. Or WordPress. Or whatever.
>Do you see any challenges with structured authoring and web publishing? Are most clients not really interested in housing their help in a web-like system?
The vast majority of our clients DO post their content on the web. I just don’t see the conflict. Of course there are huge challenges with structured authoring. And web publishing. And especially combining the two!
>To clarify a couple of points about print and mobile (sorry that I didn’t articulate these well — I was writing late at night), basically, if you remove the requirement for a separate print and mobile output from your tech pub needs, then you have less of a need to use a structured authoring setup, because you have just one publishing destination: the web.
Clarification: You have one publishing destination TODAY. What happens when (not if) another output requirement is introduced? Also, our data indicates that the percentage of people who are doing no PDF output at all is very low.
We have cases where people need to push content over to a learning management system for reuse. You’re not going to get that out of the box from anywhere…
>If you have just one publishing destination, then it doesn’t make much sense to author content in structured XML just so you can render it to an HTML output. Why not just write it in HTML from the start?
What if you (or worse, your management) change your mind and need to add PDF back in? What if you need a new type of output?
What if your web platform can’t handle the reuse, the semantics, or the other “stuff” that you need?
A simple example: A procedure refers to a specific part, and you want to link to that part’s listing in your database.
> But certainly, if you must produce a PDF and a web view and an EPUB version and send it all out for translation, then yeah, you would definitely want a structured authoring solution there.
Agreed.
> But if not, then there isn’t a strong case for it.
Don’t agree. There are other issues that may lead you toward structured authoring anyway.
There are obviously cases where a web-only approach is appropriate. I just think that it’s really not as simple as looking at Scary XML(tm) and deciding it’s too challenging. The much more interesting question, which people should be asking, is, “What does the business need from its technical content, and what is the best way to fulfill that need?”
In other words, content strategy.
Tom Johnson
Sarah, thanks for responding to my comment. I would love to see some examples of web-like help systems that are generated from XML-authored help. If you have any you can share, that would be great. (There is a difference, of course, between putting help on the web and publishing web-like help.)
Re planning for tomorrow, good point. Maybe I’m thinking too much in the present. Mainly, I want to take advantage of all the web has to offer. Maybe in some situations having content consumable as XML would provide more advantages.
Tony Self
Hi Tom. You triggered a very interesting discussion, thanks! Since 2007, my Web site has used a combination of DITA, DocBook, RSS and XHTML topics inside an ASP.Net framework. XML files are dynamically transformed to HTML on the server. So while this is not Help, as such, it is a Web publication generated from XML-authored content. The Articles area is where most new content goes, and I have listed (for curiosity value) what format the source is stored in. The now dated article(authored in DITA and dynamically transformed) explains the motivation and process. I have certainly found that this particular structured authoring has made it much easier to author and publish content, and has resulted in far more consistent presentation. In other words, the ROI has been enormous. http://www.hyperwrite.com/Articles/showarticle.aspx?id=68
Mark Baker
Tom, re:
“If you have just one publishing destination, then it doesn’t make much sense to author content in structured XML just so you can render it to an HTML output. Why not just write it in HTML from the start?”
This, I am afraid, is evidence that structured authoring has been grievously undersold. Perhaps this was inevitable, as selling its full capabilities to a skittish tech comm community has proved difficult in the past. People are often more comfortable with less capable systems that take them less far from their comfort zone. So structured content has often been sold as simply about single sourcing to multiple media, and, more recently, simply about reuse.
These are useful capabilities, but they are only the beginning of what structured content has to offer. Why work in XML if your only output media is HTML? For a start, because it can allow you to automate rich linking, which would otherwise be very costly if every link had to be created and managed by hand.
Beyond that, there is a huge amount that can be done in terms of content automation, extracting and merging of content from multiple sources, improving the consistency and quality of content, getting reliable content from employees who are not full time writers, automatically organizing content (full plug and play content management), automated updates and maintenance, automated validation and auditing, the creation of interactive multi-value selection mechanisms, content migration and exchange, powering mashups, and on and on.
Tom Johnson
Mark, thanks for noting the misinformation about structured authoring. I admit I was led to believe that content re-use and single sourcing were the main purposes. You raised a lot of other compelling reasons that I need to better understand. Thanks for sharing. Looks interesting and I’ll be on the lookout for use cases that would leverage some of these ideas.
cud
I’m 100% with Mark on this. I went to DITA as my source format, and currently only deliver a tri-pane help and a PDF — we can call that one publishing destination. So you might argue that I have nothing to gain. In fact, my turnaround time is reduced to nearly zero, my source is on the same repository as the product’s source code, and builds automatically pick up my latest version — or are branched to keep different versions of the product. That’s just the initial phase of the project, and I expect to see more advantages as we move forward. But for a first release, the results are great, and exceeded my expectations for convenience, time savings, etc.
What I have is a client-side transform from raw DITA to HTML — all done in the client. So that opens up a vast array of possibilities. One single HTML file contains the whole thing — to change the look I change this HTML file, plus CSS and some custom scripting. For example, I’m integrating JQuery.mobile to get a completely different delivery. I can use DITAMAP to filter content — on the fly. In fact, I can modify my XSL files on the fly (so I get modifications on the fly on the fly???) With entity refs I get variables in the text. I can incorporate any other data I want — for example, I can call the product’s API and incorporate the results in my documentation.
So in the short term, I see immediate benefits from using structure for my help system. I get long term benefits that I believe will future-proof my project. And in effect, this is a web/structure integration, because the product is a web app — not exactly SAS, but more or less the same idea.
I agree the tools aren’t there now. But I hope to turn this into an open-source project that will bring the tools out, and will lower the bar for structure.