h1

The perils of global IT support

December 5, 2018

I had an issue with connecting to some of my main client’s network locations today. The second-level support person (in the Philippines?) solved it, but not after checking some stuff in DOS where he saw that the last time I rebooted the laptop was April this year. Um, no. I shut down every night, and had also restarted about an hour earlier before contacting support to see if that would fix it.

He insisted it was April when I last rebooted and highlighted the date on the DOS screen. Yeah, 4/12/2018 is April 12 in US date format, but is legitimately 4 December in Australian date format, which my laptop is set to! He apologised, and hopefully learnt that different countries display their dates in different ways.

I don’t know why the backend of computers don’t store and display the date in ISO date format (e.g. 2018-12-04 — YYYY-MM-DD) — it would solve a lot of issues.

See also:

[Links last checked December 2018]

h1

Editing: It saves your readers’ sanity

December 1, 2018

Bottom line: Even something as simple as a birthday invitation can benefit from editing!

A client and I have recently been discussing academic journal writing and lamenting why it’s so stilted, wordy, written in the third person, and generally hard for an audience (especially a general audience) to understand. Our email discussion was triggered by an article in The Atlantic: The myth of dumbing down.

A few days later he shared with me a birthday invitation he’d received from an academic he knew. It was some 950 words long! While it mostly used plain conversational language (there was at least one ‘therein’…), it was way too wordy. The essentials of the message were lost or well hidden in the word salad.

I couldn’t help myself—I edited it down to 250 words and sent it back to my client, purely as an example of how editing could keep the message but communicate it in clear, plain language.

Below is the original version (with all personal and place names changed) and my edited version. The original also included the names of those who were attending and those who’d put in their apologies, which I deleted from both versions.

Original version (950 words)

Dear Family and Friends,

This email will communicate (hopefully final) details regarding the re-scheduled 50th-birthday dinner-party for me at Gurpreet’s Indian Restaurant at 280 Highline St., Anytown, on Saturday 1st December.

VENUE: I realise that some of you have eaten at Gurpreet’s Anytown restaurant in the past and so will know how to find it. But for those of you who need instructions about its location I detail them in the following section. The restaurant is on the south side of Highline Street (= Main street of Anytown and Rosella) and is just two-shops east (i.e., towards the Melbourne CBD) of what used to be the Main Town Hotel on the SE corner of Highline Street and Mountain Street (which former hotel is opposite the Anytown Post Office). The restaurant occupies a converted terrace-house and is conspicuously signed at the front above and at street level; its map location is: 2018 edition UBD, Map 32 A6; see also Google Earth image attached).

PARKING: Highline Street is metered along its entire length as are many of the side streets running off it to the north and south. The meters on Highline Street are turned off each day at 7:00 pm but not on the side streets (so I’m told) and resident-permit restrictions apply in some of these side streets after business hours.

There is a 30-minute FREE parking concession along the whole of Highline Street, but you still need to get the relevant ticket from the meter and display it on your dash board. So if you were to find a parking space on Highline Street relatively close to the restaurant after 6:30 pm and obtain a 30-minute free ticket and display it on your car dash, you would not have to worry about getting a parking fine for the rest of the evening.

Nearby to the restaurant, there is also a Council-owned free parking lot on the north side of Battle Street (2018 edition UBD, Map 32, B7) just west of its acute-angled junction with Highline Street at Federal Square (this lot is not exceptionally large off, and possibly ‘busy’ on Saturday nights). This lot is best accessed while driving east on Battle Street (so as not to have to turn left against the oncoming traffic if otherwise driving west). There is a 2-hour time-limit in this parking lot but I think that restriction ends at 6 or 7 pm (read the signs therein); so if you park there after 6:00 pm there shouldn’t be any trouble about being fined (see Google Earth image attached for location of this parking lot).

