Content Guidelines for Vaadin Documentation

This article describes the general structure of product or feature documentation. It gives a typical outline, give some examples, which you can use as templates, and list of aspects which you can consider for documenting product features.

Perhaps the most challenging task for a writer is to think what to write. Even when you know the product itself in detail, documentation is more than merely describing it. A reader first wants to see if the product is even useful for his or her purposes, so describing the purpose and various uses of the product is the most important task, and should be right in the beginning.

And so forth. The following kind of structure is recommended:

Introduction
Getting Started
Basic use
Features, components, and sub-components
Special use cases

The same structure can be used in large scale, for the entire documentation, but it should be applicable to smaller units in a self-similar manner. Just as a book requires an introduction or overview, so does a chapter, section, and a sub-section. At the smallest level, it can be a paragraph or just a sentence.

When starting to write new documentation, you first have to find where to place it and then actually create the new article or section, if necessary.

Vaadin Docs repository has the following basic organization:

Show code

filesystem

Expand code

These form the top-level product menu (except for the general Get Started section). Each product has its own menu with articles and sub-sections (folders).

Each AsciiDoc file compiles to a page in the documentation site. When compiled to PDF or the print edition, it becomes a section in the book.

Sections

A section shows as a folder in the menu. Its source files are contained in a file system folder. The folder must have an index.asciidoc file that defines the section title and menu order.

Show code

filesystem

Expand code

    ├── index.asciidoc             Section index (contains title and order)
    ├── overview.asciidoc          Section overview
    ├── some-article.asciidoc
    ├── another.asciidoc
    └── sub-section                A sub-section (folder)
        ├── index.asciidoc         Sub-section index
        ├── overview.asciidoc      Sub-section overview
        └── some-article.asciidoc

Most sections should have an overview that gives a short introduction to the topic of the section and an overview of the articles or sub-sections.

The index file may also have content, which is displayed if the section item is clicked and expanded. That is the case for tabbed pages, where the content of the default tab comes from the index file.

Menu Header

Every AsciiDoc file to be rendered as a section, a page, or tab must have a header block. It is used for building the menu in the documentation website.

Show code

Expand code

The title to be displayed in the menu. The title should be same as the title in the article, but can be a shortened version to keep the menu more tidy.

order

Order number in the menu. If articles are reorganized, the order numbers may also need to be reorganized. It is a good practice to make them spaced by 10 or 100, so that can add articles without changing the number in other articles.

layout

tab-title

Sets the tab title in tabbed-page pages. It should be short.

Some articles may need to have author displayed. Authors can mark themselves after the section title with:

Show code

Expand code

 [.author]

For section, this should be in the overview.

Note that for non-ASCII letters, you should use HTML character entity markup.

Summary

A basic new section file would be as follows:

Show code

Expand code

An introduction or overview is the most important part of any documentation. It gives the reasons to use the product: why would you want to use it? It can elaborate on this question, by considering major use cases.

Every section and sub-section should also have an introduction. In small sections, it can be just a single paragraph. It should come after the section title, and not as a separate sub-section.

An introduction or overview should contain the following:

Value Proposition

A is one sentence or a short paragraph (2 to 5 sentences) describing:

What the product is
For whom
For what purpose
- Purpose with regards to usability, documentation, efficiency, etc.

The basic pattern is:

Vaadin <Thing> is a <category> for <an important purpose>.

For example:

Text Field is one of the most commonly used user interface components. It is a Field component that allows entering and editing textual values using the keyboard. You can parse the user input flexibly and format the visible text.

An illustration gives a visual overview of the product. It can either be a screenshot or a diagram. Illustrations should have a short caption that describes the content.

The development toolchain is illustrated in Development Toolchain and Process.

Development Toolchain and Process

The ID of a figure should be dot-separated according to the ID structure of the section and be unique. The ID should be prefixed with “figure.” to distinguish it from other IDs.

Figures can be referenced from text, although it is not necessary for the first image in the overview.

Show code

Expand code

  The development toolchain is illustrated in <<figure.mychapter.mysection.toolchain>>.
  [[figure.mychapter.mysection.toolchain]]
  .Development Toolchain and Process
  image::img/toolchain-lo.png[]

Illustrations should be stored in a images sub-folder under the section folder. Sources for diagrams should be in an drawings sub-folder.

Tasks and Basic Example

A basic example should cover a typical use case with minimal number of lines. Such an example can be introduced with a brief description of the tasks involved.

You create a Thing by giving it a description. Before adding it to a layout, you need to configure it.

For example:

Show code

Java

Expand code

Features

Give a compact list of the most essential features, between around 4 to 10. In chapter overviews for major products, the list can be a bullet-point list, but if it is smaller section, a paragraph or two is better.

Thing can have an input prompt and it supports clearing the input programmatically. You can listen for text changes while they are being typed, not just when the user submits the form.

You should deal with each feature so introduced in more depth later in the text.

Limitations are almost as important as the features; readers are accustomed to making trade-offs and even expect that, so it is good to help them with it. By acknowledging the limitations, you also state that you are aware of them, care about the reader, and do your best to remove them in the future.

Thing allows editing a single line of plain text. For multi-line editing, you can use Text Area, and to allow editing formatted text, you can use RichTextArea.

The following is a list of typical topics that you can cover:

How does it do it (if implementation is relevant)
Complexity and performance
Meaning of the terminology
Appearance in the user interface
Design alternatives
Use cases
Methods of user interaction with the feature
Related features
Inheritance and (re)implementation
Styling
Security
Common use patterns