Some suggestions about documentation formatting
まだ誰も着手していません。
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 35/100
- issue の種類
- ドキュメント
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
調査の方向性
Start by reviewing the documentation examples cited in the issue, including view.adoc, preprocessor.html, and the Event! datatype example, then inventory the repository's existing formatting conventions. Done means the listed header, emphasis, link, admonition, code-word, type-annotation, and spacing conventions are applied consistently and remain suitable for translation.
索引モデルが issue の本文から書いたものです。
説明
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: Thealignfield controls if the text is displayed on theleftor on therightside.
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.
- 主要言語
- CSS
- スター
- 68
- フォーク
- 47
- PR マージ指標
- 30日以内にマージされた PR はありません
コントリビューションガイド
このリポジトリのコントリビューションガイドは索引されていません
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
red/docs のほかの issue
-
難易度 1/5 1時間未満 初心者へのやさしさ 72/100
-
What's `#INF`? オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
-
難易度 1/5 1時間未満 初心者へのやさしさ 65/100
-
難易度 1/5 1時間未満 初心者へのやさしさ 68/100
似ている issue
-
agent-ready documentation needs-triage
難易度 1/5 1〜3時間 初心者へのやさしさ 88/100
-
untriaged
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
dotnet/dotnet-api-docs#13095 ·
-
documentation
難易度 1/5 1時間未満 初心者へのやさしさ 91/100
-
workflow-status page template still says reusable workflows are "triggered only by workflow_call:" オープン
難易度 1/5 1時間未満 初心者へのやさしさ 92/100
-
refactor
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100