Page Structure

The documentation should have consistent flow. This goes for having certain naming conventions for headings to the use of images and other helpers. Here is a proposed structure that pages should follow. This is NOT yet official. No discussion has been had to this end it is just Garbee's ramblings.

Notable content sections

We have certain use-cases for sections that happen to fit in many areas. These are:

• Advantages - This discusses the specific reasons that the feature offered is superior to more traditional/widely accepted methods.
• Limitations - This discusses known drawbacks to the tools. This section should always include some input at the end about why despite the limitations the tool is still powerful. A good example of this is the Limitations of device mode.
• Tricks - A section dedicated to nice additional uses of the tools that don't fit well into a quick "protip" note within the documentation flow.
• Extras - For links to other resources that discuss the content at hand.

While not all pages will need these sections, they are the Headings to be used when they are needed.

Aids

Docs often need images or other items to supplement the writing so things are more clear to developers. When writing make sure to not have content depend upon the aids. Text content should be all that is required to understand the feature as much as possible.

Remember when marking up aids in the documentation to use figure elements. Also, please try to include a figcaption to describe what the aid is trying to convey or what it is displaying. Simple images for quick reference (such as buttons) may be inserted within the text immediately after what the button triggers or represents.

Try to default to using the Web Starter Kit demo page for screenshots. However, if you are showing off a complex topic such as JS Debugging then please use the most appropriate demo. Just make sure the demo is publicly available so others can follow along.

Page Objects

Think of the whole documentation as an object oriented program. Each page is its own object that inherits from a base class. A little bit of cross-documenting is fine but too much duplication is frowned upon. Instead of duplicating content in the many places it is applicable, find a single place in the docs the content best belongs. Then reference that location in other places for getting more detail.

Notes

• General Notes are small pieces of content that bring more emphasis to a reader. These are good for describing technical bugs within the content or for cross-referencing other doc pages.
• Protips are quick references to alternative methods or other lesser-known features. Remember if a tip is quite big, to make a “Tricks” section on the page and provide the full details there.