The Charmed Kubeflow (CKF) website has a documentation section generated from special topics in the discourse.charmhub.io Kubeflow category.
These topics are published as wiki topics, meaning they can be edited by anyone with enough reputation on the discourse. There is a link at the bottom of each docs page which will take you to the corresponding discourse topic.
Contents:
- Editing in Discourse markdown
- Some guidance for writing
- Adding pages
- Docs Markdown, everything you wanted to know
Editing in Discourse markdown
If you are familiar with Markdown syntax, editing the pages should be straightforward, though there are a few idiosyncrasies which you should be aware of:
-
linebreaks: Unlike most common Markdown, discourse respects ALL linebreaks. Don’t bother neatening up paragraphs by adding linebreaks at 79 characters unless it is really important for the output
-
images: there are limitations involved in adding images. It is better to link these to an external source rather than try uploading them when they are more of them than just a single screenshot or inline graphic
-
emojii: try not to use them - they look fine in discourse but often translate badly or at the wrong size in the published docs
There is more detailed explanation further down this page
Some guidance for writing
Documentation consistency in terms of writing style is vital for a good user experience.
Here are some general tips:
-
use a spell checker (set to en-GB!)
-
resist being overly formal
-
resist being overly verbose
-
verify links and examples
-
don’t repeat what’s been covered in other posts - use links
-
don’t make too many assumptions - explain, link or reference things the average reader may not know
We adhere to the Canonical Documentation Style Guide. In particular:
-
we use British English (en-GB), for example:
-
the ise suffix in preference to ize (capitalise rather than capitalize)
-
our instead of or (as in colour and color)
-
license as a verb, licence as a noun
-
catalogue rather than catalog
-
dates take the format 1 January 2013, 1-2 January 2013 and 1 January - 2 February 2013
Adding pages
Adding a new page to the documentation involves:-
Creating a new topic in discourse, correctly labelled
-
Publishing it as a wiki page
-
Adding the page to the navigation
Some of these steps can only be achieved by people with special permissions or a very high status on the kubernetes.io discourse. If you want to add a page but don’t have the relevant permissions, you can still create the topic and then ask one of the admins to add it for you.
Create the topic
Just click on the Discourse New Topic button like you would for any other post. Under the categories, it must go under charm, and should add the Kubeflow and docs tags too.
Write the page!
Once you have entered all the text, checked it looks good in the preview and clicked on the create topic button, you should check it turned in to a Wiki page.
Topics posted to the category are turned into a Wiki by default, but in case there was an issue, it is useful to check. You will find the Wiki options under “show more> post admin actions” (the elipsis at the bottom of the post). If the options say " Remove Wiki" (as in the above image) then it’s working.
Add it to the navigation
To add the page to the navigation, you will need the “short URL” of the page you created. This includes the critical topic id number, but omits the site part. E.g. the short URL for the main index page https://discourse.charmhub.io/t/introduction-to-charmed-kubeflow/3749 is simply /t/introduction-to-charmed=kubeflow/3749.
Use the short URL to create a link in the ‘Navigation’ section of the page. For example:
* [Getting started](/t/introduction-to-charmed=kubeflow/3749)
The full URL MUST be added to the special table which begins:
## URLs
[details=Mapping table]
| Topic | Path |
| -- | -- |
This table controls the re-written URL of the docs page generated from the topic. Without an entry here, your page will not be processed as a docs page. Pay particular attention to the format and the separators for the table - don’t miss any! E.g.:
| full_url | /docs/name-of-page |
| https://discourse.charmhub.io/t/install-kubeflow/3670 | /docs/install |
Please be thoughtful when adding pages - it really isn’t a good idea to just randomly add pages of things you think would be useful or interesting. In order for people to be able to find and reference documentation, it should be created to fit into the hierarchy of pages which already exist. If you are unsure of where the page should go, or don’t think it fits into any of the current sections in the navigation, please have a discussion about it first!
Docs Markdown, everything you wanted to know
Markdown format
Documentation is written in the CommonMark Markdown format supported by Discourse.
Mostly, you don’t need to worry about the syntax. You can simply use the style toolbar in the Discourse topic editing window to mark the elements you need.
If you don’t find what you are looking for in these topics, you can always copy from an existing post (TIP: you can view the raw content of a page by just editing the url in your browser, and replacing the /t/topic-name/ part with /raw/ instead. For example: https://discourse.charmhub.io/raw/3670 instead of https://discourse.charmhub.io/t/install-kubeflow/3670.
Headings and titles
## Subheading within a document
### Subheading of a subheading
We don’t use the top-level heading (# Heading) as the topic title is used for this.
Headings and subheadings should use sentence case, which means the first letter is the only one capitalised. Proper nouns and acronyms are exceptions.
Lists
For a bullet (unordered) list, use a hyphen ( - ). Sub-lists will use an hyphen indented at least 2 spaces:
We (mostly) adhere to the Ubuntu style guide, for example:
- we use British English (en-GB):
- the _ise_ suffix in preference to _ize_
For a numbered list, use 1. to precede each item. The numbering will be rendered automatically, which makes it easy to insert new items:
1. This is the first item
1. This is the second
1. This is the third
1. This is a sub-list
The indent here needs to be at least 3 spaces.
Unless a list item is particularly long (which should be avoided) and includes punctuation, don’t end the item with a full stop. If one item needs a full stop, add one to all the items.
Tables
For example:
|animal|type|colour|
|-|-|-|
|dog | lab | yellow |
| horse | shire | bay |
It is produced by the following markdown:
|animal|type|colour|
|-|-|-|
|dog | lab | yellow |
| horse | shire | bay |
Use colons for horizontal alignment:
heading 1 | heading 2 | heading 3
:-|:-:|-:
left | centered | right
type | access | key
The markdown:
heading 1 | heading 2 | heading 3
:-|:-:|-:
left | centered | right
type | access | key
Left-aligned is the default, and does not need to be stated.
Code blocks
Enclose a code block with three backticks and include the type of code:
name: gimp
version: '2.10.8'
summary: GNU Image Manipulation Program
The most common code types are: bash, yaml, json, and text. The last is like a miscellaneous type. It is often used to display command output and does not highlight anything.
Do separate command input blocks from command output blocks. For input, do not use a command line prompt (e.g. $ or #) and precede the output block with some kind of intelligent message:
uname -r
Sample output:
4.14.151
Inline code
Use a backtick to mark inline commands and other literals. For instance, to create $KUBEFLOW:
For instance, to create `$KUBEFLOW`:
N.B. You will normally have to press the backtick key twice to get a single backtick
Links
For links to internal files or external URLs, use the following format:
[visible text](url)
You can also use an intermediary label and then associated that label with the actual URL (usually at the bottom of the document). This is common in documentation, as often there can be several links to the same URL, and it makes it easier to maintain when updating links:
[visible text][label]
.
.
.
[label]: url
The visible text is what will appear in the documentation.
For internal pages the full URL is not used (important for the navigation links). The below forms will both work for, e.g. https://discuss.kubernetes.io/t/introduction-to-microk8s/11243/:
[Install](/t/install-kubeflow/3670)
Or just:
[Intro](/t/3670/)
Comments
Adding comments (which aren’t displayed) to the source may be useful either to create a TODO list, or to explain to future editors of the document why something has bee expressed in a certain way.
<!--
This is better as text than a screenshot as it will look completely different each new version.
-->
A TODO list would normally go at the very top of a document:
<!--
TODO:
- Update versions for 1.20
- Update when bug is fixed: https://bugs.launchpad.net/juju/+bug/1797399
-->