Requesting a review of https://www.mediawiki.org/wiki/User:Jdlrobson/Stable_interface_policy/frontend before this is sent to a larger audience.
I would like someone to look through this document before then and help me improve the technical writing so it's as clear as possible to the developer audience it will be sent to.
Timeline : By 15th August.
Thanks in advance! Happy to jump into a call if you need more context around what I'm trying to achieve here.
Hi @Jdlrobson, I'm looking at this now, so expect some feedback by the end of the week :)
Hi @Jdlrobson, the policy looks good! I like that you've included the terminology and motivation sections. I also like the use of examples and the links to things like codesearch to provide guidance about how to do things in addition to what things to do. Here's some general feedback:
Separating content by audience group
This policy covers a lot of content. To make the page as useable as possible, it's important to make it easy to skim and, as much as possible, to make it easy for readers to skip any content that isn't relevant to them. It looks like this policy addresses two groups: gadget and extension developers, and MediaWiki core developers. Are the guidelines for these two groups separate? Is it possible to organize the document so users can read only the parts that are relevant to them?
Making headings more descriptive
Section headings are the main tool for making a page easy to skim. Section headings should summarize the main idea of the section in a short phrase, usually starting with a verb and omitting filler words like "guidelines for". This also helps create contrast between headings, making the table of contents easier to read. For example, instead of "Guidelines for naming", use "Naming classes with prefixes".
Explaining examples
I really like how you've used examples to illustrate your points. The more examples the better! I'd recommend making it as obvious as possible what readers should take away from each example, making sure the explanation is directly adjacent to the example. You can also add formatting to the examples to make them easier to understand. For example, adding a title using Template:Codesample or adding counter examples as done on this page.
Clarifying vague words
When using "this" or "it", be as explicit as possible about what you're referring to. Phrases like "in this manner" and "to circumvent this" can be confusing, especially for translators. Even though it can sound repetitive, write out what you're referring to each time. Additionally, readers may have different interpretations of phrases like "most important elements" and "complex UIs", so try to be as specific as possible. Lastly, there are a few references to time ("for now", "while this policy is being rolled out") that should be avoided to reduce confusion as the policy ages.
Adding a quickstart
If possible, it would be great to have a quickstart or quick guide section at the beginning of the page that covers the most important points of the policy in brief, such as the one in the stable interface policy.
Minor edits and clarifications
I've made a set of minor edits to the page to correct small things. In addition, I have a few clarifying questions:
Let me know if you have any questions! If you'd rather talk through this synchronously, feel free to put some time on my calendar.
This is great. No questions as of yet! Hoping to make some changes based on this by the end of the week!
Making headings more descriptive / Separating content by audience group
I'm still thinking about this but have had a crack ag improving things. There's also this discussion here if you are able to participate!: https://www.mediawiki.org/w/index.php?title=Topic:Xmmslwdiy1ciw7ob&action=history
Explaining examples
I've taken a pass through this but I couldn't see many places where I could take this opportunity. Is there anything in particular that jumps out to you that i've missed that would be helped by an example?
Clarifying vague words
This should be done ( https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058278&oldid=6058224 )
Adding a quickstart
This should be done ( https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6058288&oldid=6058278 )
Minor edits and clarifications
Should all be taken care of now.
Following up on this after our conversation in Slack. The changes you've made look good!
Is there anything in particular that jumps out to you that i've missed that would be helped by an example?
Best practice is to provide the example directly following the text it relates to, like you do with the example under HTML markup. For example, under JavaScript code:
* Code that states itself as stable in its JavaScript documentation either on [https://docs.wikimedia.org docs.wikimedia.org] OR [[ResourceLoader/Core_modules]], and preferably using the <code>@stable</code> tag. If a property or module is marked as stable that indicates all of its public methods are also stable.<syntaxhighlight lang="javascript">...EXAMPLE HERE</syntaxhighlight> * Code that is defined on the public <code>mw</code> object, that has not been documented as <code>@private</code>, regardless of where the code is added (extension, skin or gadget) even if the code has not been marked as <code>@stable</code><syntaxhighlight lang="javascript">...EXAMPLE HERE</syntaxhighlight>
This also applies to the examples under What providers should do when making breaking changes... and What providers should do when removing...
Best practice is to provide the example directly following the text it relates to, like you do with the example under HTML markup. For example, under JavaScript code:
Done in https://www.mediawiki.org/w/index.php?title=User%3AJdlrobson%2FStable_interface_policy%2Ffrontend&diff=6107643&oldid=6107631 Thanks!
I've had some further feedback since our last discussion so it might be worth going over this one more time (possibly together?).
I should note the document is now official so more eyes should be on it. I have also pointed to this ticket in https://www.mediawiki.org/w/index.php?title=Topic:Xpsu67sstgjidje8&action=history in case anyone from the community is interested in participating or voicing concerns.
the document is now official
🎉
I've had some further feedback since our last discussion so it might be worth going over this one more time (possibly together?).
Sounds good! Feel free to put some time on my calendar.
I've completed all the edits I had planned to address formatting, clarity, and organization (before and after).
The only remaining note I had from our meeting was to add a notice that stability annotations may not be present while the implementation of the policy is in progress. @Jdlrobson, if you can add that, I think we can call this task done.
Thanks @apaskulin for all your help on this! I've added notes to the document pointing to T348076, T138401 to get those fixed.
Here is the relevant update if you want to give that a quick check before resolving this ticket!:
https://www.mediawiki.org/w/index.php?title=Stable_interface_policy%2FFrontend&diff=6136745&oldid=6136619