Guide: Writing Articles

Creating documentation pages

Overview

The mission of Ignite UI is to provide feature-rich and beautiful components without sacrificing simplicity. This should shine through in the articles we write and the samples we create.

The articles are not a replacement for the generated source-code documentation. The aim, when writing an article for a specific component or feature, is to touch on the most important aspects of said feature/component. The importance here relates to the difficulty (pain points) our users might encounter when using the components in their application. Edge cases should be considered advanced user stories and thus belong in an Advanced Examples section.

If a component or its features are too many to list in a relatively small article (300-500 words), those must be split into several articles. A good example of such component is the Ignite UI for Angular Grid. The articles must be read like stories, i.e. they should have a clear direction, which includes a well-thought-out, purposeful introduction that sets the tone for the rest of the article. The crux of the article should discuss the laid out features in the introduction. Those features can be split into several sections for brevity and digestibility.

The language the articles are written in should be simple, catering to a wide-range of people coming from various backgrounds both in terms of development experience and culture. Homophobic, religious, political, and other sensitive topics should not be reflected in the articles or the samples that illustrate a point.

Here's a sample structure of what an article might look like:

1. A title containing the name of the component/feature
2. A brief description of the component/feature (1-2 sentences)
3. A basic sample(demo) showcasing the component. The introductory sample shouldn't jump to complex scenarios and edge cases. Those should be reserved for the Advanced Examples section.
4. A section outlining the basic usage of the component, ideally describing how the component is used in the context of an application. This section should not list every single feature of the component. It might be divided into several smaller sections.
5. An Examples section, which contains demos focusing on specific features/quirks. Each example should cover one feature only with supporting explanation / code samples as needed.
6. The examples section is followed by a brief section that showcases how theming is done via the Sass theming engine. The sample doesn't have to cover all properties of a theme, just a few to give a taste of what the user can expect.
7. An Advanced Samples section that includes practical samples. This section doesn't require exhaustive documentation or code samples, albeit they should provide a live editing link to a platform, like StackBlitz. The provided samples may show the component/feature in the context of other components/features.
8. A section with reference links to the API documentation.
9. A section with additional resources that links to related topics, the forums and github page of the product e.g. a grid topic may want to reference the tree and hierarchical grid topics as well

Samples

All samples, with the exception of the ones in the Advanced Examples section, should be as close to vanila as possible. That means they should not customize the styling via themes or otherwise, should not be complex in structure, or be used in conjunction with other components. The composition of the samples should happen only via the IgxLayout directive, which should remove the need to write custom CSS that polutes the sample's code.