content-guidelines.md

Content Guidelines

This page contains instructions on how to create documentation for Luigi. It defines the rules for each of these topics:

• Structure
• Metadata
• API documentation
• Audience and language
• Format
• Links
• Screenshots and diagrams
• Glossary

Overview

Luigi documentation is written in Markdown and stored on GitHub. The Markdown files are then rendered on the main documentation page using Sapper. Find more about what GitHub-flavored Markdown is here.

Documentation resides in the luigi/docs folder in the Luigi repository.

Structure

Documentation on the Luigi website follows the structure below. When adding a new document, you need to place it into one of the five main categories depending on its topic.

Basics

• Getting started
• Architecture

Luigi Core

• Installation
• Basic navigation
• Advanced navigation
• Navigation parameters reference
• Authorization
• Authorization events
• General settings
• Lifecycle hooks
• UI features
• API

Luigi Client

• Installation
• API

Advanced

• Custom messages

Examples

• Angular
• Vue
• React

Metadata

In order to render documentation correctly on the Luigi website, you need to add metadata to the Markdown documents on GitHub. This does not apply if you are adding text to an already existing document/category.

Navigation metadata

This type of metadata determines where to display the document in the navigation structure of the Luigi website. It must be written as a JSON object surrounded by <!--meta meta--> tags. For example:

<!-- meta
{
  "node": {
    "label": "Overview",
    "category": {
      "label": "Basics"
    },
    "metaData": {
      "categoryPosition": 1,
      "position": 0
    }
  }
}
meta -->

Alert blocks metadata

To draw the reader's attention to something, you can use the quote block option in Markdown. Directly above the quote block, add metadata which determines whether the alert box on the website will be green (success) or yellow (warning).

Use one of these three options for alert blocks:

<!-- add-attribute:class:warning -->
>**NOTE:** Necessary information

<!-- add-attribute:class:success -->
>**TIP:** Useful, but not strictly necessary information

<!-- add-attribute:class:warning -->
>**WARNING:** Very important information

API Documentation

The Core and Client API documents are different from the rest of Luigi documentation. They are automatically generated by a script. Instead of adding documentation directly to the .md files in the luigi/docs folder, you need to:

1. Add documentation as comments to the .js file where the API function is contained. First, write a description of what the function does. Then, include extra categories preceded by tags (if relevant):

• @memberof - defines the larger category the function is part of, e.g. LuigiNavigation or Authorization
• @param - parameters the function takes, e.g. {boolean}, {string}, {Object} followed by any specific name if applicable
• @returns - type and description of what the function returns, e.g. {boolean}, {string}, {Object} followed by any specific name if applicable
• @example - one or more examples of how the function is used
• @since - earliest Luigi version offering this feature

For an example, you can look at the already existing functions, in this case fromVirtualTreeRoot:

  /**
   * Sets the current navigation base to the parent node that is defined as virtualTree. This method works only when the currently active micro frontend is inside a virtualTree.
   * @memberof LuigiNavigation
   * @returns {linkManager} link manager instance
   * @since 1.0.1
   * @example
   * Luigi.navigation().fromVirtualTreeRoot().navigate('/users/groups/stakeholders')
   */

2. Save and commit your changes. If you have run npm install in the root folder (as indicated in the contributing guidelines), documentation should be automatically generated and added to the luigi-core-api.md or luigi-client-api.md file on push to your branch origin. If not, you can run lerna run docu manually.

Audience and language

The audience of this documentation consists mainly of developers interested in implementing a micro frontend UI solution. It is assumed the reader already has basic knowledge of web development. Do not explain general concepts unrelated to Luigi except if they are instrumental for working with the feature you are describing.

When writing documentation, adhere to a few basic rules:

• Use active voice. For example, instead of writing "Luigi Client should be installed...", write "Install Luigi Client..."
• Do not use slang or abbreviations. This also means you should not use contractions ("don't" instead of "do not") or short forms ("info" instead of "information").
• Use the present tense.
• Use concise language and avoid long blocks of text. Lists, tables, or subheadings can help you with that.
• Give practical examples of features instead of only using words to explain them. Additionally, link to Luigi Fiddle as a tool where users can experiment with features.

Format

This section provides you with guidelines on how to format and organize your text.

Headings

Use H1 headings only at the start of the document to indicate the document name.

Only use H2 and H3 headings to organize your content into categories. Do not use H4 headings or lower.

H4 can be only used as a function naming.

Lists

Lists are very useful for breaking up text and providing instructions.

• Use bullet points (created with * or -) for lists involving general explanations.
• Use numbered lists only for step-by-step instructions.

Tables

Use tables when content needs comparison or to organize small bits of information. Avoid long sentences or paragraphs inside tables.

You can find an example of a table in the Styles section of this document.

Code snippets

Surround code snippets with the Markdown code block tag and specify the programming language. Make sure to indent code correctly using your text editor (2 space indentation is the default).

For example:

Luigi.setConfig({
  routing: {
    nodeParamPrefix: '~'
  },

is better than:

Luigi.setConfig({
    routing: {
        nodeParamPrefix: '~'
    },

Styles

Depending on the type of content, use different types of text, for example, bolded or code.

Type	Font	Example
Parameters	bold	viewGroup
Attributes	bold	collapsible
Values	code	true, false
Dynamic parameters	code	{userId}
Folders, paths, filenames	code	Open basicConfiguration.js inside assets/luigi-config
Code snippets	code	See this section
Functions	code	showLoadingIndicator()

Links

If the link is within the same folder on GitHub, use only the relative path. For all other links, including external links, use the absolute path, starting with https://.

To link to a section within a document, use the title of that section as an anchor. For example:

[Link to the "custom messages" section in the "communication" document](communication.md#custom-messages)

Screenshots and diagrams

When adding screenshots or diagrams, adhere to the following rules:

• Only use high-resolution images.
• Only use screenshots or diagrams if necessary, as too many of them can create visual noise.
• As an alternative to screenshots, point to Luigi Fiddle or other Luigi examples when you want to illustrate a concept.

Glossary

This section contains terminology frequently used in the Luigi documentation.

• Luigi Core - the main application and the settings used to configure it.
• Luigi Client - the micro frontend within Luigi Core and the API used to connect the two.
• Luigi Fiddle - a page where you can configure an example Luigi application and explore Luigi functions.
• Parameters - the parameters that can be used to configure Luigi in the Luigi configuration file, for example category, viewUrl, and more.
• Dynamic parameters - the parameters that can be added to create a dynamically changeable path.
• Attributes - the "sub properties" of parameters. For example, the category parameter can have label, icon, and collapsible as attributes.