Additionally, there is free unlimited parking on all four sides of the MacDonald Terrace, a divided-lane street (with very wide intervening green-strip) that runs parallel to Highline Street one block north of Highline Street between Birchbroom Road (on the west) and Roundhouse Street (on the east). There is also free parking on Carton Road (= eastward extension of MacDonald Terrace; see attached Google Earth image). Parking on MacDonald Terrace and/or Carton Road will entail having to walk up-slope for a whole block to the restaurant, so is not recommended for anyone with mobility problems.

Anyone with a disability parking-permit can park anywhere free of charge any time unless signed-posted otherwise.

TIME OF ASSEMBLY: Can I suggest that we start assembling at Gurpreet’s between 6:45 and 7:15 pm? If we are all assembled by say 7:00 or 7:15 pm, then we could begin the dinner at 7:15 or as soon as possibly thereafter. Please try to be punctual so as to facilitate an ordered start to the dinner.

DRINKS: Gurpreet’s is both licensed and BYO. I suggest you buy the house beers (which include both Indian and local brands), but bring your own wine (because the restaurant wines are relatively expensive — this is true of all restaurants because the licence to sell alcohol is very expensive!). A large variety of both Indian and local non-alcoholic drinks are available. Also, there is a bottle shop with a large range of beers and wines just around the corner from the restaurant (= the only surviving licensed element of what used to be the Main Town Hotel), so if necessary additional drinks can be purchased there.

MENU: Some of you I know have dietary restrictions. Hence I suggest that those persons order their main course(s) separately, while the rest of us share the Banquet Menu. Anyone who doesn’t want to share in the banquet menu can order separately. I have already discussed this suggestion regarding the menu with the proprietor and that is OK with her.

RESTAURANT CONTACT DETAILS: In case anyone has last minute problems with attending the get-together or arriving there on time and need to alert the restaurant, it’s landline’s and mobile numbers are: Landline: 5555-5555; Mobile: 0413-555-555

Proprietor: Shivani Singh (= Gurpreet’s wife; she usually now looks after the Anytown restaurant and her husband [Gurpreet] and their two sons [Deepak and Vikas] look after their other restaurant at Highline Harbour and at their Function Centre at Congress; I don’t know whether Gurpreet and/or either of his sons will be at the Anytown restaurant on Saturday night).

PUBLIC TRANSPORT ACCESS: Busses 41 and 57 leave from Stand A at the QVB in the Melbourne CBD and stop in Mountain Street beside the Anytown Post Office (and across the road from the bottle shop). Both these buses will return you to the Melbourne CBD from bus-stops virtually outside the restaurant.

Edited version (250 words)

Details for my 80th birthday dinner

Date and time: 6:45pm for 7:00pm, Sat 1 Dec 2018

Place: Gurpreet’s Indian Restaurant, 280 Highline St, Anytown (almost opposite the Anytown PO); 5555 5555 or 0413 555 555

Food and drinks:

  • Banquet Menu. If you have dietary restrictions, order your main course separately
  • The restaurant is licensed and BYO. Suggestion: Purchase beer there, but BYO wine. There’s a bottle shop around the corner

Parking:

  • Metered parking to 7pm along Highline St (first 30 minutes free—so you could get there at 6:30, but you must display a ticket on your dashboard)
  • Free but small parking lot on the north side of Battle St, near the junction with Highline St at Federal Square; usually 2-hour limit, but check signs as likely no limit after 6 or 7pm. Best access is if you’re driving east on Battle St
  • Free unlimited parking on all sides of MacDonald Tce between Birchbroom Rd and Roundhouse St (parallel to Highline St and one street away). Avoid if you have mobility issues as you have to walk up a hill
  • Free parking on Carton Rd (extension of MacDonald Tce). Also avoid if you have mobility issues
  • Side streets: Avoid; likely only for residents with permits.

Public transport: Take bus 41 or 57. Both depart from Stand B at the QVB and stop in Mountain St beside the Anytown PO (across the road from the bottle shop and restaurant). The bus stop for the return trip is outside the restaurant.

***********

Contact me (details on the About page) if you think your written communications could benefit from editing such as this.

h1

Word: Create a custom dictionary populated with thousands of terms

November 30, 2018

