Time to have standard style to write help documentation?

Hi there,

The style of the help documentation is too different and I have unified everything that is not mentioned in Style Guidelines: SCDocs · supercollider/supercollider Wiki · GitHub in the following PR:
Various help documentation updates by prko · Pull Request #6534 · supercollider/supercollider · GitHub

I think it would be good to summarise a writing style for help documentation on the above style guide page, and I would like to write more things that I have not written on the above page:

  • I think all tag keywords should be written in lower case.
  • I am a bit unsure whether it is good to lowercase any of the first letters (except for class names and proper names) after summary::, description::, method:: and argument:: if the letter is not the first word of the whole sentence.
4 Likes

What happened to that documentation working group some years ago? Why not start a new working group, starting with a specified task like this (combined with conclusions from the other discussion), which can be divided into smaller tasks, etc? That’s very suitable for a working group.

1 Like

I would obviously be interested in joining that working group, but I feel that I don’t know my way around enough just yet to be the one to start it… so for the time being I’m looking over prko’s PRs and trying to come to grips with the git system.

2 Likes

It would be useful to hear from those involved in the last style guideline effort.

It took quite a bit of coordination. Here are some example threads that may be instructive on the process:

1 Like

Personally I’m not that concerned with formatting and more with the content, but I do have somewhat of an editing routine for prose and it bothers me if I don’t know e.g. if that empty line should be there or not. That is to say, I don’t much care what the style guidelines end up being but there should be some.

I wonder if we might edit that wiki entry above (Style Guidelines: SCDocs · supercollider/supercollider Wiki · GitHub) to collect issues that are under consideration, even if we do not (yet) have a solid decision on it? That would give folks working on the help a list of things to pay attention to, even if the guidelines are still undecided. For instance, there are some thoughts (& some agreement, in fact) on line length/ where to introduce line breaks or empty lines in the discussion for @prko’s PR, but they were not terribly easy to find:

  • a line in a schelp file should contain only one sentence if the sentence is short;
  • to split a sentence into more than two lines if the sentence is long. In this case, comma, colon, semicolon, quotation marks and prepositions could be used as line separators

If the wiki entry had a section for something like “undecided issues”, “currently under discussion”, or “to be confirmed”, then at least contributors know where to look for a quick reminder.
I’m happy to do this, but am currently not yet sufficiently oriented within the project to even know who to ask for wiki permission. I think settling this would involve synthesizing/condensing a lot of what the discussion has already touched on.

Finally, I wonder if it is conceivable to simply adopt the documentary style guidelines of some other project so we don’t have to rethink everything… e.g., docs for python libraries (matplotlib, numpy, etc.) look pretty unified to me, but that’s just what I know.

Agreed – IMO (personal opinion), balance is an important consideration.

If style guidelines are too strict, it can drive away volunteer contributors (“c’mon, I was just trying to help”). For instance, if I see a bug in the C++ sources and I know how to fix it, I personally will think twice about putting in the PR myself, because lint checking for C++ changes is very strict, e.g. (actual example) –

// this is not OK
    if(std::isinf(beats)) return beats;

// this is also not OK!
// but it's slightly more OK
    if(std::isinf(beats))
        return beats;

// this is OK
    if (std::isinf(beats))
        return beats;

… where I have to admit (perhaps I just don’t know enough C++) that I don’t see a massive improvement between “not OK” and “OK” there. Minor improvement, yes, but is it worth irritating a contributor over a space and a line break, when the initially submitted version is perfectly readable?

If they are too loose, then it could impact readability – a free-for-all would also be a bad thing.

Again speaking just for myself, it’s good to give style guidance to contributors, without that guidance being a set of hard-and-fast rules to be enforced – so, if it’s up to me, I might not say “standard style” and prefer instead to say “style recommendations,” and not send PRs back to authors over minor infractions. (Or, review comments could say “we’ll accept this, but next time, consider xyz based on style guidelines at url.” Contributors are gently guided toward documentation, and they could choose to update the PR, but wouldn’t be “disciplined” if they don’t.)

hjh

1 Like

That’s sensible. I guess I’m the kind of person who’s scared off by a lack of guidelines… but I do think it’s a good idea, especially for the help, to make it clear that the style aspect is not the most important thing.

