Skip to content

How to add new documentation

Jump to bottom
Andy Stark edited this page Mar 23, 2018 · 7 revisions

Doc files are all located in the docs folder at root level in the repository. Each library (Core, Content Services, etc) has its own subfolder within the docs folder. The content of all doc files is written in GitHub flavored Markdown.

Use the following steps to prepare docs for submission to ADF:

  1. Name the doc file the same way you would name a source file but with ".md" as the suffix instead of ".ts". So the docs for "my-feature.component.ts" should be kept in a file called "my-feature.component.md".

  2. Follow the general structure of an existing similar component, service, etc. In particular:

    • The text should have only one top-level heading for the title. This should be like the file name but with titlecase and with the dashes replaced by spaces. So "my-feature.component.md" would have "My Feature Component" as its title.
    • The first paragraph should be a one-line description of what the component does. This description will appear in index lists and so it is important to keep it short and snappy.
    • Use the existing level 2 headings (Basic Usage, Details, See Also, etc) but don't add any new ones. Describe the component using level 3 sections within the Details section.

  3. (Optional) Add a metadata section to the page (see Adding metadata below).

  4. Save the file in the appropriate subfolder within the docs folder (so if you've added a component to the core library then place the doc file in the core subfolder, etc).

  5. (Optional) Rebuild the index pages (see Rebuilding the index below).

  6. Commit, push, etc.

Rebuilding the index

The index pages are built using a script and so any new doc files you add won't appear in the index until the script is run. This gets done regularly but if you want your new component to be listed immediately then you should rebuild the index yourself. From the command line, use cd to set the working directory to lib and then type:

npm run docindex

When the script has finished, you should see your new component listed in docs/README.md. If you see "not currently documented" in the description field then check that the doc file has the correct name format, as described above.

Adding metadata

We use metadata in the doc files to track several useful items of information. The metadata appears in a section at the top of the Markdown file, surrounded by "---" markers:

---
Added: v2.0.0
Status: Active
---

# Accordion Component

Creates a collapsible accordion menu.
...

New items of metadata get added from time to time but the most important items are the ones in the example above:

  • Added: This tracks the version where the component was added and is used to generate the version index page. The version should be a string of the form "vX.X.X" reflecting the semver numbers.
  • Status: This tracks the availability status of the component. If you omit this field then the status will be assumed to be "Active", which indicates that the component is suitable for normal use. Two other status values are also used. "Experimental" means that the component is available only temporarily or not fully tested and developed yet. "Deprecated" means that the component is still available but is obsolete and likely to be removed in a future version.
Clone this wiki locally