There are plenty of websites that tell you how to create a custom dictionary in Microsoft Word. But most assume you only have a few words to add to that dictionary. But what if you have thousands? Doing it one word at a time using the usual methods is painfully slow and not ergonomically sound.

I had such a situation a few months ago, but neglected to write up what I did. I had 4000+ Latin and common species names I’d gathered from public lists that I wanted to add to a unique dictionary so that Word didn’t flag them as spelling errors, except if they really were spelling errors or if they were species I hadn’t included in my species dictionary. I wanted a special dictionary file that I could copy and use on other computers, and turn off if I no longer needed it, so I didn’t want these words added to my default dictionary.

The first thing was to find out where the dictionary files are stored. I use Word for Windows, so this information is for Windows. By default, the Office dictionary files (Office 2010 to 2016, at least) are stored in C:\Users\<username>\AppData\Roaming\Microsoft\UProof and have a *.dic file extension. (Note: Follow these instructions if you can’t see the AppData folder.)

Now, *.dic files are just text files with a different file extension. This means you can open them in a text editor (e.g. Notepad; I use EditPlus because it has a ‘sort’ option, but Notepad works fine). Once you’ve opened a *.dic file in a text editor, you can add, edit, or delete entries. Just make sure you save the file with the *.dic file extension, not *.txt.

Because *.dic files are just text files, you can also use a text editor to create a new dictionary file. However, I started with Word because I wanted to sort them and run a macro to check for duplicates. The main thing to remember is that each word MUST go on its own line. You cannot have two words on one line. So, in the case of Latin species names, I had to put each part of the name on a separate line — this is why I had to sort the list and look for and delete duplicates (there are more than 700 species of eucalyptus, for example). Once I’d done that I copied them into my text editor, and continued from step 3 below.

In essence:

  1. Open a text editor.
  2. Add your words, ONE only on each line. Press Enter after each word.
  3. Save the file with a DIC file extension (NOT txt).
  4. Save it to the UProof folder (C:\Users\<username>\AppData\Roaming\Microsoft\UProof).
  5. Open Word and go to Word Options > Proofing. (You need to tell Word there’s a new dictionary to check.)
  6. Click Custom Dictionaries.
  7. Click Add.
  8. Select your new dictionary file, then click Open.
  9. Select the check box for your new dictionary file so that Word knows to check it.
  10. Click OK.

That should be it!

[Links last checked November 2018]

h1

Word: Apply a highlight to all tracked changes

November 22, 2018

Over on an editors’ group I’m part of on Facebook, Wendy asked if there was a way to highlight all her tracked changes. Well, tracked changes are already shown in a different font colour and formatted with underlines (insertions) or strikethroughs (deletions) by default, but she wanted more.

As she found, find and replace didn’t work with finding tracked changes. So she was looking for a macro. I’m not good at writing macros, but I’m pretty good at finding them! And then at modifying them for my purposes. A quick search found two possibilities:

I tested them both on an 80p Word document with some 1450 revisions — the first one worked well and quickly (less than 1 minute), but accepted all my track changes and applied a dark green highlight, which I found hard to read. The second was either still going after an hour, or had hung. Whatever, it had stopped Word and I had ‘not responding’ in the title bar. I ‘killed’ Word and decided to only go back to that one if I couldn’t make the modifications I wanted to the first one.

Meantime, I modified the first macro to NOT accept all the track changes and to change the highlight colour to pink instead of the dark green. Here’s my version of that macro in case it ever disappears from the intertubes at that website. Full credit goes to the macro author ‘nixda’.

If you intend using this macro, copy and paste it — some of the lines may go off the page and you’ll miss this information if you type it.

Sub Tracked_to_highlighted()

' Macro provided by nixda, 18 Sep 2014, https://superuser.com/questions/813428/convert-tracked-changes-to-highlighted
' Adapted by Rhonda Bracey, CyberText Consulting Pty Ltd, 22 Nov 2018, 
' to not accept all track changes and change highlight colour to pink
    tempState = ActiveDocument.TrackRevisions