the git format may not be the best for this kind of work… from my experience of reviewing / editing other people’s writing or getting mine reviewed/edited (e.g. by sending back and forth word documents or whatever), a lot of these things take less time to fix than to point out to other people. Whereas there doesn’t seem to be a way in github for a reviewer to just silently remove an empty line and approve the contribution in its amended form… (or maybe I just don’t know about it).

I wonder if a wiki or something of the like wouldn’t ultimately be better suited? I’m almost sure this has come up before, but all I find now is the discussion of moving the existing wiki (which is of course distinct from the help) off github, which is a different topic.

Yes, strict guidelines may discourage people from contributing!
But it can also discourage or delay contributions if you have created a PR using existing documentation forms and terminology and are asked to change those terms and forms.

I’d like to illustrate this with something that happened to me recently:

I hadn’t thought about style at all until recently when I received feedback on a particular PR.

I’m not an expert in this area (I wish I was, but there’s a lot I don’t know…), so I used the same jargon and sentence style as in the same help documentation the method is in.

The problem was the term answer in the sentence after the method:: tag, where the subject is omitted. I was using answer, but someone else said it should be return, so I went through the whole documentation and replaced every answer with return that I thought was in the same context.

But…,

in the help documentation, the imperative form is sometimes used in sentences where the subject is omitted after method::, argument::, description::, summary:: tags, and so on.

So it was suggested that this should be fixed for the changes I made. The historical background of the use of terms was also mentioned.

At this point I decided that the help documentation needed to be formatted uniformly, so I changed what I could in bulk using regular expressions in VSCode, and made a lot of changes by hand, one at a time.

Since then, however, two PRs have been merged, and the branch associated with my PR is broken. I’ve spent about a week doing this, and I can’t go back to this way of doing things.

I’ve now spent about three days writing sclang code to reformat the Supercollider help documentation using replaceRegexp (Thanks to @jordan for implementing replaceRegexp to make this possible in SuperCollider.), which has been available since last summer. I’m almost there, but a few more considerations mean I need to rewrite the code, so I’ll have to take a break for a while, and won’t be back until mid-February.

Whether the guidelines are strict or loose, new contributors may not know about them because the guidelines are not included/linked in the help documentation, and will write the help documentation as they feel comfortable. The code I’m writing now is for someone to use every few years or so, or for contributors to use when formatting their documentation.

==

One thing I can assure you of is that the help documentation should be easy for a beginner to understand. To achieve this, I think the following things are necessary, for example

  • The format should be clear and consistent, e.g:
    • If the first sentence followed by a tag keyword (and method/argument name) pair does not contain the grammatical subject of the sentence, the verb is said to be imperative. Other following sentences without the grammatical subject of that sentence should use the singular third present form verb (to me it would be better to see all these cases in the singular third present form, but it is inappropriate to say this as my English skills are not high enough to judge this).
  • Terms should be used consistently: e.g. answer(s) and return(s); item and element.
  • The use of the returns:: tag should be reconsidered. In many cases the first sentence after the method tag starts with return(s). We could consider changing this to answer and adding a returns:: tag with the returned class or data type. However, this will be hard work. There are too many cases where returns:: tags are not used.
  • Spelling should be standardised, for example: ugen, UGen; -ize, -ise, etc.

One thing for reviewers: in a line, non-code text should be on a separate line, as too long a line is unproductive to review.

This sounds very frustrating. I’ve only half followed that PR (because life) but it did look like an enormous amount fo work.

Btw have you shared the code (for the reformatting of the doc) anywhere?


Anyway, I propose the following to move this along (although I can’t guarantee that I’ll have much time before mid-Feb either, as I should really be working on annoying academia nonsense until the 12th):
I’ll try to draft a revision of the wiki page on Style guidelines that summarizes the points made here and in the related PR discussions; and I’ll make that a forum thread so folks can chime in if they disagree vehemently with something in there or have further suggestions; and once we’ve revised the thing enough that everybody’s ok with it, I will bother someone to give me permission to update that wiki page itself.

No.

I did not save the code that worked well because I found a problem in the code.
Currently I have a new code with a better structure than the previous one. However, there are some problems with regular expressions. Sharing this code will be a bit ridiculous I think. I will share it when I have solved the regular expression problems.
Using the capture function ($0, $1 ...) and negative search ((?<!) and (?<) ) is not so easy to optimise the whole code… I have used AI services to save time, but they are not helpful. They do the work I can do very quickly, but they never find a perfect solution when I need to think deeply…

