How to add new documentation

You may want to add a new documentation file, say, if you create a new component or find an existing component that doesn't have docs yet. This page shows the best practice for adding docs in a way that keeps the overall doc structure consistent. Don't worry if you find the guidelines hard to remember or follow. They are not hard and fast rules but just general "pointers" that will help to improve the quality of the docs if you can apply them.

Contents

• TL;DR
• Docs location and format
• README doc index
  • User Guide section
  • Rebuilding the doc index
  • Stoplist for undocumented files
• Best practice for structuring a Markdown file
  • Table of Contents
  • Main sections
  • Basic Usage
  • Methods
  • Details
  • See Also
• General doc content tips

TL;DR

1. Copy docs/boilerplate.component.md or docs/boilerplate.component.md and rename the new file.
2. Edit the file. Have a quick check at the end to make sure you have removed or replaced all the placeholder text (it sounds obvious but it is easy to forget!)
3. Edit docs/seeAlsoGraph.json and run node config/generateSeeAlso.js from ng2-components if you want to add a "See Also" section.
4. Run markdown-toc -i ../docs/my-filename.component.md from the ng2-components directory only if there are more than about 5 subsections in the Details part. You should always do this after you have done step 3 because the See Also script will add an extra section to the file and you want that to appear in the Table of Contents.
5. Run node config\buildFullDocIndex.js from ng2-components to add the new component doc to the index in README.md. Alternatively, just edit README.md directly to replace the existing link to the .ts source file.
6. Commit, push, etc, but be aware that the See Also and indexing scripts sometimes change files that you didn't directly edit yourself.

Docs location and format

Doc files are all located in the docs folder at root level in the repository. The file content is written in GitHub flavored Markdown and the filenames have a ".md" suffix. Note that not all GitHub features are appropriate for docs (strikethrough, task lists and emojis, for example). Also, to keep a consistent look and feel to the docs, you should generally not use inline HTML to create your own formatting.

For components, etc, each Markdown file has the same name as the Typescript source file where the component is defined (so document-list.component.md is the doc file for document-list.component.ts). This is required for our doc toolset. Filenames for docs in the User Guide section should be derived from the doc title but this can be abbreviated if necessary.

README doc index

All the doc files are listed in an index within the README file for the docs folder. The list sections of the file are generated by a script that looks for special HTML marker comments. So the section marked out by:

<!-- ng2-activiti-tasklist start -->
...links to files...
<!-- ng2-activiti-tasklist end -->

...contains links to all the docs for the Tasklist library. Text inside these sections will be replaced whenever the index gets rebuilt by the script but any text outside will be left intact. The list sections also include components that are present in the libraries' src folders but don't have any docs in the docs folder yet (these are prefixed with a * character and the link points to the source file instead of a Markdown file).

If you add a new doc file then you don't necessarily need to rebuild the index. It is fine just to edit the appropriate link in the README file but remember also to remove the * character from the link title. If you do rebuild the index then the script will automatically find the new file you have added, match it with the source file and update the link.

User Guide section

The index lists the files in the User Guide section above the component docs. Unlike component docs, new User Guide pages aren't found automatically by the build script. Add a line in the summary.json file to add a new page to the User Guide the next time the build script is run:

[
    ...
    { "title": "Form Stencils with Angular 2", "file": "stencils.md" },
    ...
]

We use this approach for compatibility with the Compodoc tool, which we use to produce an HTML version of the docs.

Rebuilding the doc index

You need to rebuild the doc index with the script if you add a User Guide page but this is often the "cleanest" and easiest way to update the index for component docs too. Use cd ng2-components to set the working directory and then run:

node config\buildFullDocIndex.js

As mentioned above, the text outside the marker sections in README.md is left intact by the script, so you can edit it directly. You should use this method to add non-component classes to the index as we do in a few isolated cases (eg, FormFieldValidator).

Stoplist for undocumented files

The index also has a "stoplist" that removes components without docs from the undocumented sections in the list. There are many classes in ADF that are not particularly interesting from a user's point of view or that are described in the context of other components. These items are intentionally left without doc files and so we don't want them to appear in the index.

The stoplist is contained in undocStoplist.json in the docs folder and has the following structure:

[
    "model",
    "context-menu-holder",
    "data-column-list",
    "card-view-[a-z]+item",
    ...
]

Each item is a regular expression that is matched against the filenames of undocumented components, services, etc. If the filename matches any of the stoplist items, it will be removed from the doc index. Note that the stoplist only removes undocumented items, so a Markdown file will always be correctly located if it exists. Also, the regular expressions are supplied as ordinary strings. This works fine in most cases but be careful if you need to use backslash escapes in the regular expression itself (you will need to double the backslash in the stoplist string).

Best practice for structuring a Markdown file

The Markdown files are written with a consistent structure. The idea is that a user will gradually become familiar with the structure and so learn how to get to the information they want quickly. Also, the structure can be used by scripts that process the docs.

