Top Nav vs. Tripane (based on a discussion with my mentor DF)

Topic-based writing: tripane or top-nav for documenting software

One of the topics that I am currently interested in is topic-based writing. My company has just adapted MadCap Flare as the main authoring tool, and we have chosen top-nav paradigm as the deliverable hosted on the password-protected website.

During our last mentoring meeting, David and I attempted to discuss the whole notion of topic-based writing, starting with a small discussion around the purpose of writing and the type of audience to consider.

David believes, and I agree with him, that the layout of the output as well as writing approach doesn’t solely depend on the latest writing fashion or your preference, you need to consider your target audience, and what you want to document.

Is your audience used to printed manuals? Are these end users, or engineers which will probably depend on a good search functionality rather than structured content?

What do you want to document? Is it software per se: how it looks like, and how to navigate within the UI, or do you want to describe the tasks you can perform using the software as the tool?

Tasks are easier to describe with top-nav, each task being a separate searchable topic. However, I find it challenging to describe UI using topic-based approach. This is why for the UI parts, I create one topic that serves as an introduction to the UI, and lists all main parts/sections of the software, providing links to the relevant topics describing them in more details. That way, I am sure that all topics are easy to find, as you can either search for them using the built-in search field, or view the list of software sections and choose the one you are interested in.

Pros and Cons of Tripane

Tripane is considered old-fashioned. However, it may be a good transitioning media for the audience that is used to printed output; it has a TOC pane that organises the content. That way the reader is always aware of where they are and how they got there. It imposes clear structure and does not include any distracting fancy design that sometimes gets in a way of obtaining information you are after. It depends on the tool used to create the tripane, but most of them have pretty decent search optimisation functionality, so it is easy to forage for information, if the reader doesn’t want to go through more traditional approach, i.e. reading the TOC.

Top-nav imposes a real web experience – the reader is usually supposed to make search against the information they want to obtain; it puts the reader right in the middle of the content, and by doing so also out of context, making it is easy to get lost. A reader needs to be a proficient web user to know how to forage for information within the top-nav system. Thy need to know how to make search in the most effective way to be able to extract exactly what they came for. One way to cater for this is to write a meta topic on how to search for information, so even the most inexperienced readers can learn how to do it effectively. It is also very important to provide additional introductory information, to minimise the feeling of being lost. I find this the most challenging part of topic-based writing, as you need to very precise and clear using as little words as possible, making sure the reader won’t skip this part.

Every writing style has its pros and cons. The most important thing to keep in mind is to know your audience expectations, and if you as a writer don’t have this luxury, cater for many different scenarios using the tools you were given. I think, my documentation team is on the good path, trying to cater for people accustomed to traditional top-down writing approach that incorporates TOCs, and people who come to the website just to search for one particular piece of information, and don’t want to waste time on looking through indexes or navigation tips. Having said that, I do recognise the long path before us to learn how to use metadata more proficient to get the best of each approach.

Posted in Uncategorized | Leave a comment

General After-UA-Europe-conference Thoughts

Conference content this year was a very broad, focusing on soft skills, theoretical aspects of documentation, documentation administration and also how to style your CSS and adapt your content for multiple media, talks that personally I enjoyed the most.

Below, I will try to describe and discuss 3 talks that I enjoyed most.

Practical Information Architecture: Building Templates For Better Content by Kelly O’Brien

Although a bit too high-level and without any solid examples, Kelly’s talk on information architecture was well-worded and it was a treat to listen to her explaining the importance of a well-structured  documentation.

As compelling as it sounds, unfortunately the challenge is that rarely a company will burn resources and funds to design IA first and content later. It is often the other way round, and it’s typically the template being adapted to the content. I am speaking from the perspective of an author hired by a fast-paced Agile software company whose main objective is to feed information to the field engineers (technical reference, UI overview) and end-users like sales and marketing people (release notes) as quick and efficient as possible. We do try to be consistent, but we are far from having a style guide and dedicated templates for each type of content.

