Adding an Article

Adding a new article to the document requires a little more consideration and requires updates to some other resources, but is otherwise the same as submitting a merge request to improve an article.

The articles in this document are grouped into broad categories. Generally, proposed new articles should fit into an existing category.

1. Determine the appropriate group for the article. Consult the categories index for a listing of all the categories. If no category seems appropriate for your proposed new article, consider reporting an issue to discuss the need for a new category with project members. Instructions for defining a category are given below.
2. Determine the title for the article. A good title is consise enough to fit on a single line or two of text, and conveys enough information that it can stand alone as a synopsis of a given practice or principle. When specifying the title, capitalize the first letter of the first word, and capitalize any proper nouns; all other words should use lower case letters.
3. Create the file for the article in the appropriate category directory. Use the next available number in the sequence of articles in the category. Project maintainers may ask you to adjust this before merging if other new articles are merged first. Name the file using the form
   <NNN>-<short-title>.md
   where NNN is the zero-prefixed article number and short-title is a further shortening of the article's title; we're looking for a meaningful and unambiguous name, not an exercise in typing long filenames. See existing articles for examples. In the short-title part of the filename, use lowercase letters with hyphens to delimit words.
4. Add a top-level heading as the first line of the article, specifying the category-qualified article number, a period, and folllowed by the title. For example:
   # Q3. Perform operations as code
5. Add a link for the article to index.md within the category directory. The index for a category is a numbered list of linked article titles. Specify the link URL using the article filename, omitting the .md suffix at the end.

Defining a Category

Articles are grouped in broad categories. Each category is assigned a single letter of the alphabet as the category designator. This designator is used to create a qualified article number that is convenient when discussing or communicating about articles, or in other documentation.

A category named Cloud Adoption and Migration Practices has been given the letter C as the designator. The third article in this category is identified as C3 in this document. The articles in each category are in an arbitrary order, such that there is never a reason to change the identifier assigned to an article. This makes is reasonable to refer to this article using the identifier C3 when communicating about the article or perhaps in other documentation.

When it it is necessary to define a new category, the following updates are required.

1. Update the /docs/articles/categories.txt to define the designator and name of the category.
2. Update /mkdocs.yml to include the category in the nav: navigation tree.
3. Update the /docs/index.md to include a link to the category.