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.