5

I was just reading http://lasagne.readthedocs.org/en/latest/modules/layers.html and wondering about some documentation style questions. One of them was the use of the word "should".

For example:

This method should be overridden when implementing a new Layer class. By default it raises NotImplementedError.

Is that a place where "should" should be used? It seems to me that the following would be better:

This method has to be overridden when implementing a new Layer class. Otherwise, it raises NotImplementedError.

Is there a style guide about such language-independent documentation style questions? (e.g. should a documentation be written in passive voice or with "you" or "the developer" would be another question)

Please note that I'm not writing down requirements. This is a question about documentation of a library.

Improve this question
3
  • see also: What is the benefit of the MoSCoW technique?
    – gnat
    Jun 3, 2015 at 19:46
  • 1
    Those are probably not duplicates: this question is about documentation (where ease of reading is more important than precise language), not about requirement documents or technical specifications (where unambiguity is of utmost importance).
    – amon
    Jun 3, 2015 at 20:06
  • 1
    @amon As a programmer, when describing the implementation of code or requirements to other programmers (I suspect this would be the case for "This method should be overridden..."), I would use the least ambigious useage and preferably the one that is best known. Outside of that constraint, when writing in general, I would look to Writers.SE tag: technical-writing for aspects of the use of passive voice in documentation.
    – user40980
    Jun 3, 2015 at 20:20

3 Answers 3

Reset to default
6

Ever since I read RFC 2119, I began to put a reference to it in specifications - even code documentation. A comment like the following somewhere in the documentation helps set the standard for interpretation.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (https://www.ietf.org/rfc/rfc2119.txt)

It's a pretty small and easy to understand RFC and you only need read it once.

Improve this answer
1
  • Wow. Didn't even think that there would be an RFC for that!
    – Mike Nakis
    Jun 3, 2015 at 20:33
0

The term "must" tends to be reserved for completely black and white situations where you really have no option but to do something in a specific way, or else failure is inescapable.

The person writing the documentation cannot write "must" if it is possible for someone, under some circumstances, no matter how artificial, to prove that technically, the issue being discussed is not an absolute necessity.

In other words, I suppose it must be fairly easy for someone to implement a new "Layer Class" without overriding the method that throws NotImplementedError, and then proceed to instantiate that class, invoke a few of its methods while making sure to not invoke the problematic method, and then go "voila! It was not necessary to override that method after all!"

Of course, this whole discussion may be an attempt to read too much into the written word of the documentation. Perhaps the person writing the documentation simply was not hell bent on using the most precise possible word of the English language, so they simply wrote "should" as a synonym for "must".

Improve this answer
0

RFC2119 was mentioned. According to RFC2119, "SHOULD" means: There may possibly perhaps under some circumstances be reasons why you wouldn't follow the requirement, but you should really seriously think about it and consider all the consequences.

That seems to describe the situation quite well.

Improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.