-
-
Notifications
You must be signed in to change notification settings - Fork 447
Description
How could the content be improved?
In the 'Plotting' lesson which I have taught from this week as part of an internal training course, there is a line in the section near the start under the heading 'matplotlib is the most widely used scientific plotting library in Python' which states:
Simple plots are then (fairly) simple to create.
however it is fairly well-known and -publicised (Google via its Developer Documentation Style Guide, Microsoft e.g. quoted in its older guide 'Microsoft Manual of Style' etc.) that it is bad practice to claim that something (technical) is 'simple' or 'easy' or similar since it is subjective and what may be so to the writer(s) or those with experience could not be so to the reader and therefore frustrate them put them off, or just sound patronising. Even with the '(fairly)' adverb modifier, this is still the case.
So I/we think the statement should be rephrased. Notably in this case I think the intention is to convey that it only takes a small number of lines i.e. not much code (one main call) is required, more specifically and objectively, so the statement should be updated from asserting simplicity to asserting on conciseness (concrete suggestion below).
(To be clear, the first use of the word 'simple' is fine because it's not referring to the process of doing something that any reader could try i.e. covering a procedure, in that case it's describing an object.)
Suggestion
In the statement quoted above, 'are then (fairly) simple' should be rephrased to something along the lines of 'can be created with just one call [to plt.plot]' (last bit square-bracketed bit optional, as the code snippet below it showcases this) - which is specific and objective and as per the probable intention of the writer of said line when saying more-ambiguous and subjective 'simple'.