' Turn off track changes
    ActiveDocument.TrackRevisions = False
    For Each Change In ActiveDocument.Revisions
        Set myRange = Change.Range
        ' myRange.Revisions.AcceptAll
        myRange.HighlightColorIndex = wdPink
    Next
    ActiveDocument.TrackRevisions = tempState
End Sub

[Links last checked November 2018]

 

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)
h1

LavaCon2018: Day 2

October 24, 2018

Day 2 started as per Day 1, with several short (20 minute) plenary sessions.

A journey to intelligent content delivery

The first breakout session I attended was another case study on how a software company transformed their help and documentation offering using Zoomin, in this case Pam Goodwin describing how her small team of 6 authors changed how documentation was viewed for Cherwell, an IT service management company with 450 employees.

Before:

  • focus was on ‘catch up’ documentation
  • dated look
  • poor search capability
  • different help systems and tools used for different rpoducts
  • no consolidated search
  • no access outside the software to other information

Interim (2016):

  • used SuiteHelp
  • based on DITA source
  • improved searching
  • standalone systems for each product release
  • needed separate PDF plug-in and PDF delivery model

After (2018):

  • easy to find
  • cross-product and cross-version support
  • multi language support
  • improved searching
  • on-demand PDF creation by users at point of need
  • responsive design
  • scalable
  • simple delivery model for authors
  • easy maintenance

Why choose Zoomin Docs?

  • met all their requirements
  • powerful search
  • minimal changes to DITA source
  • improved analytics (esp. for searches)
  • on-demand PDFs
  • built-in feedback mechanism
  • past relationship with vendor’s personnel
  • great customer references

How they sold it to decision makers:

  • Timing — new leadership were looking for opportunities to modernise and scale
  • Executive support — Chief Product officer (CPO) saw tech docs as a valuable marketing tool, esp. once he realised that when he was researching a product, he always checked the docs as part of his decision making
  • Strong program management — saw value and helped navigate the approval process
  • Affordable solution — able to take great strides with minimal investment and compressed timeline

Project challenges:

  • lack of UI/UX support at kick-off
  • struggled with taxonomy shift; once made, then kept it simple
  • quickly pushed multi language support and context-sensitive help to phase [not sure what I wrote there!]
  • table formatting issues
  • automation issues
  • user management
  • need a third testing environment

Results:

  • significant increase in users (27%)
  • number of sessions per user down (i.e. ‘hit and run’)
  • 320% increase in number of page views
  • 91% increase in unique page views
  • 37% decrease in bounce rates
  • 17.5% increase in Net Promoter score [what is this?] in past year; great customer comments

Creating interactive intelligent style guides

(George Bina, Oxygen)

20 years since XML standard was first published, and since Oxygen was created.

A style guide is a set of rules to follow when writing content. (e.g. how to style code blocks so the code remains correct, but visually readable). A style guide helps you avoid making mistakes.

A style guide should:

  • evolve and grow over time
  • deal with errors/new issues as you find them

But often there are too many rules.

Solution: Automate. Auto detect when content doesn’t follow a specific rule. (e.g. Schematron will detect variations in patterns in structured docs; Acrolynx).

Schematron can also check text via regular expressions. Works inside the authoring tool (e.g. Oxygen XML Editor) and is integrated within it so you get messages about potential errors while writing.

With Schematron, you select the rule and provide your parameters, plus a message for the writer.

(Note: I left this session halfway through because while automated style guides are something I wanted to know more about, what he was demonstrating was the integration between an XML/DITA editor [which I don’t use] and Schematron — I couldn’t see how I would ever use this.)

End of day plenaries

The last two plenaries of the day were from David Dylan Thomas (The content strategy of civil discourse: Turning conflict into collaboration) and Megan Gilhooly (The power of learning you were wrong). Both were really excellent!

 

h1

LavaCon2018: Day 1

October 23, 2018

I helped out on the Registration desk this morning. It was a bit of a madhouse, with three of us checking in about 450 people in just on an hour!