I had an impression that Kelly dedicates most of her time to writing style guides and designing templates rather than being focus on the content that she admitted is contributed by many people of many background (engineers, sales, etc.), so I could understand the importance of a “mastermind” who is responsible for unification of the content provided. In a small company like mine, with two technical authors being responsible for the knowledge centre’s content it is not so hard to maintain consistency, hence the lack of a style guide. However, having said that, I would love to see us spending more time on administrative aspect of our work, organising templates, generating a basic style guide and documentation procedure overview.

Best-in-class Embedded UA by Scott DeLoach

This talk was a bit of an anathema to the talk given by Kelly, as it was spiked with examples on how to organise your content to adapt to different types of media (desktop, tablet, mobile).  By the use of simple jQueries, you can cater for different types of media used for reading your content. To be honest, I never took it into consideration, but the fact is that our browser-based content in all probability is rarely read on the 15″ screen, which I personally use for writing and reviewing content. I would imagine a warehouse worker, who needs to review information will use his work tablet, as this nowadays is the standard media used by non-sedentary employees who need something more handy than a laptop. I fully intent to think learn more about CSS and how to develop more responsive content that will automatically adapt to different media based on typical break points.

Zurb Foundation and Other Responsive CSS Frameworks by Matthew Ellison

Matthew Ellison allowed us to look under the hood of his UA Europe website and explained how he implemented Zurb Foundation responsive front-end framework that is free to use. As he explains, ZURB is a a collection of HTML, CSS and Javascript that makes it easier to maintain and design a website. The main idea of ZURB, from what I understand, is allowing a website designer to rework static content so that it can be viewed within various media and a plethora of different screen sizes. I took a look at the ZURB foundation website, and it’s full of friendly tutorials and walk-throughs that makes the whole learning curve ever so easy. I am looking forward to try it out. I don’t see it being used in my company, as Flare offers a really decent automated almost to the last bit (and very adaptive, if you want to change something) front-end solution, so there’s no need to reinvent the wheel, but the tutorials themselves offer a nice refreshed look at JavaScript, HTML and CSS for seamless browser experience.

Teaching by Example: worked examples in the documentation of complex systems by Caroline Loveridge

I have to admit that I went to this workshop not driven by the need, but rather I was lured by the slides. When I was browsing through speakers’ slides, the presentation prepared by Caroline Loveridge struck me as outstanding, just the right amount of information, great examples (duh, the presentation title!) and … yes, nice images. Basically, it appealed to all my senses.

So what is a worked example? It’s a step-by-step instruction on how to solve a certain problem. It is especially crucial if a software you document is complex, and combines various combinations and settings. Good worked example has a clear structure, is prompted by images and informs the reader what the steps lead to. In other words, a worked example defines the “problem”, provides instructions, and explains what happens after the reader accomplished given set of steps.

To my huge surprise, the workshop that I have attended just because I liked the slides, proved to be the most important to me, as I was able to apply my newly gained knowledge to my line of work. I came back to work, and started working on my own set of worked examples that I called, processes to distinguish it from the rest of documentation types I had: setup and configuration instructions, reference materials, etc. My process documentation defines the purpose of the instructions, and provides a generic set of steps (e.g. how to ship an international package) followed by steps closely related to the software (e.g. how to ship an international package using the App developed in-house). The second part contains images of the software. Given instructions cover only a basic idea, but once you complete the task, you may move to “Related Content” and see more complex processes (e.g. how to ship an international shipment but one consisting of multiple packages).

All in all, the conference was a real treat to me, and it was really good to attend it for the second time. Unfortunately, as we’ve learned at the end of the gathering, this was the last UA Europe conference, which makes it even more special to me that I was able to participate.

Posted in Uncategorized | Leave a comment

Couple of thoughts on Agile methodology based on a discussion with my mentor DF

Text written: 16.12.2016

