You are viewing documentation for Vaadin Framework 8 and related products View documentation for Vaadin Framework 7 ›
Content Guidelines for Vaadin Documentation · Vaadin
Contributing - Content Guidelines for Vaadin Documentation
 Edit This Page

Content Guidelines for Vaadin Documentation

Introduction

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:

  1. Introduction

  2. Getting Started

  3. Basic use

  4. Features, components, and sub-components

  5. 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.

File Organization

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
---
title

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

Order number in the menu. If sections are reorganized, all the order numbers must also be reorganized.

layout

The layout should always be page.

Author

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&ouml;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.

Summary

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&ouml;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 <chapter>-overview.asciidoc. The ID of the section must be <chapter>.overview.

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.

Value Proposition

A value proposition is one sentence or a short paragraph (2-5 sentences) describing:

  • What the product is

  • For whom

  • 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>.

For example:

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.

Illustration

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.

toolchain lo
Figure 1. 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 original-drawings sub-folder.

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.

For example:

  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.

Features

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 (optional)

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.

Aspects

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

  • Internationalization

The aspects are described in more detail in the Vaadin API Documentation Guidelines PDF.