By the time I got into the intro and plenary sessions there were no seats left, it was hard to see the screen, and hear the speakers, so I left after Karen McGrane’s keynote.

Some notes from McGrane’s talk:

  • How to create content for any format (including audio only), any device, any screen size, no matter what the ‘next big thing’ is, even for devices not yet created?
  • Still too much reliance on visual styling (as used in books/paper) to create meaning. The web isn’t print — the way people create content has to change.
  • Content ecosystem has to be navigable whatever size device (e.g. watch to stadium screen; digital signage), even if not the primary target device.
  • Need true separation of content from form; presentation-independent content.
  • Content must be readable, browsable, and accessible on any platform/device.

Word and DITA

The first general session I attended was on Microsoft Word and DITA, and featured Doug Corman speaking about the pros and cons of each and how an add-in from SimplyXML could make it easier to general authors to write in a style compatible with DITA (yes, I checked with him afterwards about the add-in’s applicability for editing, and it’s not).

My notes from this session:

DITA positives:

  • XML standard
  • separates content creation and form
  • supports topic-based authoring
  • information typing
  • re-use at many levels
  • open source
  • large global community of practitioners
  • proven for tech pubs
  • flexible (640+ elements)
  • integration with CMSs and modern processes
  • control through a standard architecture

DITA negatives:

  • 640+ elements!
  • transformation costs from Word, XML, PDF
  • XML editors are complicated
  • DITA tools are expensive
  • expertise required for implementation
  • rework/rekeying of DOCX, PDF may be required.

Microsoft Word positives:

  • ubiquitous (at least 1 billion users)
  • does everything
  • has footnote/bibliography capability
  • has review functions such as track changes and comments
  • publishing format flexibility — fonts, templates

Microsoft Word negatives:

  • does everything (flexibility)
  • full DITA functionality is impossible
  • standards, macros can be violated
  • authoring and publishing are tightly integrated

Best of both (ideal world):

  • XML
  • topic-based authoring
  • information typing
  • re-use at many levels
  • open source architecture
  • large global community of practitioners
  • flexible — 640 elements or fewer
  • integration with CMSs and modern processes

SimplyXML has a plug-in for Word (Content Mapper) that uses the Word API and constrains (severely) the use of Word functions to match the DITA schema. Authors still author in Word, but are limited in how they use it. Cost is $300 for a single user; price decreases dramatically when more than 100 users, and even more so when more than 1000 users.

If you focus on the technical side of DITA/XML, you will fail with everyday Word users in an enterprise. need to:

  • take a well-defined systematic approach
  • understand and focus on information consumers
  • make the least number of changes
  • comply with content and markup standards
  • use a phased implementation approach — pilot, then go live in stages
  • need support from C-level leadership (i.e. CEO, CFO, COO, etc.)
  • apply KISS — keep it simple, smart person (i.e. ‘don’t try to  boil the ocean’)

Information consumers want:

  • accurate, actionable content
  • consistent look and feel (branding)
  • just enough and just in time content

Product knowledge triangle

The next general session I attended was after lunch. It was delivered by Hannan Saltzman and Lawrence Orin (from Zoomin software). Lawrence has only just joined Zoomin and worked for a company that implemented their solution, and presented a compelling case study on that.

My notes from this session:

70-85% of site traffic to most tech companies is looking for product content (not just docs!; includes support, forums), with only about 16% to the main website, and about 1% to sales info.

The product knowledge triangle has three parts: product documentation (writer-generated); knowledge base (KB) articles (field-generated), and forums (user-generated).

Product documentation:

  • often PDFs (e.g. admin, user, installation guides)
  • web Help
  • customers must search for this info, often filtering down by product name, version etc. to find the docs and then having to download individual PDFs to find the one with the info they need

KB/support documentation:

  • includes support, tech notes, and KB articles (usually focusing on a specific task)
  • often kept in a KB database, and accessed by case #
  • typical content includes symptom, cause, solution
  • customer needs to search the KB database separately from the product documentation

