RFC docs: style guide first sketchy draft #2062
Conversation
Use https://github.com/asciidoctor/kramdown-asciidoc with command: kramdoc --format=kramdown <file_name>.md
| include::../attributes.inc.adoc[] | ||
| :description: Writing styles, markup, formatting, and other standards for LinuxCNC Documentation. | ||
| //:group: unassigned | ||
| //:info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. |
There was a problem hiding this comment.
Should refer to LinuxCNC not Gitlab
| //// | ||
| TODO Other docs | ||
| In addition to this page, the following resources can help you craft and | ||
| contribute to documentation: | ||
|
|
||
| * xref:../index.adoc[Doc contribution guidelines] | ||
| * xref:word_list.adoc[Recommended word list] | ||
| * xref:../testing.adoc[Doc style and consistency testing] | ||
| * https://design.gitlab.com/content/error-messages/[UI text guidelines] |
There was a problem hiding this comment.
Should this URL point to Gitlab?
|
|
||
| * If you use an image that has a separate source file (for example, a vector or | ||
| diagram format), link the image to the source file so that anyone can update or reuse it. | ||
| You can freely include or link presentations, diagrams, and videos. No |
There was a problem hiding this comment.
Whilst this is a nice idea, we generate PDF documentation, so need to be clear what happens in that case to, for example, an embedded movie.
| mentioning https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments[the writer for] | ||
| the applicable https://about.gitlab.com/handbook/product/categories/#devops-stages[DevOps stage or group]. | ||
| If you have questions when considering, authoring, or editing documentation, | ||
| ask the Technical Writing team. They're available in `#linuxcnc-docs` rooms |
There was a problem hiding this comment.
I don't think that we have a linuxcnc-docs channel?
| * For each subsection, increment the heading level. | ||
| In other words, increment the number of `=` characters in front of the | ||
| heading. | ||
| * Avoid headings greater than `H5` (`=====`). If you need more than five |
There was a problem hiding this comment.
I think that we have problems with heading levels > 3.
See, for example, the many warnings here abour "sect5"
http://buildbot.linuxcnc.org/buildbot/builders/2000.docs/builds/8227/steps/make%20docs/logs/warnings%20%283263%29
And bear in mind that sect1 is the overall document, and therefore === in a signle file is sect4
|
|
||
| ==== Markdown rule `MD044/proper-names` (capitalization) | ||
| ==== AsciiDoc rule `MD044/proper-names` (capitalization) | ||
|
|
||
| A rule that could cause confusion is `MD044/proper-names`, as it might not be | ||
| immediately clear what caused markdownlint to fail, or how to correct the |
There was a problem hiding this comment.
This seems markdown specific
|
|
||
| * Avoid unnecessary words. | ||
| * Be clear, concise, and stick to the goal of the topic. | ||
| * Write in US English with US grammar. (Tested in https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/British.yml[`British.yml`].) | ||
| * Write in US English with US grammar. |
There was a problem hiding this comment.
Hmmmm
I just can't bring myself to spell things incorrectly.
| // FIXME Decide on fixed line width. | ||
| // @silopolis: 100 seems to correspond more or less to the number of | ||
| // characters in a line on a printed page | ||
| * Splitting long lines (preferably up to 100 characters) can make it easier |
There was a problem hiding this comment.
This makes things harder for weblate translators.
Discuss with @smoe
| when pressing the tab key. | ||
| * Use serial (Oxford) commas before the final *and* or *or* in a list of | ||
| three or more items. | ||
| // TODO Test with https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OxfordComma.yml[`OxfordComma.yml`]. | ||
| * Avoid dashes. Use separate sentences, or commas, instead. |
There was a problem hiding this comment.
This might be a good place to mention that HAL pin names require a "minus" sign rather than em-dash or similar if users are to be able to paste code samples into their HAL files without getting very confusing errors.
| https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers[list of supported languages and lexers] | ||
| for available syntax highlighters. Use `plaintext` if no better hint is available. | ||
| * Syntax highlight hints are required for code blocks. + | ||
| See the https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers[list of supported languages and lexers] |
There was a problem hiding this comment.
I think that this is different for Asciidoc.
Note that Rust works better than C for comp files as it handles trple-quoted strings.
| * https://marketplace.visualstudio.com/items?itemName=darkriszty.markdown-table-prettify[Markdown Table Prettifier] for Visual Studio Code | ||
| * https://packagecontrol.io/packages/Markdown%20Table%20Formatter[Markdown Table Formatter] for Sublime Text | ||
| * https://atom.io/packages/markdown-table-formatter[Markdown Table Formatter] for Atom | ||
| // TODO Editors plugins or extensions for formatting AsciiDoc tables ? |
There was a problem hiding this comment.
I don't know of any, but adoc tables aren't hard to do anyway.
| @@ -882,139 +1014,187 @@ Example: | |||
| `+markdown | |||
| the instructions for your OS. | ||
|
|
||
| //// | ||
| TODO Use GitLab's or provide our images compression helper script | ||
|
|
||
| If you use macOS and want all screenshots to be compressed automatically, read |
There was a problem hiding this comment.
We won't be using MacOS, will we (I mean, I do, I am now, but I don't think that's relevant to this file)
| Don't use the Markdown emoji format, for example `:smile:`, for any purpose. Use | ||
| <<gitlab-svg-icons,GitLab SVG icons>> instead. | ||
| Don't use the AsciiDoc emoji format, for example `:smile:`, for any purpose. Use | ||
| <<gitlab-svg-icons,LinuxCNC SVG icons>> instead. |
|
|
||
| Use of emoji in Markdown requires GitLab Flavored Markdown, which is not supported by Kramdown, | ||
| the Markdown rendering engine used for GitLab documentation. | ||
| Use of emoji in AsciiDoc requires LinuxCNC Flavored AsciiDoc, which is not supported by Kramdown, |
There was a problem hiding this comment.
Kramdown is not relevant here
|
|
||
| //// | ||
| TODO LinuxCNC Icons | ||
| ____ | ||
| https://gitlab.com/gitlab-org/gitlab-docs/-/issues/384[Introduced] in GitLab 12.7. | ||
| ____ | ||
|
|
||
| You can use icons from the https://gitlab-org.gitlab.io/gitlab-svgs/[GitLab SVG library] |
|
There is probably a fair bit more that I failed to notice and comment on. |
Here is the WIP style guide after importing GitLab's one, converting it to adoc, and making a first pass to adapt it to LinuxCNC project.
There's still a lot to do (as you can see from the many TODOs and FIXMEs in the comments) but I thought it would be better to get your feedback ASAP.
Please throw all your ideas, remarks and criticisms.
Maybe we could put the embedded GH review comments to good use as it allows to keep discussions close to the matter.
TY
J