People communicate best via dialog. It makes sense that documentation should be in dialog form.
Some of the greatest tech books out there are the sort where you learn about the system by building an actual example in the first few chapters. Then you explore various implications of changes for customization, security, and performance in the later chapters. A great example of dialog based books that do this well is Pragmatic Rails Book.
In a time when marketers are struggling to find ways to get people to pay attention for a few seconds, it seems to me that creating outstanding documentation materials might be a far better use of the budget than spending it on marketing.
The best way to make a sale is by having systems, products, services … whatever that is so good that people feel like they need to tell their friends. Users that love your system need documents that show them through real examples how to use it well.
Besides reading a story is much more interesting than a glorified API.
]]>