Forums (can include chat, talk back):

  • has discussion threads
  • disorganised
  • can be hard to search (especially chats)
  • typically has repeated questions, star responders, and a lot of inconsistency
  • customers have to drill down threads to find answers, even if have a search engine

Implications for enterprises regarding this triangle:

  • each place a customer goes is a separate place/dataset with a separate search function and results
  • lots of findability issues

Case study — Aternity:

  • product monitors performance of devices in a company
  • information is displayed in browser
  • monthly software releases (Agile process)
  • audience is IT/product helpdesk
  • had a help site within the site (used DITA for authoring, 2 tech writers)

Before:

  • portal with a login required to access the documentation/help
  • classic doc set (e.g. PDFs) that had to be downloaded before you could see if they contained the relevant info; if not, download and try the next one
  • had to search by product, then version, then publication
  • basically books on the web (with TOCs, indexes), and NOT search oriented
  • needed to shift paradigm to a search with the main aim of ‘findability’ (used Zoomin software)

After:

  • a single search box for everything
  • no login required
  • can quickly jump to topics
  • task topics, not a book metaphor
  • device agnostic
  • filters on side of results page to narrow down search by product etc. (all products, all versions, live filters, intelligent context-sensitive help, synonyms)

When trying to convince management of the solution, had to deal with the ‘docs are an evil necessity’ mindset so came up with a ‘Why write docs’ proposal that had a business and customer focus. Used a restaurant menu metaphor [which I think was a brilliant strategy!]:

  • make the menu (docs) public, but never the recipes (code)
  • make the menu gorgeous and tempting
  • don’t worry about the restaurant down the road (your competitors) seeing your menu posted outside — let them see how good you are, but not how you work

The aims of making the docs public are to sell, upsell, maintain loyalty, promote the thrill of what’s new, and the thrill of being the best (i.e. technical marketing!)

A typical topic page:

  • had a customer focus/relevance
  • focused on customer tasks
  • used customer jargon
  • first paragraph had the who, when, what, and WHY, followed by an example
  • included as many rich visuals as possible
  • had glossary popups (allowed topic to be pared back to basics)
  • had a place for user feedback
  • placed related KB (‘Support’) and forum (‘Community’) topic links into a side bar on the page

The result was a modern help portal that:

  • was easy — inviting, easy to find, open, easy to view
  • had a clear aim — external/potential customers (no login required), to sell and upsell the product, loyalty
  • had a customer focus — tasks, examples, rich graphics
  • was exposed — many more hits, easy to publish, search tracking, tweaked synonyms as a result of search tracking, track feedback
  • had unexpected effects/consequences — customers used the product properly (reduced level 1 support calls; nature of support shifted (questions changed — basic questions almost disappeared, and questions became more sophisticated; tracking allowed benefits to be quantified and raised the profile of the doc team — people stopped thinking of docs as a necessary evil; like support, the nature of training shifted (no more 101 courses needed); prospects/pre-sales were going to the help to find out what the product did; interest in the product increased; other business units wanted to join in.

Before, the web help pages would get 500 to 100 hits per month; after — ~25,000 hits per month. User tracking showed that customers typically spent 4 minutes viewing an article. 45% were ‘hit and run’ users (quick in and out grab of information they needed), while 55% were ‘hit and browse’.

Tracking the top search terms helped them define more synonyms (e.g. ‘db’ for ‘database’), and was used for developing documentation relevant to those search terms. Tracking search errors was also important — as a result they either created more documentation that addressed the missing info, or added synonyms to route users to the correct place. Tracking feedback wasn’t really about where the docs needed work — customers would use it to talk about the product, suggest changes to it, talk about issues they were having with it — the doc team passed these on the support people.

The impact of the ‘modern help’ was immense, in ways unforeseen when they started. The documentation is now the public side of R&D (having it behind a login defeated that purpose). The main takeaways of the project were:

  • know where your customers are looking for answers
  • ensure content is available from all touchpoints
  • prevent info overload by using filters, related articles, glossary popups
  • think content monetisation (how will making content available drive sales, reduce costs)