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”
- costs of inefficiency are often hidden
- people focus on bad experiences to the exclusion of future possibilities
- 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.
- 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:
- 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.
- 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.
- 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.
- Three Students – interested in all aspects of tech writing, tools, how to learn tools and craft.
- 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”