Concepts
Audience definition
A way of describing your documentation's users.
From Splunk's The Product is Docs:
Audience definitions are not personas:
a persona is a concrete characterization, rather than a well-defined audience type.
The benefits of audience definitions:
Technical writers craft connections between an audience and a product. To build these connections, you need to identify your users as clearly as possible. You also need to identify your users’ goals: the problems that they want to solve, the decisions that they need to make, or the things that they want to build. Equipped with this audience awareness, you can write more accessible, well-situated, and supportive documentation. You can also help create more satisfied customers.
Brand codes
The sensual identifiers of a brand. Codes can be:
- Characters (for example, Tony the Tiger)
- Celebrities (for example, Clooney with Nespresso)
- Packaging
- Visual style
- Colour
- Font
- Slogan
- Logo
- Sonic brand cues
- Scent
Docs like code
Also called docs as code. The practice of treating documentation developement the same way as code development. This includes using the same tooling and processes as your development and devops teams: version control, PR-based review process, automated deployments, and so on.
Book by Anne Gentle: Docs Like Code.
Article I wrote for KnowledgeOwl's blog: Docs as Code: An introduction for beginners
Write the Docs resource collection: Software documentation guide | Docs as Code
Linting
Linting in code means checking source code for problems: everything from enforcing a preference for tabs over whitespace consistently, to checking for more serious programmatic errors. Linting in docs is pretty much the same thing: check for adherence to style guidance, writing quality, spelling, grammar, and so on.
Tool: Vale
(The) long and the short
A way of splitting marketing activities. 'Short' is short term (sales activation), while 'long' is long term (brand building).
The Short of It is a very short video by Les Binet that explains the concepts and is well worth a watch.
Positioning statement
A few sentences briefly setting out:
- To: target name and portrait
- What: the thing you want to position (could be company/brand/product)
- Versus: the alternatives
- Is: what you're trying to say about the company/brand/product to the target
Qual
Qualitative data. For example, user interviews, session recordings.
Quant
Quantitative data. This is any data that comes as hard numbers. For example, "32% of new customers surveyed this year mentioned docs as a purchasing factor."
Relative differentiation
Classic differentiation relies on unique selling points, and tries to create a clear difference between products, on some product aspect that matters to buyers. However, there are two problems:
- There's nothing truly unique about your brand.
- You can't own an attribute. For example, you can't own "open source" or "secure" or "fast".
The solution: relative differentiation. Not a unique difference, just something you have more of than your competitors. For example, instead of claiming to provide the best website-building tool (in the world), show how you provide the best low-code website-building tool for small to medium enterprise projects.
Targeting
The process of identifying and selecting the market segments you want to pursue.
Your Product Needs Words