Best practices

This project aims to deploy commonly accepted 'best practices' to make the user experiences as good as possible, for both readers and contributors.

As we adopt, develop or change practices we should document and share them so that all contributors can be aware and adopt the same.

For now, note the practices below and also keep an eye on A to Z of style.

One sentence per line

This practice is very helpful for a number of reasons — please read One Sentence Per Line.

Topic-based writing

Done right, this practice is enormously helpful for effective management and delivery of modern publications.

In essence, it means that each Asciidoc page source file in this project should comprise a self-contained 'topic' rather than a monolithic 'chapter' or other traditional book-based construct. The point is that topics are much easier to develop, review and reuse in clever ways that also feel more effective for the reader. Less maintenance, fewer errors, and better usability (especially in digital formats).

This is a whole subject in itself, but for a quick overview of the general ideas see Every Page is Page One.