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



Session 2 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.

Challenges of using standards to support content development, consumption, and interchange. Includes tools, vendors, services, committees, when and how to choose, government regulations, etc.

  • S1000D
  • economize, rationalize, increase quality
  • resistance to struct authoring: get buy-in from writers; express ROI
  • capture metrics: link rot, typos, accuracy
  • reasons to adopt a standard: interchange, access to library of tools and techniques, user community
  • objection: “but our content is special”
  • 85% of the problems are the same–most problems are well-known
  • as a consultant, “accept” that it is special but offer as a starting point
  • tech writers don’t have some foundational concepts
  • “you go to LA, everyone has a screenplay, you come to Silicon Valley, everyone has an app”
    1. costs of inefficiency are often hidden
    2. people focus on bad experiences to the exclusion of future possibilities
    3. writerly types don’t like losing creativity
  • standards help us serve customers better: reuse, interchange (localization)
  • XML is a recommendation, not a standard
  • magma: minimal architecture for generic …
  • when is it appropriate to use a standard?
  • standard as a path to follow or a convention vs. as defined by a standards body adoption of a standard is a long path, not an augmentation
  • standards don’t help if your content is bad
  • convert legacy content, or make a break?
  • garbage in garbage out applies to standards also–and you can still be compliant
  • manage expectations with mgmt., users, customers
  • start with requirements–have to be able to articulate what you are trying to accomplish
  • big benefit of standards is to defer tools decisions until requirements are clear markup is data centric, tools are peripheral
  • when you use standards, you own your content; when you use proprietary tools, the vendor does as a consultant you are the expert, but use issue-centric conversation–build a business case
  • failure is blamed on consultants or standards exchange

How to work with offshore vendors and/or globally distributed project teams, collaboration across global teams, collaborative writing in distributed teams, etc.

This session offered a lot of anectdotal experiences from the participants. The moderator began the session by stating that there is a big cultural misunderstanding between the East and West, and that when dealing with vendors from Asia or India, you cannot make the same assuptions that you would  make if you were dealing with vendors from the US or Europe. In the Indian language, there is no word for “no” and if you ask for something, you will either get “yes” or a made-up story, or silence, but never “no” or “I don’t know.” It is also rare for people from India to ask clarifying questions because it’s considered rude to not just do exactly as they were told.
Sometimes working with global teams has benefits, such as the ability to timeshift the work, but it can also be frustrating because of communication/cultural issues. Here are a few tips that partcipants have tried in order to help alleviate these frustrations:
  • Use webex, videoconferencing, IM, and email frequently, to increase the amount of communication that occurs.
  • Get feedback about how the call/webex went, perhaps not immediately, but a day or two later to give people time to gather their thoughts and respond
  • Become friends on Facebook with some of your global colleagues, to help learn about them as individuals
  • Read books such as “Speaking of India: Bridging the Communications Gap when Working with Indians”
  • Meet face-to-face, either by going to your colleagues’ location or by having one of more of your colleagues come here
  • Interact with people who are local, but are from the country in which your colleagues reside
  • Have the right attitude and don’t place blame; try providing constructive criticism in a 1:1 situation rather than in a group
  • Encourage people to ask questions; start small and praise even the most minor sorts of questions (this applies more to places like India and Japan, and not so much to places like France and Israel)
  • When working on collaborative doc projects, set up clear ownership for diffferent parts of the document
  • Use wikis with outlines, schedules, and places for peer reiews
  • Take a class on working collaboratively, such as those offered by Joanne Hackos

What is the most efficient way to teach a traditional writer how to write topic-based content?

Scribe: Michael Belef

These notes are rough and incomplete. Our session was more about questions that students and writers had about learning topic-based writing, not how to teach it.  Alas, since Mike was the designated scribe and also the lone writer with structured experience. His notes below are not complete as he tried to answer many questions.

