Session 3 Summaries – 24 January 2015

Session 3 Topics For Discussion

Generating PDF from DITA

Session Title: Generating PDF from DITA

Scribe: Mark Giffin

Top Takeaways:

  • “It’s Hard”


PTC Arbortext makes big PDFs for FM small pdfs when book is graphic-heavy and big, dense graphics involved. Not a large community, few answers

DITA 1.5.3 needs simple changes

It’s Hard.

Teaching topic-based oriented writing

Scribe: Joanna Broadbeck

Top Takeaways:

  • Topic-based authoring: Writing with the goal of describing one thing (topic) as opposed to thinking of a chapter, book ,etc. A topic should be able to stand alone
  • To teach a writer (a) have before and after examples in addition to writing guidelines (b) provide extensive review & guidance on the writer’s first big assignment (c) have writing buddies and referesher training for ongoing reviews to ensure topic writing remains consistent across your team
  • writers tend to write about everything they know, not what reader needs to know
  • understanding and defining TOPIC TYPES is key. Examples of topic types – concept, process/task, reference


What is most efficient way to teach a “traditional writer” in a topic-oriented way?

One company moved to DITA we rewrote everything. Developed process for teaching topic-based writing conversion. Everyone read IBM book. Content workshops – writers sat with editor and worked through restructuring the doc. Where is conceptual? Procedural task? etc. Tease apart the bits.

Book: IBM Developing Quality Technical Documentation

What is topic based authoring? Thinking of unit of content as a TOPIC rather than book, chapter, etc. Topics address a single thing. In theory: answer 1 question or explain 1 thing, and not rely on context.

What are stumbling blocks? It’s a mindset change. And there are tool issues.

Topic-based is in pieces, it’s not linear. Topics may be consumed in any order (for example, think of landing on a search result in the “middle” of a “document” – reader should still be able to make sense of it without having read from the start of “the document”)

Links to related content

Collection types and relationship tables is what DITA has to deal with linking to related topics

How to give a new writer training to think of writing in topic style?  (1) have writing guidelines with examples (2) have “before” and “after” examples that have been well reviewed (3) repeat training workshops as new writers are hired; have refresher training too (4) do extensive developmental review and edit with peer and with editor (for new writer on first assignment) (5) have “DITA-buddies” that help coach writers (6) Editors are important!

DITA allows you to define common structures like tables, etc. NOTE: DITA is topic-based, but topic-based is not DITA

Good writing can happen from document down or topic up

Are there qualitative metrics?

One company found docs were better after this: (1) more consistent (2) more accurate because reuse is more accurate, no longer cut and paste (3) topic-based writing created much better, succinct pieces of text that made overall more clear

Mental shifts – linear is often product-focused. Topic-based can be more reader/user-focused. What is user wanting to do?

Writers tend to write everything they know, not what reader wants to read

You can reuse at topic-level

Topic-base writing is easier for writers than learning DITA. DITA should be as hidden as possible to keep writers efficient.

Author-IT is not DITA, but it is topic-based

Process (done by multiple people over time) vs Procedure (done by one person)

Writers need to understand and agree on types of topics (conceptual, process, procedure, reference).

IBM doesn’t do doc plan – but topic names and short description, which is then reviewed with an editor.

Outline is old school, but has a place: introduction, audience, etc. — With Topics, you “Annotate” the outline

“Short description” is an introductory sentence in a topic.

Often you will find a section of traditional writing will end up being multiple topics.

Book: “Author Experience” by Yagodich about going to CMS’s “CM-Ness”


Scribe: Tracy Baker

Top Takeaways:

  • We have a lot to learn
  • People consuming content on a mobile device are trying to get something done -> task based content


What kinds? Mobile apps, documentation, end-user displayed on mobile device

We talked about what does mobile mean?

Need to learn who or figure out who your customer is

Maybe mobile content is an app?

We discussed the meaning of responsive design

We surmise that mobile users are trying to get something done as opposed to reading to learn

M.*  sites are less desirable than an app or a responsive site.

Review Process

Scribe: Susan Allen

Top Takeaways:

  • Tools support the process
  • PDF reviews are the norm – either via email or shared review
  • There are some other collaborative tools, but no consensus
  • Targeting reviewers is important to get responses
  • One “trick” : send review and schedule a meeting a the deadline: in case they don’t have time for review. Then, say if they review it beforehand, no need for meeting