A good way to get the right structure for a doc file is to start off with either the Boilerplate component file or the Boilerplate service file (which is also useful for models, pipes, etc). These files contain placeholder text in the correct structure for a doc file. Duplicate and rename one of these files or copy/paste the contents into a new file. Then, edit or delete the text as necessary.

All of our doc files start with a level 1 Markdown heading

# Arc Reactor component

For components, services, etc, this title is derived from the filename by expanding and capitalizing the kebab-case.

After the title, User Guide files can be fairly free-form in content but components have a specific structure. In a line under the title line, you should add a short one-sentence description of what the component does:

# Arc Reactor component

Powers the heart implant and armor.

Avoid text like "this is a component that does xxx" or "use this component when you want to..." in the brief description line. Also, something like "allows you to do xxx..." or "enables xxx to happen..." can usually be written more neatly as "does xxx...", "activates xxx...", etc. This is a widely-used convention in API docs; it reads easily and helps keep lists and tables clear:

• Arc Reactor component: Powers the heart implant and armor (<- Looks neat) |
• Arc Reactor component: This is a component that supplies power for the heart implant and armor (<- You get tired of reading this over and over again in a list)

You should put a screenshot under the brief description for components that display something interesting. It is best to focus on just the component itself rather than using a full-screen image, but there may be cases where the whole screen is relevant.

Table of Contents

The last thing in the top section is the Table of Contents (ToC). Most files don't need this but if you have a very long description with more than about 5 subsections in the Details part then you can use it. You should use the command line tool, markdown-toc to generate the ToC rather than adding it by hand. Use cd to get to the ng2-components directory and then run

markdown-toc -i ../docs/my-filename.component.md

For this to work, you need to have a ToC section marked out in the Markdown file with special HTML comments. The boilerplate files have this already in place but you can delete it if you don't need a ToC for your file.

Main sections

After the top part, there are a number of level 2 sections in the document. For components, these are:

• Basic Usage
• Details
• See Also

For services, etc, we have:

• Methods
• Properties (<- often not required)
• Details
• See Also

You should edit the content of these sections but don't add any extra level 2 sections to the file. Also, adding your own level 3 subsections under Details is fine but you should leave the section structure as it is for the rest of the file.

Basic Usage

For components, the Basic Usage section can contain a simple usage template and 2 subsections for the Properties and Events tables. Try to keep the descriptions in the tables as short as possible to prevent the table rows from getting too deep. They don't need to be reduced to a single sentence like the file description line but they should ideally be no more than a few sentences. You can expand the description in the Details section for properties that really do need a lot of explanation.

Methods

The Methods section simply lists the function signature with a brief description on the line below. This description should be just one sentence like the file description line described above. You can add any extra description that a method may need in the Details section.

Details

The Details sections is the most free-form part of the document. This is a good place to put any general description, screenshots, tables and code samples. Level 3 subsections are also fine here and these can be useful for expanding on the shorter descriptions in the properties table, etc.

See Also

The See Also section should be the last thing in the file. Like the Table of Contents, this is generated by a script using special HTML comments which are already present in the boilerplate files. However, the See Also links are specified in a separate file, seeAlsoGraph.json, which is located in the docs folder. Each item in the JSON corresponds to a Markdown file in the docs folder and has an array of links. So an item like the following:

...
"dropdown-breadcrumb.component": ["document-list.component", "breadcrumb.component"],
...

...means that dropdown-breadcrumb.component.md has See Also links to document-list.component.md and breadcrumb.component. The JSON file is processed by a script that adds the right links to the See Also sections. Note that if dropdown-breadcrumb.component has a link to breadcrumb.component then a link in the other direction will be added automatically, even if it is not specified in the JSON file. To use the script, use cd ng2-components from the command line and then run:

node config/generateSeeAlso.js

This will build the See Also sections for all files. Note that you should finish this step before generating any Tables of Contents (for files that need them) because it adds an extra section to the page.

General doc content tips

Some components are only used by a "parent" component and are very simple (eg, Login footer is only used by the Login component). In cases like this, it is a good idea to just add the description as a section to the "parent" page and use the index stoplist to ignore the subcomponent. Similarly, when a component makes extensive use of an ordinary non-component class then it is often OK to describe it in-place rather than starting a separate file for it.

However, you should consider breaking the class out into its own page if:

• Its description is not trivial (eg, if it has properties/events or has other behavior that is not obvious)
• The same class is used by more than one "parent" class (eg, FormFieldValidator); here, it is best to create a new page for the class and link to it from the other pages
• If the "parent" page is already very long and you could use the opportunity to move some of the content elsewhere.

It is often helpful to think of this the same way you would think about adding functions to a piece of code. Adding a function for every minor subtask can result in unnecessary clutter but functions in just the right places make the code much easier to understand, reuse and maintain.