Participants and Experience:

  1. Bio Tech writer. Uses FrameMaker, uses context sensitive help, Started as software builder. The company outsourced the software teams so she transferred to tech writing.
  2. Tech writer since 1982, software company. No one wrote user docs. Later, got tech writing certificate at De Anza. Used a Texas instruments T-1000.
  3. One writer: 7 years at Medical instruments, three years in aerospace, 13 years in computer industry, Learned to use tools on the job. Sun workstations, PCs, Macs, many tools over the years.
  4. Three Students – interested in all aspects of tech writing, tools, how to learn tools and craft.
  5. Various levels of experience but none have structured authoring experience.

We discussed content tagging versus tagging for format.

Start writing from the perspective of chunking.

Keep topics small a couple paragraphs.

You can re-use, share info across departments, like marketing and training.

One writer explained that the developers create a hook file which the writer creates content for so it will display at that hook.

Have a mentor who can also teach. If you have an editor well versed in structure, the editor can really help writers grasp structure. I got my best training from my editor. The editor can focus more on content planning and helping the writer stick to the rules, while writers learn the tools and work with subject matter experts.

What programs should we focus on learning?  Well it depends on what you company or customer will use… oXygen Author, FrameMaker, XMetaL, others.

See the book DITA Best Practices, the author, Laura Bellamy is here today.

Mike: I think you have to just get hands on tools to learn it…. (Vendors at TC camp could help advertise their business by helping students and writers learn to use their authoring tools. Post the docs online so students can point to it and discuss it in class later.)

Mike also suggests that some of the solution providers here today, help mentor people who don’t have structured experience, show them what you do. This can help sell your expertise, demonstrate your business services.

Forms- and Wizard-based Authoring

currently unavailable

Visual presentations that are not text

  • Goal is to communicate
  • Need to consider pictures – Easy to grasp/retain info
    • Charts
    • Diagrams
    • Flowcharts
    • Tables
  • Requirement Analysis
  • Easy to spot gaps (flowcharts/diagrams)
  • Videos
    • screencasts for help with/without audio/captions
    • how-to/repair videos
  • How can we improve visual communication?
    • create portfolio
    • sample docs
    • magazine clippings
  • book recommendation: Edward Tufte books, Indi Young “Mental Models”

Session 3 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.

How to build your help structure and navigation for web help – product based vs process based, etc

Facilitated by Neal Kaplan

  • Several writers in the room were involved in moving from heavily UI-based docs to process or task-focused docs.
  • Users want to know, “How do I do my job?”
  • How do you associate topics to a dialog box if you are doing context-sensitive Help? (When you have multiple tasks for a single dialog box.)
  • Need to approach documentation from both sides – some users need to know how to do a task, and some users need to know what a widget does.
  • Minimalist writing – how do you decide how much content you need? How do you know when there isn’t enough content? There was a lot of discussion of how to use metrics to track which content customers actually use. Some were using Google Analytics, others proprietary tracking systems.
  • An unusual take on the value of topic-based writing – the complexity of a topic can be used as a metric for the complexity/difficulty of the task. This can be used to improve the user experience.
  • Using collapsible sections to hide extended discussion can be a nice way to balance the needs of users who want quick info versus those who want more detail.
  • Search vs. ToC versus index: Are customers still using ToCs and indexes? Anecdotally, writers have noticed that some users and reviewers don’t seem to see ToC’s when they’re there.
  • Many users don’t read in detail. Put your important info up front. Give a meaningful set of link choices.
  • One of the side-effects of a cloud-based world: We don’t have the same de-facto standards that we did when people were tied to an operating system. (For example, Windows UI conventions and Microsoft Help provided a consistency that people were used to.) Now every interface looks different, and every help system looks different.
  • Some people just like PDFs. Is ePub a viable alternative?
  • The distinction between Help and PDF/manual is not so strong any more.
  • What is the impact of writing for translation? How do people handle graphics for translation? Most people limit screenshots because of translation cost, but users like them. They have visual appeal, provide a “You are here” signpost for the user

