h1

LavaCon2018: Day 3

October 25, 2018

The last day of LavaCon 2018 was full of breakout sessions, with no plenary sessions. Here are my notes from the sessions I attended.

Diversify your content ecosystem

Bernard Aschwanden took us through a heap of information, a tiny amount of which I captured in notes. I’ll have to watch the recording and view the slides later. The notes I did make were:

  • clarify, simplify, and reuse content
  • track/share costs — you can cut costs by sharing content, but even better is to generate revenue. Docs can reduce costs AND generate revenue
  • content is a core business asset
  • content is cross-department and cross-functional — it shouldn’t live in silos
  • search is a headache, find is a solution (think of searching for your car keys [anxiety] versus finding your keys [happiness/relief])
  • think about components, not complete docs
  • reuse components across business verticals
  • how and what to measure — process efficiencies to reduce costs; revenue growth

Cross-format and cross-silo: Lightweight DITA (LWDITA) for intelligent content

(Michael Priestley, IBM)

  • DITA is a standard, which means it’s portable and scalable
  • Why isn’t DITA everywhere? perceived complexity (too many tags, too hard to customise, steep learning curve) and it’s XML (software developers mostly use XML for data, so when JSON came along, XML was dead for them; bias against XML in favour of Markdown, HTML5, custom formats)
  • Simplify the model — no longer reliant on XML schema; cross-format content standard
  • LWDITA — has only 2 doc types (topic and map), 40 elements types (33 from DITA 1.3, 7 for multimedia support), and 3 formats (XML, HTML5, Markdown)
  • LWDITA is less flexible but easier to learn
  • Full DITA — advanced features, more flexibility, mature tools
  • LWDITA — start simple, eventually more tool support, don;t need XML
  • Tools that support LWDITA include oXygen XML Editor, Author, Web Author; SimplyXML Content Mapper; and others
  • Publishing options — DITA-OT; XML Mind DITA Converter; Adobe AEM Publishing
  • people and processes are the hard part — tools are the easy part!
  • more info: http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.html and https://wiki.oasis-open.org/dita/LightweightDITASubcommittee/lwditatools

‘Tis an unweeded garden that grows to seed — cultivating a weed-free content ecosystem

This was an info-filled talk by Helen St Denis, Conversion Services Manager, from Stilo. She talked about pre- and post-conversion tasks for DITA, amongst other things. I tried to keep up with her but these notes may be missing a few points.

Content strategy includes:

  • content modelling
  • taxonomies
  • setting up storage, reuse and publication facilities
  • perhaps style guides

First step is the content audit:

  • what do we have
  • what do we need to keep
  • what’s OK and where is it now
  • what needs to be rewritten
  • what should be moved first

Writing for minimalism:

  • focus on action-oriented approach
  • understand the users’ world
  • recognise the importance of troubleshooting info
  • ensure users can find the info they need
  • remember that every page is page 1
  • rewrite for reuse
  • rewrite for localisation/translation even if not going there yet — consistent terminology, concise, clear (avoid idioms), grammatically complete (don’t forget ‘that’)
  • minimise inline x-refs — move into a relationship table

Content model:

  • topic-based — smallest unit of content that makes sense by itself
  • 4 basic topics — task, concept, reference, and troubleshooting
  • do not include multiple types on content in the one topic — just one

Tasks:

  • only 1 set of steps per task
  • if there are two ways to do something, you need two tasks
  • doing and undoing something = two tasks
  • improve conversion by adding paragraph breaks between <step><cmd> and<step><result> or <info>

Short descriptions:

  • these help with findability
  • either use everywhere or nowhere — not a mix; everywhere is best, but time consuming

Pre vs post conversion cleanup:

  • if you don’t need the docs immediately, convert after
  • if active docs, do pre-conversion cleanup

Really need to do:

  • topics — break out based on heading levels
  • topic types — many not need immediately, but much easier to add at conversion time, not after