16 December I met with my current mentor to have a discussion around Agile methodology implementation within software development cycle. The aim of the chat was to establish some ground rules for documentation; should it be a process on its own, running parallel to the whole cycle, or should it be fully implemented within said cycle?

The most important aspect of Agile workflow according to David is its flexibility. In other words, you should feel free to experiment with the approaches and ideas, and then if it works for you, it means that it is a good workflow. The key is to remember that being rigid with Agile structure contradicts the whole notion of this methodology.

Following this logic, it is my understanding that Agile should be adapted to the company, and what is even more important, to the team – not the management. The task of management is to understand the “MO” of the team, let them help choose the tasks, and then, factoring all these in, make a coherent plan and prioritise the tasks.

How does the documentation writing process fit into this? It is the technical author’s responsibility to interact with the development team, and become part of the team. We cannot expect developers to know documentation impact a feature implementation will bear. They will have an idea, but it is the author’s responsibility to communicate clearly the scope and the timeframe. According to David, our role is to be pragmatic, and to manage expectations. Just as we need to understand the feature, development also needs to understand documentation impact of that feature.

One of David’s suggestions is to use scrum as the means of asking questions and interacting with the team. I don’t usually ask questions during the scrum. I use scrum to communicate potential problems with the feature I might encounter while testing . I do it ad hoc, because it might prove to be consequential to the feature concept, or it might be a bug. If I don’t have a proper feature demo, what I usually do is to document the feature as I see it, and write the list of questions that come to my mind, as I write and test it. I expect to have my doubts answered as part of a technical review. I usually write an email with the list of questions, and attach a Word document in which I additionally leave the comments that indicate the particular section in the manual or particular feature description that I found problematic. This approach works fine for most developers. However, some of them prefer talking about the feature, in which case what I would do is to divide the review into two parts. Part one, I would learn about the feature by listening to the presentation, or participating in the demo. Then, I would bring the document up on the projector, and go through the trickiest parts with the developer.

All in all, the better the user story is written, the lesser interaction between the developer and the technical author is needed. This is something both David and I agreed on wholeheartedly. A good user story is usually a good ground work for documentation preparation. It can even help an author create a good skeleton, based on the user acceptance criteria and the feature description.

To sum up, the whole discussion proved the point that Agile is all about communication between all members of the team, including documentation team.

TOPICS TO CONSIDER: documentation support and how we handle it outside Agile workflow (Kanban board), is there a value in bringing it into the cycle?

Posted in Uncategorized | Leave a comment

My thoughts after MadCap Flare Basic/Intermediate Training

Text written: 25.06.2016

June 21-24, 2016, I attended an interactive online training course with Mathew Ellison taking us through basic and more advanced features of MadCap Flare. This is an on-going learning curve for now for me. We have implemented, in my company, MadCap Flare software to produce html and PDF outputs. As we have 3 different software (branded for different customer), we have decided to host 3 documentation sites. The idea is to try single-sourcing as much as possible using Flare projects that for now are stored in Dropbox to maintain basic version control. We are planning on using conditional tags to mark the three target channels. Due to the lack of resources and strict deadlines, we haven’t implemented snippets yet; however, we are planning to use this feature retrospectively; this would involve two main exercises: identifying all areas in documentation that could be converted into snippets, and then a gradual task of converting them into ones. I think we are doing well with the time constrains we have; however, I do sometimes have a feeling we are rushing too much with the content, forgetting about all administrative tasks (glossary, styles catalogue, procedures overview, etc.) which will affect us in the future.

Posted in Uncategorized | Leave a comment

Tech writers vs Devs ratio

Text written: 27.07.2016

Cherryleaf revisits the post from 2003 on ‘standard’ ratios between developers and Technical Authors. Did anything change from 2003? Is the ratio still valid?

What they suggest as an optimal solution is a ratio of 17.6% , or roughly one in six (1:6) technical communicators to programmers. This is taking into account automatization of certain document types, like API docs.