TC in an Agile environment

Facilitator: Shari Clare (Voltage)
Scribe: Amy Bowman (VMware)

  • Overview and general thoughts
    • Shari started by describing some of the Agile process and commonly used terms
    • The process provides continuous feedback to the team members about what is going well and what needs to be changed
    • Agile increases the visibility of the documentation/the information developer if you are a part of the process.
    • You see SMEs on a daily basis.
    • Everyone is equally responsible for the story being accepted. If no one has reviewed the doc and the story can’t be accepted, the whole team is “at fault”, so the team is theoretically more likely to help you when you ask (for example, to review docs).
    • Scrum won’t solve your problems. If your dev team has problems, scrum will put the issues in the spotlight rather than fixing them. Don’t blame scrum if you still have issues after adopting it.
    • Training is key! Teams must have solid foundation in the principles of the process to be successful
    • Different teams might have different levels of maturity (experience with Agile). This can introduce conflict when teams try to work together.
  • Ideas
    • Suggestion from session participant: Scrum in a day. Have the group do a day-long exercise/off-site where they learn the process by going through a scrum-in-a-day.
    • Suggestion from facilitator: Training by Mike Cohn of Mountain Goat Software (can be done online)
    • Suggestion from session participant: Should tech comm be the people writing the user stories?
  • Problems
    • Agile doesn’t really take docs into account. We are forced to retrofit the process to get our work done.
    • Sometimes UI components aren’t done until the very end
      • Possible solution: docs lag behind the development by one iteration
      • Possible solution: decouple the doc tasks/process from the dev process. Have separate scrums with your writing team and then sync up with dev every week
    • Collaborating with offshore teams
      • Possible solution: weekly sync up (scrum of scrums — meeting of the scrum masters). Provides forum for requests, get to know each other
      • Possible solution: Send each other a list of stories and tasks you have worked on every week
      • Possible solution: Put watches on stories to see when they change
      • Possible solution: Record your daily stand up via WebEx. The offshore team views your stand up before they do their stand up (and vice versa – you view theirs before you have your stand up).
      • Suggestion: Go to visit the team or have them visit you! If possible, this is a huge step toward successful collaboration
    • Doc work doesn’t always fit with/align with development work.  (For example, a ten-line code change might be a one-hour task for a developer, but it might introduce eight hours (or more) of work for the docs.)
      • Possible solution: If a user manual (for example) doesn’t match up with the dev work, it can have its own story. Break it down into chunks that you can demonstrate at the end of a sprint.
    • Where do you fit in tasks like release notes, indexing, general maintenance?
      • Possible solution: Some people said that these tasks can be done when the dev work for a user story doesn’t have doc impact.
      • Suggestion: Acceptance criteria for a story should include the doc tasks — the story isn’t done until the docs have been written, reviewed, review feedback incorporated, and doc “demo”ed.

Wrangling difficult personalities

  • Find common ground, become their best friend
  • India people like to be asked about their families
  • Ways to work with remembering names
    • If you don’t remember name, show that you remember something about them
  • Difficult bosses
    • have witnesses – get evidence, save emails
    • see employment attorney (not HR)
    • make emails specific “x told me to do/not to do this”
    • don’t brown-nose
  • When you get work requests that are verbal: send email summary of conversations, “CC” those who may be affected (i.e., projects are “at risk” or affect timelines)
  • Book recommendations – Snakes in Suits, The Psychopath Next Door
  • Dealing with screamers: find the one person who can shut them down
  • Unavailable SME: send email, copy boss, people ducking you..

Basic competencies for entry-level and advanced information developer positions-> and implications for training/education, from certifications to degree programs, to advisory boards, to general professional development; skills for new writers, portfolios

currently unavailable

How do you decide what content should go into a doc for the mobile version of an enterprise software app? Do you rewrite or just cut down on amount of content?

currently unavailable