Session 3 Topics For Discussion
- Generating PDF from DITA
- Teaching topic-based oriented writing
- Review Process
- Style Guides
- TC in an Agile Environment
Generating PDF from DITA
Session Title: Generating PDF from DITA
Scribe: Mark Giffin
- “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
Teaching topic-based oriented writing
Scribe: Joanna Broadbeck
- 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
- 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.
Scribe: Susan Allen
- 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
Scribe: Heidi Miller
- 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
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
- 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
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
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