I tend to agree with that. Right now we have 2 technical authors and 12 active developers, and the workflow has never been better. Apart from producing meaningful output, you need to take into consideration time you spend on preparing your tools (layout arrangement, output configuration, etc.), researching new technologies, administrative tasks and doc maintenance (version control, peer reviews, etc.)

I would maybe stretch the ratio a bit, I think it would still be perfectly manageable with more developers onboard without a huge impact on documentation quality.

Having said that, I have not taken in consideration procedural documentation that we stopped maintaining due to other more pressing priorities (2-3 week sprints with a product patch release at the end of each sprint).

Posted in Uncategorized | Leave a comment

Non-native English in technical communication

Text written: 1.05.2016 as a speech proposal for TCUK conference. The proposal was rejected.

Is it possible for a non-native technical author to write coherent and clear documentation? How does second language influence writing?

Short overview of the proposed speech:

  1. Intro
  2. What is second language and SLA? How I learned English
  3. How does it influence my writing?
  • Daily struggles and pitfalls (over-correcting, too much time spent on grammar discourse)
  • Is it all that bad? (high grammar awareness makes it easier to edit a document in terms of: Okham’s razor, jargon, figurative and poetic lg (metaphors, similes, connotations, etc.)
  1. Summary (as usual, there are pros and cons)


Technical Authors do not write for writing sake, their writing is not so much about beautifully structured breath-taking narrative, as it is about dry, informative and very precise message dressed in as little words as possible. Such writing improves the chances of a reader not being left all confused and overwhelmed. This also means that in 90% of readers will actually read the sentence till its full stop.

What defines good documentation? It is fairly simple: it needs to be concise, clear and easy to read. That is to say, a reader can extract information that is useful to them, does not have to think twice what a particular sentence/phrase/word means, and can put the acquired information to some practical use. Basically, good documentation is “reading with understanding” taken to the next level of simplicity.

In a dangerous world of crystal-clear precision, Ockham’s razor and procedure flow charts, is it possible for a non-native technical author to survive? Is it a curse or a blessing?

To answer these questions, I would like to look into the difference between hermetic language, acquired without a cultural context, and the one acquired naturally and based on a set of stimuli received from the surrounding environment.

Which aspects of bilingualism contributes to writing in CNL (controlled natural language)? Here I would like to list some pros and cons focusing on daily struggles but also small victories. The biggest advantage is, undoubtedly, linguistic precision stemming from the ability to convey a message using language not tainted with jargon nor any linguistic shortcuts imposed by the culture. However, at the same time, the biggest disadvantage is the fact that very often a non-native techy author is the biggest critic of their own work, undermining themselves and their linguistic capabilities. How can one overcome their “grammarphobia”? In this line of work, is it really such a bad thing?

Posted in Uncategorized | Leave a comment

Traps and benefits of Agile workflow. How Agile influences documentation process

Text written: 22.02.2015

Agile workflow especially when applied to software development is a real game-changer on today’s market, allowing for shorter development time and more adaptive approach to feature planning and support. Agile benefits both parties involved in the process: the development team and the customer, who is usually actively involved.

We all know agile is good for business, but is it good for technical authors?

Flexibility of Agile allows documentation to be involved in any stage a writer feels it is beneficiary. The more writers are on a team, the easier it is to be involved from the very first steps of the cycle, i.e. planning.

However, if a documentation team is small, attending all possible meetings (sprint planning, feature demos, stand-ups, etc.) can be quite laborious and take up most of the writing time. When it is physically impossible to attend all the meetings, it is crucial to select only the ones that are most informative from documentation point of view.

Planning allows writers to get their priories straight, learn which features are particularly important for the customer, and even be able to jot down customer’s initial doubts and questions, so that they know which aspects of the feature are confusing for the end-users.

As appealing as it sounds, this freedom bears some traps a writer can fall in. It is all too easy to get side-tracked with minor features which potentially can be abandoned or changed for the sake of the bigger picture.

Posted in Uncategorized | Leave a comment