On documentation and marketing

I’m currently in the process of unifying the documentation of nexiles gateway – this is part of the ongoing effort to get marketing for nexiles gateway started.

Why is documentation so important when we talk marketing? Does it not suffice to have a nice and shiny landing page featuring a big “buy” button?

I believe it’s all about the target audience and the market, and the type of customers. For nexiles gateway, who are the possible customers? I think that these are mainly technical persons. Developers, Administatrors, Dev-Op people.

Those people need to understand and evaluate any new tool they want to use. For them, the shiny landing page is a jump size to more detailed documentation. Most technical people gauge the quality of a solution by the quality of the documentation.

Writing good technical documentation is a huge effort – often this is a separate position called Technical Writer or similar. Luckily, there are good examples, tools and guidelines.

One of the guidelines is Diátaxis:

Diátaxis is an approach to quality in technical documentation. It describes an information architecture that emerges from a systematic approach to understanding the needs of documentation users.

Diátaxis identifies four modes of documentation - tutorials, how-to guides, technical reference and explanation. It derives its structure from the relationship between them.

In Diátaxis, each of these modes (or types) corresponds to a different user need. Each fulfils a different purpose and requires a different approach to its creation.

And JetBrains recently published a EAP of WriterSide – a IDE for Technical Writers, which also can be used as a plug-in for other IntelliJ IDE. it appears that they follow the style of diatraxis.

Some initial experiments look promising – we’ll see how it goes.