Style Guidelines: SCDocs

Purpose of style guide for contributors and reviewers.

• Style guide compliance is not a criterion for PR rejection. However, contributors should expect reviewers to request amendments.
• First-time contributors will be nudged towards the guidelines but in such a way as to not discourage further contributions.
• Regular contributors will be expected to adhere to style guidelines.
• For new contributions, conformity with the present style guidelines take priority over conformity with existing help files. (There is just not enough time to bring all of the help up to date.)

These are guidelines, not rules set in stone. That is, the purpose is to clarify expectations, and provide templates; they should ultimately make contribution less complicated, not more complicated.

---

Text formatting (as seen by HelpBrowser user) and spelling

• If possible, documentation should be written so non-native speakers of English can understand it easily, using simple words and phrasing. If you are unsure about your formulations, do not hesitate to ask for help during the PR review. Requests for help on language are very welcome.
• American spelling is preferred.
• Use sentence case (first letter of sentence is capitalized) even in grammatically incomplete sentences, such as "Returns the square root."
• If unsure, personal pronouns should be the non-binary they.
• SuperCollider’s documentation follows standard grammar specifications. For example, sentences should start with a capital letter and end with a period.
• When referring to classes, use capitalization to help distinguish between discussing a class, and a common word. For example, “the class Function” makes it clear that we’re talking about the class called Function.
• Link mentions of classes to their help files (link::Classes/AbstractFunction::) as much as possible; similarly for methods. If a class or method is mentioned many times in one paragraph, it is ok to link only the first appearance. These links can help disambiguate meanings and lead to quicker understanding.
• When mentioning methods of classes external to the helpfile, include the respective class name; when mentioning methods of the class you are documenting, omit the class name. (E.g., in a helpfile for Function, you would write .fork, but in a helpfile for any other class, you would write Function.fork)
• External references should at least include an author and year of publication (or url and last update of website). When referencing external sources, you can use any citation format you want, but the Chicago Manual of Style format is preferred.
• When writing method (or argument) descriptions, assume that the method is the subject of a declarative sentence, as in “.squared returns the square of a number.”
• When relevant, use terms and concepts from the Glossary. For example, a common phrase used in SuperCollider is “this parameter cannot be modulated” (referring to a Ugen parameter which cannot be modulated after Synth initialization) (see Glossary entry).

Issues to settle at a later stage:

• Handling of syntax shortcuts and method aliases in help files.

---

Argument specification

• Use the tags argument:: and returns:: to document these items. Do not describe these in the method description body (after method:: ).
• All arguments should be documented (as specified in this document). If language would be duplicated in various places in one document, it is ok to point a reader to other places (for example an instance method freq_ might tell the reader to see the specification for the freq parameter in the class method *new).
• Return values that differ from the default (this) should be documented.
• Names of arguments should be highlighted in the text using the code:: tag.
• For common arguments (such as freq, phase, amp, etc.), consult and consider using the descriptions from the SCDoc Template File to encourage consistency and clarity.
• If an argument is used to specify one of multiple options (for example Env’s curve argument), a table should be used to associate the argument with its result. For guidance on building a table, see the SCDoc Template File.
• Pursue opportunities to disambiguate and clarify argument options. For example, GrainBuf’s interp argument accepts 1, 2, or 4, so the documentation should clarify that 3 is invalid.
• When an argument expects a certain range, specify the minimum and maximum valid inputs. Where appropriate, specify invalid inputs: For example 0 is an invalid argument for the exponential range in .explin. Mathematical interval notation (such as [0,1)) is welcome, but should be accompanied by prose: “Between zero and one (including zero, not including one).”
• Clearly document when certain values may cause instability, artifacts, or unexpected behavior (clicks, very loud sounds, etc.).

---

Text Formatting (as seen by contributors, not HelpBrowser users).

Also see SCDocSyntax and Writing Help.

Blank lines and indentation:

• At most one blank line between lines of text and/or code.
• Use tabs for indentation in schelp-formatted text and code.
• Line length should be limited to one sentence.

Tag usage:

• Prefer using the lowercase forms of tags (code:: ::, method::).
• Use the private:: tag to hide private methods
• Use the inline code:: :: tag when referring to file names or file paths.
• Prefer code:: :: tags for sc code, teletype:: :: for non-sc code.
• When writing mathematical formulas, you can include KaTex formatting via the math:: tag, but this is not necessary; use whatever notation you feel most comfortable with. (For more information on using the math:: tag see the SCDoc Template File)

Single line tags

• Single-line tags: Place a space between the tag and the following text.
• Some section tags (section::, subsection::, argument::) are followed by text that will serve as a heading, others (description::, examples::) do not. Consider this example:

section:: This text will serve as a heading.

description:: 
This text is the body of the description, not the heading.

Header tags:

• Header tags should appear in the following order: title:: summary:: categories:: related:: (The tag class:: should not be used, and replaced with title::)

Inline tags (strong:: ::, emphasis:: ::, etc.):

• No space between inline tags and the words they surround. Example:

emphasis::No:: space between strong::inline tags:: and the words they surround.

Multiline tags (code:: ::, note:: ::, footnote:: :: …).

• Tags should be on separate lines from both preceding/following text and enclosed text.

Example:

This is a sentence of preceding text
warning::
This is the  enclosed text.
::
This a sentence of further text.

Exception for footnote tags:

• The opening tag for a footnote should be placed on the same line as the preceding text, without a space between the final word of the sentence and the tag. (Otherwise, the renderer inserts a space between the last word and the footnote marker.) Example:

This is a sentence at the end of which is a footnote marker.footnote::
This sentence is the content of the footnote.
::

---

Spelling:

A useful table of common differences can be found in the section "Variant spellings by category" of this resource, where the rightmost column of the table is the American spelling. In general, the Merriam-Webster dictionary is often taken to be the standard for American spelling.

Example citation formatting:

Follows Chichago Manual of Style. Representative examples (borrowed from Computer Music Journal):
Feller, R. 2011. "Formatting References." Computer Music Journal 13(3): 51–55.
Cahill, M., and B. Terry. 1996. "All About References." Proceedings of the 1996 International Computer Music Conference, pp. 51–54.
Wyse, L., G. Tzanetakis, and D. Van Nort. 2004. Book References. New York: John Wiley and Sons.