JiaChen-Zeng commented 6 years ago

Here are some suggestions about the formatting of documentation which came up while I was working on the translation. The goal is to make the documentation look less confusing and more compatible with different translations in terms of formatting.

Document Header

Suggestion: Add an attribute :toc-title: Table of Contents.

Reason: This attribute represents the TOC label. The translator only need to change "Table of Contents" to the translated language without adding a new attribute manually.

Bold and Italic

Suggestion: Always using __text__ and **text** instead of _text_ and *text*.

Reason: Like in Chinese and Japanese, there is no spacing between words, so single _ or * will be treated as normal texts instead of formatting instructions. It is better to avoid translators changing the formatting manually.

Link and Anchor

Suggestion: Always use link:url[text] syntax. Note the link: prefix must be added.

Reason: This can work without spacing around the link. Maybe just I can't figure out how to make << xxx >> work.

Suggestion: Always using link:#a-anchor[text] for links within the document and add an explicit anchor ID [#a-anchor] right above the section title to link.

Reason: The anchor for a section is dependent on the text of that section, which can be messed up after translation. This works across different translations.

Suggestion: Use link:another-document.adoc[text] for links between documents. Note the extension of the link is adoc.

Reason: This makes the link works both on github and gitbook. Gitbook will automatically change .adoc to .html.

Admonition

Suggestion: Always using the syntax described below (NOTE can be other type):

[NOTE, caption=Note]
====
Something to note.
====

Reason: That "Note" of the caption attribute is the label displayed in the left of the admonition block. The translator only need to change into translated language without changing the formatting. The label of inline admonitions (NOTE:) can't be changed (or maybe I couldn't figure it out).

Word Name

Suggestion: Always surround the word which means Red word with ` (also in section titles, without uppercase).

Reason: Red word (keyword in DSL, or function name) is not that distinguishable from normal English words (in my opinion). If it is used in section titles without surrounded in a code span, it can be hard for translators to decide whether to translate it or not, and also may be confusing for normal readers. I have tried to make it a code span in the section title and it renders good.

Suggestion: Maybe avoid using red-words like normal English words in sentences.

Reason: Like the example below from the description of check in view.adoc, It sounds stupid if I keep left and right as is after translating. Or wrap left and right into a parenthesis and annotate after translating left and right, which also doesn't looks so good.

para: The align field controls if the text is displayed on the left or on the right side.

para: align 字段控制该文本是靠 left 边显示还是靠 right 边显示。

para: align 字段控制该文本是靠左边（left）显示还是靠右边（right）显示。

Type Annotation

Suggestion: Unify the type annotation over all documentation.

Reason: It is good to do so. Currently it can appear in two different kind of contents (see below), function syntax code blocks and some tables. It is not always at the end of a paragraph.

From macro of preprocessor:

#macro <name> func <spec> <body>
#macro <pattern> func <spec> <body>

<name>    : name of the macro function (set-word!).
<pattern> : matching rule for triggering the macro (block!, word!, lit-word!).
<spec>    : specification block for the macro function.
<body>    : body block of the macro function.

From Event! datatype of view:

|`offset`| Offset of mouse cursor relative to the face object when the event occurred (`pair!`). For gestures events, returns the center point coordinates.

Suggestion: Don't use "," to separate multiple types, nor "or" needed.

Reason: Removing these won't cause confusion. The datatype won't lose coloring as the example of #macro above.

Spacing

Suggestion: Always add a separate line between the actual content.

Reason: This can avoid content format corruption in some languages.

PeterWAWood commented 6 years ago

These seem very sensible suggestions that should be adopted. I wonder how we could come up with a Red Documentation Style Guide and how we could keep it from being too bureaucratic?

greggirwin commented 6 years ago

@AT-Aoi's notes here should be the basis for that document. I agree that they are good suggestions.

In the context of paper books, there is a legend in the introduction, generally, that explains the typographic choices. We could do the same for document writers.

greggirwin commented 6 years ago

One question is where to put these rules. Wiki page for now?

PeterWAWood commented 6 years ago

I think the best place would be in the docs repo though we’ll need to call it something like doc-style-guide.adoc as there is already the code style guide.

I’ll try to prepare something based on AoiSan's (or should that be Ayatsukisan) proposal.

On 9 Feb 2018, at 00:35, Gregg Irwin <notifications@github.com mailto:notifications@github.com> wrote:

One question is where to put these rules. Wiki page for now?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/red/docs/issues/36#issuecomment-364169680, or mute the thread https://github.com/notifications/unsubscribe-auth/AAqkWpIqhQMYYx7m_FU7Al-CLCc68Iigks5tSyJdgaJpZM4R6svZ.

red / docs

Some suggestions about documentation formatting #36