Documentation Center

Modular writing best practices

With Draft Space, you write your content inside topics, that makes it optimized for reuse. That modular way of writing requires some change of habits compared to classical writing.

Perfecting modular writing may take a lot of practice. However, following a small set of basic rules can help you contribute to the document without creating extra work for the authors.

Overview

Dividing content into single-purpose topics makes it easy to reuse and re-organize it:
  • The topics can be included in many different documents and can also be duplicated in a single document.
  • You update a topic once, regardless of in how many places the topic is used.
  • Many authors and contributors can work in parallel on content without having to bother about how it will be organized.

Those benefits can be achieved only if the content is written in a way that makes it independent from any changes in structure and sequence.

Single-purpose

Write a topic for only one thing. If it appears that you need to describe several things, do not hesitate: create several topics. These topics can then be listed under a parent topic that acts as chapter head.

Appropriate title and short description

The readers first see the title and a few words of the beginning of a topic, then choose whether or not they want to select the link and see the entire topic content. Therefore, title and first paragraph should help that decision.

The title should covers all the topic and only the topic (which is of course easier if you create single-purpose topics).

The short description (shortdesc) provides the first paragraph of a topic, and we recommend you always create one. The short description is often displayed in an infotip when the reader hover over the title, thus helping the reader finding out if the topic is worth reading. It doesn't summarize the content, it introduces it. We recommend you also try to keep the short description's length under 300 characters.

Independent

Topics can be moved around in a document. Some may be added, some removed, and some reordered. Therefore it is essential that, in the content, you make no reference to what comes before and after. Ideally, a topic should be written as if there was nothing else around it. The topic is in fact usually displayed on its own.