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.
- 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.
- 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.
- 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
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.
- 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
- Add a link for the article to
index.mdwithin 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
.mdsuffix 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
C as the designator. The third article in this category is
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.
- Update the
/docs/articles/categories.txtto define the designator and name of the category.
/mkdocs.ymlto include the category in the
- Update the
/docs/index.mdto include a link to the category.