Content Guidelines for Vaadin Documentation
These guidelines describe the basic contents of product documentation, applicable both to small parts and large products.
In this article, we describe the general structure of product or feature documentation. We present a typical outline, give some examples, which you can use as templates, and list a number 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 user first needs to determine 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 done right in the beginning.
And so forth. In these guidelines, we suggest and describe the following kind of structure:
Features, components, and sub-components
Special use cases
We describe the structure as if you were writing a book or a section of a book, 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 smallest level, it can simply be a paragraph or just a sentence.
Getting Started to Write a New Section
A "Getting Started" section was second on our list, so we go on with that. In this document it means two things: 1) determining where to write the documentation and 2) what is there to do to create a new section.
As explained in "Getting Started: Repositories", documentation content is mainly contained in the respective product repositories. They are collected in the documentation site when it is built.
Product documentation is usually contained in a
documentation folder in the product repository.
There are some exceptions to this, such as in Vaadin Core Elements.
See the list of product repositories and their branches and documentation folders.
For most products, the documentation comprises of one top-level section in the Vaadin Docs site, or a chapter in the Book of Vaadin that is compiled from the documentation site. Vaadin Framework is a large product that is divided further into chapters. Each chapter has a sub-folder in the documentation folder.
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.
For compiling the book, they must be included in a
chapter-<name>.asciidoc file in the documentation or chapter folder.
The name must match the chapter ID in the documentation.
In the framework documentation, it must match the folder of the chapter.
Each section file must have a header block. It is used for building the menu in the documentation website.
--- title: Title of the section order: 4 layout: page ---
The title to be shown in the menu. It should usually be same as the section title, unless there is some need to shorten it.
Order number in the menu. If sections are reorganized, all the order numbers must also be reorganized.
The layout should always be
You are the author and owner of the documentation you write. Each author of a product chapter or section can mark themselves after the section title with:
[.author] [name]#Marko Grönroos# <[email protected]>
For chapters, this should be done in the Overview section.
Note that for non-ASCII letters, you should use HTML character entity markup.
A basic new section file would be as follows:
--- title: Title of the section order: 4 layout: page --- [[thechapter.thefeature]] = Fine Feature [.author] [name]#Marko Grönroos# <[email protected]> The Fine Feature is a feature of a feature... [[thechapter.thefeature.basic-use]] == Basic Use ...
Writing an Introduction
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 briefly, by considering major use cases.
For book chapters (in practice each documentation folder), there must always be
an Overview section.
The section must have file name
The ID of the section must be
Every section and sub-section should also have an introduction. In small sections, it can be just a single paragraph. It should be written after the section title, and not as a separate sub-section.
An introduction or overview should contain the following:
Let us go through them one by one.
A value proposition is one sentence or a short paragraph (2-5 sentences) describing:
What the product is
For what purpose
Purpose with regards to usability, documentation, efficiency, etc.
How it’s better than other products.
Allows integration, privacy, etc.
The basic pattern is:
Vaadin <Thing> is a <category> for <an important purpose>.
TextField 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 with a few words.
The development toolchain is illustrated in Development Toolchain and Process.
The ID of a figure must be dot-separated according to the ID structure of the
section and be unique. The ID must be prefixed with “
figure.” to distinquish
it from other IDs.
Figures should usually be referenced from text, although it is not necessary for the first image in the overview.
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
img sub-folder under the documentation
folder. Sources for diagrams should be kept in an
Tasks and Basic Example
A basic example should cover a very 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.
Thing thing = new Thing("This is a Thing"); thing.setConfiguration("Diidaa"); layout.addComponent(thing);
The result is shown in "Using the Thing".
If the illustration is a basic screenshot, the basic example should produce the screenshot. The screenshot should be referenced verbally in the text.
Give a compact list of the most essential features, between around 4-10. In chapter overviews for major products, the list can be given in bullet-point form, 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 they are written to the data source.
Each feature so introduced should be dealt with 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 will 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 TextArea, 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
Methods of user interaction with the feature
Inheritance and (re)implementation
Common use patterns
The aspects are described in more detail in the Vaadin API Documentation Guidelines PDF.