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

[timhunt]

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

[andrewnicols]

I'd agree with that.

I was also thinking that we should rename that "Commit cheat sheet" to a series of more general git cheat sheets, and include things like fixup commits and suggested ways of working with fixups.

[timhunt]

Oh yes! I was planning to try to write up the 'working with fixups' advice, because I have had enough of re-reviewing all of monster patches, and I want a guide I can point people to - just not time. (I made one small attempt to start, and found it hard.)

I would like to find a better name than 'cheat sheet', but I can't think of one now.

Also, how do we conceptualise these things? I think we should aim for separate articles/pages (not too long), each of which make a specific point:

• More meaningful comments.
• Better commit comments.
• Breaking big changes into logical commits
• Fixup commits to help get big changes through review

And, some of the user cases for them:

• For developers, a way to learn pratical aspects of "the craft of doing software development" that otherwise you might never get explained to you.
• Or, from the other perspective, if you are peer reviewing, and notice that someone needs a certain sort of advice, you can point them the specific guide, rather than having to write it out yourself.
• And, we can also link them throughout the docs, where appropriate.

OK, so having tried to write out what these things are, does that lead to a better name? ... No. Some ideas, none of which seem perfect yet:

• Good practice guide?
• Tricks of the trade?
• A better craft: (just so we can then call them ABC guides).

[andrewnicols]

Also, how do we conceptualise these things? I think we should aim for separate articles/pages (not too long), each of which make a specific point:

Yup - that sounds good.

For the content we've been migrating it's largely been a like-for-like transfer. We have split or merged some pages.

For new content I've found that I go in with an idea of what will work best, and then I discover that having contextual navigation between different pages (compared to MediaWiki's lack of native) changes the way I think.

I think it makes sense to have a structure similar to:

/general/development/abc.md - Introduction and index page to the ABC guides
/general/development/abc/comments.md
/general/development/abc/commit-messages.md
/general/development/abc/logical-commits.md
/general/development/abc/iterating-commits.md

We can use an autogenerated sidebar entry here, and use the sidebar_position frontmatter to select an order other than lexical.

An early apology if I dont' get a chance to fix it before you get there: Some of the sidebar navigation for the /general section needs adjusting. Things have moved and grown and we've learned about how we want to do things and we haven't had a chance to update the sidebar configuration accordingly yet.

Re naming, I'm not quite sure yet. I like the 'abc' analogy. Perhaps "A better contribution" would be better than "craft"?

I'll mull it over :)

[timhunt]

I like 'A better contribution'.

I did a bit of random hacking at main...timhunt:abc, but I don't yet know what I am doing here, and I am not sure if I will get more time. Feel free to steal that if you think you can progress this.