Blog Archives

Documentation that developers need to do their jobs

A fellow technical writer asked me this week about the documentation that developers need to do their jobs. He was thinking not of the guides people need when they want to integrate their systems with another organisation’s systems, but rather the internal guides developers may write for themselves about their projects and tools.

That’s a very good question. I’ve thought about it over the last couple of days, and pulled together a list of the types of developer-focused documentation I’ve come across. If you have any to add, please do!

The list is confined to documents relating to the role of software engineer/developer. It doesn’t include more general information that all employees need, such as human resources and facilities.

Information about the project and system they’re working on

  • Who the people are: engineering team members, product managers, technical writers, stakeholders.
  • Customers: Who they are and what they do, or would like to do, with the system or application that the team is developing.
  • Goals: Mission, vision, goals for the upcoming month/quarter/year.
  • Product requirements document for the system, application, or major feature that they’re working on.
  • Design documents.
  • Architectural overview, preferably in the form of a diagram.
  • Comments in the code, written by their fellow developers.

Help with their development environment

  • How to set  up the development environment for the application/system that the team is developing.
  • Guides to specific tools, whether built in-house or third party, including the IDE of choice, build tool, source repository.
  • A pointer to the issue tracker used by the team.
  • Guide to the team’s code review tool and procedures.
  • Best practices for writing automated tests, and information about existing code coverage.
  • Links to the team’s online chat room, useful email groups, and other communication tools used by the team.
  • Where to go with technical and tooling problems.

Coding guides

  • Coding style guides for each programming language in use.
  • Guidelines for in-code comments: style; where to put them; how long they should be; the difference between simple comments and those that are intended for automated doc generation such as Javadoc; and encouragement that comments in the code are a Good Thing.
  • Best practices for code readability.

Sundry useful guides

  • Communication guidelines, if the developer’s role will involve significant liaison with third-party developers, customers, or important stakeholders.
  • A map to the nearest coffee machine, preferably reinforced by a path of glowing floor lights.

Too much information can be a bad thing. :) I spotted this sign on a recent trip to Arizona:

Too Much Information

Tech Comm on a Map now includes businesses and groups

A month ago I announced my project called “Tech Comm on a Map”. The idea is to help us see what’s happening in the world of technical communication around the globeTech Comm on a Map puts tech comm titbits onto an interactive map, together with the data and functionality provided by Google Maps.

When first announced, the map included data types for conferences, societies, and a grab-bag called “other“, which currently contains a couple of historically-interesting morsels.

Now I’ve added two more data types:

  • businesses for commercial organisations specialising in tech comm, such as consultancies, recruiters, publishers, independent technical writers, and so on.
  • groups for smaller groups and regular meetups of technical communicators, either as part of a larger society/association, or as an independent group.

Any groups or businesses to add?

At this point there are very few businesses and groups on the map. Do you have one you’d like me to add? Please add a comment to this post, including the following information for each item. The information will be publicly available on the map, via an information box that appears when someone clicks on the relevant circle on the map:

  • Type: Conference, Society, Business, or Group
  • Name of the business, group, society or conference.
  • Description.
  • Website address (or an email address that people can use to get more information).
  • Street address (this is essential, to position the item on the map).
  • Start and end date for conferences, or meetup timing for groups (e.g. “First Wednesday of every month at lunch time”, or “Every Tuesday at 7pm”).

Note: Don’t add the names or addresses of any individuals, unless it’s your own name and address. We need to ensure we have people’s permission before adding their information in a comment on this post, or on the map. Any information you add here should be already publicly available on an organisation’s website or other publication.

Contributors to the project

Thanks to the following people who have helped me add data to the map so far: Sarah O’Keefe, Ellis Pratt, Stefan Eike.

Thanks also to Stefan Eike and Stephen Farrar, who have both contributed to the code on GitHub.

More coming

Excited? I am. :) If you’d like to know more about the project, check out the introductory blog post. Soon I’ll write another post with the technical details of the APIs and other tools involved. In the meantime, here’s Tech Comm on a Map.

The Making of “The Language of Content Strategy” (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

The Language of Content Strategy is a book by Scott Abel and Rahel Anne BailieIn this session at STC Summit 2014, Scott Abel discussed the content strategy, tools and technologies behind the making of the book.

Problem statement

Time, money, skills and experience are in short supply. Hand-crafting content is expensive, time consuming and not scalable.

The demands of the audience are changing. People use social media, rather than going to a specific website to gather information.

To meet the demands of content delivery today, we need to adopt manufacturing principles. The is made possible by content engineering: The application of engineering discipline to the design and delivery of content.

Case study: The making of  The Language of Content Strategy

In this session, Scott will show us how he and Rahel created a book, an eBook, a website, and a set of learning materials, from a single source, without breaking the bank. They did it by harnessing technology and crowd sourcing.

Scott talked about the differences in approach between technologists and editorialists. Conflict and time wasting arise because of a lack of a common language. Rahel and Scott wanted to craft a solution: A crowd-sourced book about content strategy that is both a case study in content engineering and a practical example of content marketing.

Setting up

The team started with careful analysis of the educational landscape, contributors, and more. Then they defined the content types they needed.

  • The smallest unit of content they would create would be a term and definition pair.
  • Another content type is an essay of 250 words.
  • Then there are contributor bios, statements of importance, and resources.

For the authoring environment, the team selected Atlassian Confluence. It’s a wiki with support for XML content re-use.

They also chose a gimmick: 52. The project included 52 terms, 52 definitions, by 52 experts, published over 52 weeks, and one of the output formats was 52 cards.

Then they selected a team of experts: the best and brightest in tangentially-related fields.

Other roles and responsibilities: markup specialist, editor, indexer, peer reviewers, and a graphic artist.

The source data

The source was authored in Confluence wiki. The content types are clearly labelled: Biography, importance statement, topic name, definition, etc.

The output

In the various output formats, the content is structured differently but still consists of the various topic types. For example, in the printed book every chapter is two pages long, and consistently structured. The eBook format is slightly different, as are the website format and the flash cards learning format.

Each Thursday, one chapter is automatically published. The web output also contains audio files, photos, and additional resources that are not contained in the book.

The advantages of a future-proofed content strategy

The team was able to add content after the fact, such as the audio files for accessibility. The content strategy was designed to future proof the content, so the team was able to adjust to challenges and opportunities. And the strategy is repeatable. Now that it’s been done, it can be done again.

Scott told an amusing story of how he disobeyed his own rules, and tried to create another channel by copying and pasting instead of using the single-sourced content. A marketing person asked him to create a slide deck from the content. He was on a plane, without WiFi, so decided to do it by cutting and pasting. Needless to say, this didn’t work. By the end of the flight he had only 13 slides of the required 52, and had run out of laptop battery!

Cost

The cost of the project came in at under $10,000USD.

  • Approximately $4000USD forgraphic design, indexing, editing, markup assistance, audio tracks and hosting, the URL for the first year, and site hosting for a year.
  • Approximately $5,440 for book donations, postage, Adobe InDesign, Confluence Wiki, and overhead/administrative costs.

Scott’s promise

Scott finished by saying that if you want to undertake a similar project, ask him. He will try to help.

This was a fun and inspiring talk. Thanks Scott!

Information Architecture Bottom Up (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

Mark Baker, author of the book Every Page is Page One, presented a session on Information Architecture Bottom Up. The outline of his talk ends with this summary:

This session will look a practical examples of top-down and bottom-up information architecture and will illustrate where top-down fails, and how to create a bottom-up architecture to replace or to supplement your top-down approach.

Bottom up

Traditionally, information architecture organises knowledge from the top down. As examples, Mark showed us the Map of the System of all Human Knowledge from the Encyclopedia of Diderot & d’Alembert, the Linnaean classification system, and the Dewey Decimal system.

One of the simplest forms is the table of contents. You start with a general concept, and then drill down to the details. Such classifications tend to end with a category of “miscellaneous” items.

Sometimes tables of contents even act as a classification scheme, such as a clickable classification of organisms.

Another form is a system which lets you find out what medical problem you have, by progressively narrowing down your symptoms.

Mark showed us other examples of hierarchical organisation of data. Then he showed how hierarchies don’t necessarily meet a user’s needs. For example, if you’re looking for a convertible car, and the information on a car sales site is organised by year/transmission/price… and eventually by body type, you’ll need to move up and down the hierarchy a lot before you find what you want.

We will never find the hierarchy that will suit all users’ needs, because people have different needs.

Faceted classification

Such systems let you choose the things that are important to you. For example, a car sales site may have a set of various selection criteria in a side panel, such as price, transmission, mileage, year. You can choose to fill in some selection criteria and not others, and so find what you need.

There’s a big technological difference here. Paper can’t provide faceted classification, but computers can.

This is still top down. It’s a collection of taxonomies that define the things people are interested in, with respect to buying cars. It works, because most people buying cars know this particular taxonomy. But it won’t help people who don’t know the taxonomy. There are still classification problems.

Experts classify, the rest of us name things

A nice quotation from Mark:

“Experts classify. Everyone else names.”

Looking at flowers, and pansies in particular, the scientific classification of a pansy isn’t particularly useful to most of us. Looking at a Google search for common names of pansies:

  • Searching for “stepmother flower”, you find plenty of information and images for pansies. That’s good. In such cases, a search engine like Google works.
  • Searching for “football flower” shows images of pansies, and also of footballs made of flowers. Some good, some potentially confusing.
  • Searching for “Three faces under a hood” is particularly interesting says Mark. Looking at the images, you see a pansy (good), a girl in a hood, two people under the hood of a car, and a composite photograph showing the three faces of Mt Hood.

Scalability

None of the classification systems scale well. Tables of contents can get immensely long. Mark showed some examples from a book and an online help system.

There’s often too much variety, which leads to complexity and unevenness

Mark quoted David Weinberger: “Everything is miscellaneous”.

Everything flows to the Web

We shouldn’t attempt to push content into channels. Reuse is a big subject, often for the sake of being able to deliver the same content to multiple channels.

Problem, says Mark! There are no channels any more. All content flows to the web.

If people search for something on the Web, they will find the most popular hit – which will probably be your most popular product, even if published a few years ago.

Moving towards bottom up

What happens when someone does a search and ends up on a page in your content? They don’t start at the top. They start on the page that Google sends them to.

Mark isn’t saying we should throw away all the top down architecture. But we do need to start adding bottom up information architecture to our content.

Subject affinity

Looking at Wikipedia: it’s highly organised. There are various links and ways to move around. But it’s not ordered. Organised, yes. Ordered, no. The links point to related information, which provides a type of semantic clustering.

Dynamic semantic clustering

Mark showed us examples of information clusters that are dynamically organised:

  • Twitter hash tags
  • RSS feeds
  • Forums. Sometimes these are organised by number of votes.

Linking interesting connections without making a bowl of spaghetti

Most of the problems that people find are the irregular associations, and multiple connections. If things are regularly organised, people don’t usually have problems. So we need to help people with the irregular associations.

In a bottom up architecture, it’s easy to link to the interesting associations. If you tried to map all these associations from the top down, you’d soon have an incomprehensible bowl of spaghetti. In a bottom up architecture, the links show connections that are relevant in this context.

“A topic in a bottom up architecture is a hub of its local subject space.”

How do you make sure people don’t get lost?

This was a question from the audience. Marks’ answer was that you have to design the content for a bottom up architecture. You can’t just take the content from a top down hierarchy and put it into a bottom up system.

You must build context into the subject matter. Context in the table of contents doesn’t matter, but context within the subject matter does. Every page is page one, so every page must start by establishing the context. “Where am I.”

How can you filter the links based on the reader’s context?

In a tech comm point of view, you must have a systematic design for linking. A taxonomy is vital here. So, a taxonomy is not used for generating a table of contents, but instead for organising your links.

What about procedures and workflows?

What if a sequence must be performed in order? Mark’s answer is that a procedure should be the subject of a single topic. In top down design, a table of contents should not express a workflow, although it often does. So, workflow is one of the most important use cases for a bottom up architecture.

A person from the audience mentioned that you can illustrate workflow via a progress bar or images illustrating steps, which can link to steps in a complex workflow.

Topic types

Due to lively discussion with the audience throughout the presentation we ran out of time a bit, so Mark ran quickly through the types of topics in a bottom up architecture:

  • Workflow topics. We mentioned these above.
  • Pathfinder topics. These are about how you get from a business topic to an action in the system.
  • Big picture topics.
  • Tasks.

Walled garden or bazaar

Mark finished by comparing the top down approach (a walled garden) to the bottom up approach (a bazaar). The main difference: in the pictures Mark showed us, the bazaar had people in it. :)

Thanks Mark

It was a pleasure and a privilege to hear you speak.

Minimalism (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

Barbara Beresford‘s session was entitled “Minimalism—It’s Really About the User!” Here is an extract from Barbara’s summary of her session on Lanyrd:

Minimalism is a widely accepted and influential methodology in technical communications, but it is not a simple method to understand or apply. John M. Carroll’s two books on minimalism: The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skills (1990) and Minimalism Beyond the Nurnberg Funnel (1998), provide the best source for the ideas behind the theory.

Minimalism begins with understanding your users—in particular, how they need to use your software in order to accomplish their specific business goals. Designing content that really addresses this problem is notably more difficult than simply documenting the features of your software. But tackling this problem can help you develop much more usable content!

Introducing minimalism

“Minimalism” – It’s seemingly a simple word, says Barbara, but it’s surprisingly difficult to get your head around it.

Barbara talked about her path to minimalism. She says she has some “special expertise as an impatient user”, which gives her a special insight into minimalism. This got a laugh of recognition from the audience. She also gave us a useful list of influences, including books, articles and methodologies. These include DITA, content strategy, Information Mapping, Every Page is Page One by Mark Baker, and more.

Update on 14 June 2014: The above paragraph previously stated, erroneously: “She also gave us a useful list of references to books, articles and methodologies that have influenced minimalism.” I have now changed it to say, “She also gave us a useful list of influences, including books, articles and methodologies.”

Minimalism is a theory of learning developed by John Carroll at IBM in the 1980s. He used the term the Nurnberg Funnel to describe the way people learn. They’re not passive when learning. They want to drive their learning experience, based on what they already know and what they want to achieve.

His study found that when people are handed a comprehensive set of instructions, only approximately 1 out of 20 follow the instructions from beginning to end. The others jump around, do their own thing, make mistakes, get lost, and have trouble finding their way back. People like to do things their own way.

In response, Carroll decided to design tutorials that start users immediately on meaningful and realistic tasks – things they needed to do. He also wanted to reduce the amount of content, and make errors and error recovery less traumatic.

So instead of comprehensive coverage, he aimed for selective coverage based on the user’s goals.

Barbara used the terms “minimalist design” and “systems design” to compare the two approaches. (At first I was not quite sure why the term “systems design” was used here. But later during the presentation, I think I know: it denotes a manual whose structure is based on the structure of the user interface it’s describing, rather than on user tasks.)

Minimalist design

Marta talked through these points of minimalist design:

  • Brief orientation
  • Prerequisite tasks
  • Learn by doing, start straight away
  • Modular, self-contained topics
  • Support error recognition/recovery

We looked at an example of a legacy document, which was organised to match the menu structure of the user interface. Barbara described how she reorganised the document along minimalist principles. She started by identifying the key user roles (booking officer, investigator, administrator) and their key tasks (create booking records, search for new records, etc). The new guide was then organised on sections based on tasks (use the import queue, create inquiry records, create booking records, etc).

Questions from the audience

At this point, a member of the audience said that the minimalist guide would be more of a quick-start guide, but a comprehensive user manual is still required. Barbara’s answer was that a system-organised reference manual is typically not used very much. Users typically want to find their information within the context of the key business task. If it’s important to explain specific elements of the screen, do it as part of the business task.

A number of related questions arose, which Barbara answered authoritatively and clearly. One audience member made the point that you could start with the minimalist guide and allow people to drill down to the more detailed information. Barbara also said that part of the role of technical writer is to point out what the primary focus is: serving the users’ needs based on usability studies. We don’t need to document everything that other people tell us to document.

Psychology of learning

Barbara related the principles of minimalist design to the psychology of learning, which shows that we are complex, emotional beings, not machines that run scripts. We do things for complex reasons, without necessarily understanding the reasons ourselves. We need to act, even to struggle, in order to learn and to retain information. People may even be too busy learning to spend much time on the instructions.

Developing minimalist documentation

Examine the system you’re documenting, decide where it’s not intuitive to use, and help the user with those areas. Discover the user’s mental model, and find out if it matches how the tasks are carried out in the system. If not, help orient them to the system. Find the common error situations, and help users through them.

Thanks Barbara

I’ve never consciously used minimalist design, although I’ve attended a few talks on it through the years. I feel that some of the principles have rubbed off on me. This talk helped crystallise and solidify the concepts and practise of minimalism for me.

Follow

Get every new post delivered to your Inbox.

Join 1,446 other followers

%d bloggers like this: