These guidelines describe the basic contents of product documentation, applicable both to small parts and large products.
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:
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:
articles ├── guide Get Started ├── flow Flow ├── fusion Fusion ├── ds Design System ├── ce Collaboration Engine └── tools ├── designer Vaadin Designer ├── mpr Multiplatform Runtime └── testbench Vaadin TestBench
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.
PDF Edition PlannedVaadin Docs is now only compiled for the website. A PDF edition, which could also be printed as a book, is planned. PDF edition may bring extra requirements for the document structure, file naming, IDs, and cross-references.
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.
some-section ├── 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.
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.
--- title: Title of the article order: 4 layout: page ---
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 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.
The layout can be either
tabbed-page. In a tabbed page, the sub-articles are displayed in tabs rather than in the menu. The default tab content comes from the
Sets the tab title in
tabbed-pagepages. It should be short.
Some articles may need to have author displayed. Authors can mark themselves after the section title with:
[.author] [name]#Marko Grönroos# <email@example.com>
For section, this should be in the overview.
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# <firstname.lastname@example.org> The Fine Feature is a feature of a feature... [[thechapter.thefeature.basic-use]] == Basic Use ...
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:
A value proposition is one sentence or a short paragraph (2 to 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>.
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.
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.
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
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.
Thing thing = new Thing("This is a Thing"); thing.setConfiguration("Diidaa"); layout.addComponent(thing);
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
Methods of user interaction with the feature
Inheritance and (re)implementation
Common use patterns