[docs] Create some advice for writing better PHP (and other) docs

What is the Moodle feature that needs documenting?

I just wrote the following (which is either patronising, or helpful) in an email to some colleagues.

Unsolicited advice on writing better comments

• Take a moment to imagine sitting down with another intelligent developer who just does not know about the thing you are working on. What would you want to say to them? Distil down the essence of that into text. (In these Covid times, you may prefer to imagine a call, but the psychological trick of imagining a specific human being as the audience is worth playing on yourself.)
• Any time you find yourself using a word that is part of the name of the thing, be suspicious of yourself. That word is probably not adding any value. (Sometimes you can’t avoid it.)
• And, if essentially all the words in the comment are part of the name, you are just wasting everyone's time. You can do better than that! (Sadly, this is all to common in some Moodle code.)
• But, anyway, think of adding value: what is not already obvious from the name (and type)?
• An example can be worth a dozen words. (A good Moodle’y example: @param $component Frankenstyle component name, e.g. ‘mod_forum’. –I know which bit of that would be most useful to me.)

It seemed possibly worth preserving (opinions welcome), perhpas on a page like https://docs.moodle.org/dev/Commit_cheat_sheet. However, that has not been migrated yet, so I am not sure where to put content like this. It is not really coding style, it is more advice that could be linked from the coding style (like commit cheat-sheet is.)

Anyway, given some hints about where this belongs (which might be in the bin) I will make a pull request.

Is this documentation specific to a Moodle version?

No

Are you able to provide a patch for this?

Yes - I will create one

Review the proposed advice in this issue and inspect the developer documentation around Commit_cheat_sheet, which the issue identifies as a possible home but says has not been migrated. Done means placing the guidance in an agreed developer-docs location and linking it appropriately from coding style or related guidance.