I hope to be able to share the code by the middle of February.

That’s a good point about consistency, which I hadn’t considered.

The English rule has one exception to this: If the subject of the sentence is clear, and the verb is in third-person present singular form (in English, normally this form is different, e.g., to take, I take, you take, he/she/it takes), then it’s assumed to be declarative rather than imperative. This case happens a lot in the documentation.

keep(n) – keeps the first n items in an array

Here, the method itself is the only possible subject of the sentence, and the verb form can’t be imperative, so the meaning must be that the method is what’s doing it. For English speakers, it might be a bit pedantic to write “keep(n) – this method keeps the first n items…”

Without the s, then yes, it feels like an imperative – “keep(n) – keep the first n items” although this could be taken as instructing the computer to do the thing.

For English speakers, I don’t think either one is wrong. But you raise a good point – non-native English speakers may get tripped up over “is that a command or not?”

I see the point, though it may be tricky to enforce.

Absolutely! Method documentation should explain all inputs (expected types and what their contents mean) and output. If you have to run code to see what the method really does, then the documentation is incomplete.

Also tricky here to require British doc authors to use American spelling :stuck_out_tongue_winking_eye:

hjh

2 Likes

It has always been clear that we adopt the North American spelling. (I don’t know if that’s written somewhere).

I can imagine that it can be annoying sometimes (I can put myself in such a situation in my mother tongue), but it can be converted with simple tools anyway.

1 Like

I think this is a good goal to shoot for for docs. For C++ and SC code there are two classes of guideline, rules and recommendations.

  • Rules can block PRs, and in the case of C++, are enforced by the linter.
  • Recommendations wouldn’t block a PR, but are still useful for reference.

Consistent contributors should probably eventually adapt to them. But for new contributors, especially those who don’t even know that style guidelines exist, it can be helpful for a reviewer to say, “this isn’t a blocking issue, but consider reviewing the style guidelines, in particular regarding x part of your contribution.”

2 Likes

In a related thread:

This is why I linked to the GH Issues above - that was the approached used to facilitate hashing out details in the previous effort to develop formatting guidelines. There was a “point person” that moved the discussion along, and made a judgement call when there had been enough discussion and decided if there was consensus.

There could be other approaches, coordinated in an RFC, for example. I don’t think this thread is the place to decide each case (I’m glad though that @prko has already introduced some very good cases that resonate with many people, I’m sure!).

I have personally kept track of a couple dozen+ suggestions or open questions related to scdoc formatting, but I never shared them because I wasn’t in a place to coordinate the effort. So I’d be happy to chime in with those if a project gets off the ground :slight_smile:

3 Likes

Hi again,

  1. just to confirm - because this hasn’t come up as it’s very much a niche issue I imagine: The current working assumption is that readers of the help will use the scide helpbrowser or the HelpBrowser class, such that some aspects of the style that the helpbrowser cleans up anyway are based with help contributors, not help readers in mind? (Thinking about spaces and linebreaks primarily.)
    Background: I’ve recently started to browse the schelp files directly in nvim, because the builtin browser for me is often slow and I use scnvim anyway (whose txt rendering for me also doesn’t work very well). Turns out a bit of syntax highlighting and conceal can make this quite readable, but what nvim syntax can’t do without editing the actual files is remove newlines.
    Is there a significant portion of sc users that browse the help in this way (my guess is no), or in other ways that are different from the scide help browser?

  2. I suggested the following above, but nobody chimed in on it, so I’ll quote myself:

I’ll try to draft a revision of the wiki page on Style guidelines that summarizes the points made here and in the related PR discussions; and I’ll make that a forum thread so folks can chime in if they disagree vehemently with something in there or have further suggestions; and once we’ve revised the thing enough that everybody’s ok with it, I will bother someone to give me permission to update that wiki page itself.

The idea is that I will try to function as what @mike has described as the “point person”, mostly summarizing what other people said already and basically banging the gavel when consensus has been reached so we can move on to the next thing.
Do folks think that this the forum the right place for this, or should this go into a gh issue? I don’t care either way.

1 Like

My impression is that the forum could be good for getting an initial scope of the guidelines. Then GH Issues could be spawned for discussing the details of each sub-category of guidelines, as was done with the Cpp formatting project.

Deciding whether modal tags should be capitalized while deciding whether examples should be inlined, in a Discussion, or in and Examples section, all in a single thread would likely get messy quickly.