Session 1 Summary – 26 January 2013

Notes from all sessions were shared at the end of the day in the final Summary Session. Notes from those scribes who sent them in have been posted here.

New Features in Frame Maker

  • Side Curtain Expandable
  • Table catalog
  • Object catalog
  • Marker pod – good for xrefs
  • Drag fiels into workspace to open
  • Tab catalog can be outside FM window
  • Can save and share workspace config
  • Reset workspace to revert side curtain config
  • Re-save workspace must retype name
    • Use a file to track workspace names
  • Paragraph catalog
    • options – use dialog to delete/show tags
    • clean imports plugin
    • customize catalog tag view
    • CTL+9 / FN9 – all old shortcuts work
    • sort view – used/unused
  • Line numbers (great for review/work in multiple columns
  • Searches – new “finds”
    • find character and paragraph overrides – can change/remove
  • New: xml templates
  • Show/hide text w/in tags
  • Table catalog tab
  • Structure
    • open OTK files
    • XML code view
    • xpath 2.0
    • xslt
    • pretty print
    • dita otk plug in
    • self-validate code (tool tip)

Document Review process: Our authoring tools have evolved, but a lot of us are still doing technical reviews the way we used to 10 years ago. How can we improve the tools process?

This session had the highest number of votes.

Facilitator: Wendy Shaffer (VMware)
Scribe: Amy Bowman (VMware)

  • What we’re doing now (the attendees of the session)
    • sending out PDFs via email
    • shared PDF reviews via Adobe Reader
    • putting content on a wiki
    • sending out a Word doc
    • distributing a paper doc
    • full doc reviews and also chunk doc reviews (per feature, per topic, per section)
    • comments are returned via email, via wiki (though reviewers are hesitant to edit our wikis), print, and via bugs
  • * Problems
    • Reviewers can’t see the comments of other reviewers (except in the case of shared PDF)
    • Shared PDF is unreliable – sometimes comments get lost, so we’re afraid to use it
    • Status of review is unknown (who has reviewed it, have the comments been addressed, what sections still require review)
    • Quality of reviews (how to get reviewers to do more than just mark up missing commas and formatting)
    • Reviewers aren’t comfortable using our tools (Frame, DITA, etc.), so they can’t make comments in the source (or we can’t afford to buy all reviewers a license to use our tool)
    • Agile process – time for review is very limited, sometimes squeezed in at the very end of a sprint
  • * Ideas
    • “The problem isn’t the tool. It is the human management of the process.”
    • Prototype a process first and then consider what tools to use. The process is more important than the tools. Process varies depending on what your needs are. Do your reviewers want/need to see every comment or are some comments protected for access-control reasons? etc.
    • Small groups can use a linear approach – send the PDF out via email, a reviewer marks it up with comments, replies to all with the marked-up PDF attached. The next reviewer adds his/her comments to that PDF, etc.
    • Use bugs/defects to track reviews. Reviewers put comments in the bug or email them to you and then you add the comments to the bug. This allows all reviewers to see the comments that have been made and also provides a paper trail of who has reviewed it and what the comments were.
    • Some tools (like SDL’s latest) allow you to push your topics from a CMS to a wiki-like page where people can add comments, and then the comments are associated with the topic (but not added directly to the topic – no round-tripping)
    • Add a cover sheet to your PDF specifying what type of feedback you want (e.g., no grammar-related comments, please) and/or where feedback is required. For example, a table that lists the reviewer in one column and the section(s) he/she is responsible for reviewing.
    • Specify areas of concern with draft comments/reviewer’s comments that stand out in your PDF. You can also respond to comments by inserting a reply via a draft comment/reviewer comment, then regenerating and reposting/sending the PDF.

Reusing content with techpubs, training, marketing, support and other organizations

Scribe: Michael Belef

These notes have comments by many people in the session but does not attempt to identify each speaker.

Re-using Content:

What ideas are there to expand the efficiencies of tech pubs content re-use into other departments?

  • Training
  • Support
  • Marketing
  • Education
  • and other departments.

Recently, one writer had to review marketing collateral. Six different solution briefs. About 50% of the info in each of the six pieces was the same info. They could be re-using technical publications content. All departments would benefit.

Some folks think re-use is too hard to implement across departments.

It is not that it (re-using content) does not work, it is that folks don’t plan enough or they plan too much. Or bite off too much at once, when they need to deal with smaller chunks at first.

Maturity Scale:

  • We will re-use X
  • Track it
  • Have a strategy
  • Be compliant with rules.

Authoring interfaces.

Some writers happy working in oXygen Author, for example. So, maybe we need more friendly authoring interfaces… but how do we get them through that learning curve?

Marketing Team

Not every department will have the same needs for reuse.

Example 1: Marketing can use fragments of content

Example 2: Flash interface based course. Notes on the course were different than the content?

Marketing is not aware that there is something out there better than cut and paste. If made aware, they think that is great but we don’t have time to learn it. And maybe willing to try but just under-informed about content re-use and unwilling to adopt this unknown. And they have invested so much training in their current tools, are overwhelmed.

In-Design has an in-copy feature… …simplified editing interface… it could be a solution for those who are trying re-use. Not necessarily a recommended path, but it might work for some. XML for In-Design is not setup for XML re-use. Very flat. Mostly made for creating catalogs.

You need to have an executive champion. Some one who can tell the other departments they must re-use content.

You have to have a business driver to push the re-use initiative.

You can’t get a return on investment unless you document your business requirements.

Thinking about the marketing departments that I have worked with….

  • How do we structure the body content?
  • It might need to be part free-form for the art side and part structured content.
  • How do we innovate and change our headline styles while having the same content?

Sounds like the real issue is marketing tools are all still based on 80s model. (If anyone knows different let us know.) The hard part is the process, the rules the governance. How do we ensure the two translation departments, two writing departments, or others, adhere to the plans and strategies?

You are saying marketing is gonna be hard to train. So that is what you have to do: train them.

Marketing is about the message, not tools. About the look. There is a reluctance to adopt tools.

They are paid to be creative.

It really depends on the marketing group.


Don’t touch the tools until you have the strategy.

Each department has already invested in tools, has their processes.

Your current output is already a perfect example. If you can document that, you can use it to build your business case…

For our company it is not the Return on Investment (ROI) decision – we all know it is more efficient, better time to market, cheaper. We can make that case… Okay we are sold… The hard part is to get the funding. Who will adapt? How do we ensure everyone is on board?

At another company, everyone was on board and two years later the re-use strategy still was not implemented. Yes that goes back to the execs… they did not enforce the goal. Correct – we did not even have a VP. The CEO was probably not that interested in being a champion for the change.

In many places the style guide is not even meeting multiple department needs. Like the company is already “siloed”.

Our company uses Microsoft style guide not so much because it is perfect but it’s an established standard we can work from.

One company that I worked with, did everything in DocBook. The transition from DocBook to DITA did not go so well. Later, the whole transition failed. Some groups start a transition but fail because they think it makes senses to keep doing it the old way.

Q: Were the groups in Ben’s example sharing content?

A: Different customer base, different customer needs, so why is it hard? Well we are small now but we are growing in training tech pubs marketing, service, etc. But the training department’s learning objectives are not needed in the tech docs.

Using DITA OpenToolkit.. We do not have embedded help. We will have eLearning. DITA will support eLearning, HTML PDF. Those requirements won’t be hard to meet.

Support People

If you bring support people in, they are very much okay with learning to structure for re-use.

Sales Team

I am the one technical person in the sales group. But we still don’t have the bandwidth to implement all the stuff. I am the only person who knows how to use the templates but that is not my job and it’s not the important work I need to do. (I have other technical work to do.)

Company culture

Some are just gonna say “get it done now, don’t worry about re-use.”

General notes:

Sounds like the take-away is that there has been little to no success for us to get this done at our companies.

Well… I think that you will see more companies succeeding in this.

You will see some that move to DITA.

I don’t hear a lot of people on conference circuit saying that they succeeded in getting multiple departments to share re-use.

Does it matter if everyone is 100% on board?

Who will manage the content database?

Web site what content is being injected to the web sites?

Marketing, Training, Education etc: Gotta get them all on board and trained.

When it costs the company more money … You have to have the numbers to make the business case. Support, service, marketing, is your solution cheaper than doing it the current way?

The upper levels of management don’t feel the pain. Do you have to translate the pain so that the execs feel it and are moved to adopt the content sharing strategy?

Another perspective…. Marketing often creates collateral that has a three day trade show… Then they move on. So the pain of adopting is too great for this short-lived material.

Well, some of tech pubs material has short life time too. We are just in the culture of re-use in tech pubs community.

Some marketing stuff does have a longer life span. And some technical material has a short life span.

It would still benefit marketing and other groups to have a database of reliable re-usable content to inject into their docs and still spend time

If you do this – don’t you need to ensure you have a content management system?

We got through this (economic) depression by just hunkering down. All the companies still have the same problems. Now companies are starting to release more funding. So maybe budgets will open up to allow the changes.

Well so it sounds like nobody one has a success story of cross departmental. But we can hope ….


  • Make the business case,
  • Try to show the return on investment,
  • If expanding to other departments and you don’t have content management system you will need to plan for content management.
  • And if you do have a content management system you need to be sure that it is adequate for these planned changes.

LinkedIn, Recruiters, portfolios, getting noticed, etc

This session had the third highest vote count.

currently unavailable

Documenting APIs

This session had the second highest vote count.

currently unavailable