How can we improve the process? Tools support the process. Tools for HTML markup reviews? Convert to Google Docs – Sometimes write it there

PDF reviews – individual emailed copy or shared on server

Google Doc – can control who can change vs control

Code collaborator – code dev tools that support putting comments in PDF – made by Smart Bear – Coders already use it

Enable developers to edit xml

Give more weight to reviewer who is closer to the user

Targeting reviews is important. Highlight points you are not sure of

For large doc – send TOC and ask who should review what

Meeting for first review – walk through. Not finished? How do you want to handle this?

Schedule meeting for deadline. If you can review before, we don’t need meeting.

Oxygen web help with comments (requires database at back end)

Metrics – task tracker for comments

In agile environment – is review plugged into the process? Engineer has no incentive – get it into the process

Using Jira – assign review as a task

“Reviewer Creep” – when reviewers keep getting added. With tracking program, reviewers must be in the tracking program

MadCap makes review tool – does it help? Requires users to install it. “Contributor” also facilitates input flow from other authors. Once installed, works well

DeltaXML tool = change bars

Leave in one grammatical error

User feedback? Quality is often low and frequency is low

Style Guides

Scribe: Heidi Miller

Top Takeaways:

  • Why = Achieve consistency, get answers quickly, users benefit
  • Problems = multiple style guides due to different audiences, cultures, language, resources
  • Recommendations = Pick a basic style guide, have a good reason for exceptions
  • Last Line = People have strong opinions


How many have been responsible for style guides? Several, lots of experiences

What goes in? Usage, Mechanics, Style

Recommendation: Steven Pinker’s “A Sense of Style”, cognitive science, psychology professor Harvard – takes science => working principles

Microsoft, Chicago Press as basics, good for new people

How? Details, Examples – Do you add tags, how to/when to

Cascading style guides – in-house SG (minimalist) vs Full SG (comprehensive)

Writing to inform vs writing to convince

Web style != Chicago/Microsoft: Yahoo, writing for web, also IBM.  Good for (1) tech people (2)  newbies to field (3) ESL (4) computer or human translation

Confession: One of our group members reads style guides for fun!

Others write several style guides – knowledge base, differences in users must be considered. Science writing needs it’s own style guide

ESL concerns – using American idioms might not work

Example: The writer dealing with bad docs: audience was the writer; Goal to achieve consistency. Content was procedural, printed, many things didn’t fit (terms, procedures); did own SG to have everything in one place: Start Clean.

People have strong opinions about SG. During Merger, writing teams combined, used Layered SG. Use Publishing SG then Internal SG for exceptions. SG online, searchable. Read me first (Sun), Monthly meetings for new/changed entries.

List out what not to do (British/American)

Reference Dictionary to settle spelling dispute

Product glossary

How much detail? Don’t invent the wheel. Use standard materials. Make it short… Or not? Search mitigates this

When picking base style guide, consider the purpose of the SG (MLA, Words into Type< AP ,MS, Yahoo, Sun)

How to keep track of all the SG you are using? Conscious of who/what you are aiming for; reason to use provides clarity

Realistically, as a writer, how do you get an answer? Co-Workers, Internet, SG, team, physical hard copy, Google.

Working without an editor – have a good reason for exception.

Pick basics, then copy editor makes/notes/records decision

TC in an Agile Environment

Scribe: Cherie Woodward

Top Takeaways:

  • Have a champion for TC
  • Tie docs to dev tasks – can’t close task until doc task is closed
  • entire team learns together


Agile – incremental, nimble, development goals, agile manifesto

Work broken into easily complete-able tasks

Shortened time-to-market

Writers fit how?

Get documentation into scrum or sprint

build in reviews

user story isn’t accepted until TC is complete

Daily 5-min meetings: What did you do? What are you working on? (standups)

What problem does story points solve?

Estimate hours = story points. 13 is highest sprint tracking effort

65% time work, 35% time overhead or 70-30 (based on effort, ability, complexity)

Always working on tasks – less downtime

Doesn’t necessarily fit the best model for user assistance

By programmers for programmers

Minimum viable content/minimum viable documentation

Customer feedback?

Jira – link your task to an ENG/Dev task; can’t close task until you close your task. Doc tasks can be skipped until the next sprint

QA – time them into test docs while testing code

Doc tasks created after Dev completes their tasks – get team involved in learning process together

Management buy-in to champion TC