Fold Fiona's review conventions into the guidelines - #48
Open
abrudz wants to merge 7 commits into
Open
Conversation
Record the rules and style preferences that FionaDyalog has applied consistently when reviewing merged documentation pull requests, taking her comments as authoritative where they refine or override the current text. rules.md: avoid ambiguous "so" and set connectives off with commas; gloss codes on first use; use the Oxford comma; keep parallel items consistent. Correct the Edit window / Trace window casing and record that "Editor" and "Debugger" name the tools. Add sections on describing parameters and values (inline defaults, the whether-1-or-not-0 pattern) and on deprecations. Add rules on consecutive blank lines, footnote ordering, the [DYALOG] placeholder, and balanced parentheses. style.md: lower-case the second element of hyphenated headings; require meaningful headings; broaden bold to configuration parameters and more UI components; add glosses and the englishname-glyph naming pattern to italics; require consistent code spans; expand cross-referencing (link first mentions and subsections, replace positional phrases, avoid link overload and version numbers in links); and add structure rules (filenames match titles, no duplicated content, hidden keywords last). tables.md: sentence-case captions, alphabetical ordering, justified rows and columns, empty cells as non-breaking spaces, and introducing tables.
Fold in further conventions from Adam's review feedback and the Style Guide: state the present rather than the history; that/which and if/whether; "and so on" not "etc", and not alongside "for example"; dfn/dop (not "dynamic function/operator"); "Session window" to disambiguate the window; a list is not one sentence split across items; inline-link the term itself rather than trailing "(see ...)"; keycodes in bold; and a short Contributing section (PR linked to an issue, branch named after the issue, close the issue from the merge message). Also reword the consecutive-blank-lines rule to explain that it keeps the source tidy.
A numeric range takes an unspaced en-dash (1–2147483647), the standard typographic form, rather than the spaced form previously shown.
Mine FionaDyalog's review comments across the whole repository, not only those on abrudz's PRs, and fold in the rules and refinements that recur. Notable additions: a variant options template (principal option, default phrasing, bold option names); house phrasing for arguments and results, and value-meaning value lists; the backwards-compatibility Legacy case, distinct from deprecation; a lower-case version prefix; system function as the umbrella term; the standard-departure exception to stating the present; escaping every literal angle bracket in prose; the version-in- link exception for Release Notes; and preferring prose over screenshots. Plus smaller refinements to headings, bold, code font, references, tables, acronyms, lists, and the OS library extensions.
Variant option names and values are now in code font, not bold. Mark a
default with (default), or <small>(default)</small> in a table value
column, replacing the withdrawn { .shaded } attribute. Record the correct
bracket names: curly braces, round parentheses, square brackets. Note
that an example section with more than one example takes a plural
Examples heading.
… whether(-or-not), Note-that/in-order-to, no shouty caps, comma usage, parameter linking, deprecation dating
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Record the rules and style preferences that FionaDyalog has applied
consistently when reviewing merged documentation pull requests, taking
her comments as authoritative where they refine or override the current
text.
rules.md: avoid ambiguous "so" and set connectives off with commas;
gloss codes on first use; use the Oxford comma; keep parallel items
consistent. Correct the Edit window / Trace window casing and record
that "Editor" and "Debugger" name the tools. Add sections on
describing parameters and values (inline defaults, the whether-1-or-not-0
pattern) and on deprecations. Add rules on consecutive blank lines,
footnote ordering, the [DYALOG] placeholder, and balanced parentheses.
style.md: lower-case the second element of hyphenated headings; require
meaningful headings; broaden bold to configuration parameters and more
UI components; add glosses and the englishname-glyph naming pattern to
italics; require consistent code spans; expand cross-referencing (link
first mentions and subsections, replace positional phrases, avoid link
overload and version numbers in links); and add structure rules
(filenames match titles, no duplicated content, hidden keywords last).
tables.md: sentence-case captions, alphabetical ordering, justified rows
and columns, empty cells as non-breaking spaces, and introducing tables.