Authoring conventions:

  • tasks — look for gerunds, ‘how to’
  • concepts — look for ‘about’
  • references — look for titles with command names in lower case
  • paragraph styles — look for styles like ‘procedure heading’
  • consider adding prefixes in text (e.g. T_ for task, C_ for concept, R_ for reference)

Topic types:

  • can allow conversion to determine these based on content of topic (e.g steps = tasks; syntax diagram = reference)
  • can use in combination

Data model:

  • tasks are trickiest
  • only 1 set of steps per task
  • no sections — stuff before and after MUST be in the correct order

Inline elements:

  • especially important if you will localise/translate
  • some things may not be translated
  • some things will be presented differently in different languages
  • may already have styles/typographic conventions for these
  • character-level style names (if still working on the docs); if not, consider colour highlighting the elements

Don’t need to worry about:

  • tables
  • links
  • variables
  • conditions
  • having all the answers

Other considerations:

  • graphics — supported format; where stored; findable
  • do graphics have superimposed callouts? Are they easily editable?
  • paragraph breaks — watch out for hard and soft line breaks
  • look out for text in the wrong order (e.g. from text boxes, or from inDesign)
  • eliminate superfluous docs
  • some legacy content may have reuse already built in; some is from copy/paste
  • legacy reuse can be at doc level (e.g. Word master docs), phrase level (e.g. Word auto text)

DITA reuse:

  • reuse is at the element level
  • maps can bring in other maps
  • phrase level — conrefs, keys
  • conrefs allow reuse of single DITA element (para, table, single list item, whole list)
  • conref range — first and last elements MUST be the same

Identifying reused content:

  • text inserts/snippets — use the file name
  • create conrefs using the filename as the ID
  • each block level element becomes a conref

De-duplicating (dedup’g) content:

  • prune redundancies
  • spreadsheet to track duplications — very painful and slow! Avoid
  • tools can help ID identical and near match content, but still need a human eye (e.g. Stilo’s OptimizeR, which compares DITA elements, shows diffs, you choose to dup or not, auto creates conrefs, auto adjusts maps to refer to selected topic, gives a report of what has been dedup’d)
  • allow time for implementing a reuse mechanism

Content 4.0

(Pam Noreault and Chip Gettinger, SDL)

  • Landscape: any device can be used to display content
  • Customer demands: By 2020, customer experience will overtake price and product as a main differentiator

Product content:

  • branded tech product info is 2nd most trusted source (they didn’t state what the 1st was)
  • customer support (phone/online) has dramatically decreased
  • product info must be available in various languages, for various devices and formats
  • customers want to go to one place to get info

Trends:

  • shared content strategy — content mashups, portals, microcontent, blogs, videos, chatbots, Twitter feeds, documentation and product help, KB articles, communities/forums
  • shared enterprise taxonomy — make content findable by applying consistent terminology and metadata
  • device independence — design content for any device; mobile first; responsive design; how will voice interaction affect content
  • design for global customers — plan initially for translation even if not doing so now
  • adaptive personalisation — machine learning, AI, natural language processing in real time

Actions:

  • review info architecture (IA)
  • be flexible and willing to support new use cases
  • consider content granularity
  • taxonomy — seek help from others, including industry experts
  • work within the politics of the organisation to gain allies — get a seat at the table
  • get your IA house in order
  • move ahead in increments
  • gain knowledge through research and people — seek out those who’ve already done it
  • start with a small pilot and expand
  • morph again and embrace change
  • create a global content strategy
  • understand where you are and where you need to be
  • know the gaps and narrow them
  • support your company’s global business
  • improve the quality of your source content
  • don;t create another content silo
  • get the global strategy completed first
  • Google Translate is NOT the solution!
  • research tools, infrastructure and whatever else you need
  • mix strategy with technology
  • empower SMEs, contributors and authors
  • make content findable and relatable
  • connect contextually (e.g. classified searches vs free text)

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: