There are a lot of variations in methods and terminology based on which technology does what, and it has evolved a lot. We talk about online help, context-sensitive help, contextualised help, targeted help, onboarding help, and many others. Some of the definitions are...

Part of the evolution to Documentation 4.0 so that information around software caters for the proper needs is designing a journey from the outset. Part of that journey is the road from development to content and cycling back to ensure that both improve each other. An...

What is personas all about? A persona is a representation of a type of customer. Personas answer the question, “Who are we designing for?” and they help to align strategy and goals to specific user groups. You can begin by compiling everything you know about...

At TECH’advantage we are software editors in the oil and gas industry. When we talk about doc in this article we mean user-oriented documentation. This article is based on our experience over several decades are orientations driven in conjunction with our clients as...

Technical writing must be clear, consistent and concise. The approach we prefer is minimalistic. It’s not new, but it is more and more important in today’s world of over saturation in information. Literary minimalism Literary minimalism is characterized by an...

One of the hardest goals to achieve within a documentation team is to standardize writing styles. In most cases, information models, style guides and editorial styles are used to structure and guide the editorial writing process. But these editorial best practices are...

Yes. We're not the only ones who believe in this, have a look... Translating User Stories into Task-Oriented Topics In an Agile environment, development is driven by user stories, which define the tasks that end-users want to accomplish with the software. User...

As early as possible would be the ideal answer. It’s been said for decades and ignored for as long. If you have and editorial plan that is compatible with a product plan, then both the product and its documentation can be written in the same rhythm and probably even...

Most software should nowadays be easy to apprehend for an IT-literate community. We can hope that this becomes true for new software, but a lot of software is vintage. Training should be reduced to how the software handles specific procedural approaches if it varies...

Internal documentation is written by developers in or around the source code. You can cut your documentation time if you build your User Documentation at the same time you write the Internal or System Documentation. But no one believes it or wants to hear it....

The approach we advise to writing documentation is based on using the DITA norm as an information model. DITA (Darwin information typing architecture) DITA includes three specialized topic types: Task, Concept, and Reference. Each of these three topic types is a...

Success!

Andy McDonald

Product manager

Trained as a social psychologist, Andy McDonald has been designing and writing documentation for the oil industry since 1998. He is the Documentation Products manager for Tech Advantage in the Paris area. -Learn More