Tech/News/Manual

From Meta, a Wikimedia project coordination wiki
< Tech‎ | News
Jump to: navigation, search
This page documents the publishing process for the weekly Tech News newsletter. It provides guidelines based on our experience in creating this particular newsletter, but might also be used as a guide for other Wikimedia publications that are delivered to multiple wikis.

The following notes are intended to serve as guidelines for the process of publishing the Tech/News weekly newsletter and as a place to gather experiences and best practices learned from the publication and delivery of the newsletter's previous issues. There are more details about about deadlines and inclusion critera for editors who want to contribute or translate.

Publication schedule[edit]

The current distribution date for the newsletter is Monday, at around 3:00 pm (UTC). This deadline is linked to from the upcoming issue.

Guidelines[edit]

Language
You can check readability indicators, the Hemingway app, the SimpleWriter and the Up-Goer 6 tool to check for complex and rare words. SimplyPut.ie gathers useful resources on how to write in plain English and provides a handy list of words and phrases to avoid. For more specific guidelines, you can try the English Wikipedia Signpost's style guide as well as the more general Manual of Style. Consider using prepositions liberally and avoiding grouping long phrasal groups composed of many nouns.
Links
Be careful with links to wikis other than MediaWiki.org, Commons, Wikidata, and Wikispecies. If you want the links to always work in the same way, always use m:Example to link to anything on Meta-Wiki; always use w:en:Example to link to anything on English Wikipedia; always use q:de:Beispiel to link to anything on German Wikiquote.
Code
All visible MediaWiki or HTML tags should be wrapped in <code><nowiki>...</nowiki></code>;
Add the direction of LTR blocks, for RTL languages compatibility. For instance, <code dir=ltr>.mw-ui-constructive</code> ill be rendered as a LTR text in a RTL translation.
Translation
  • Whenever issues contain text similar to one that had already been published, use the same <tvar|name> to reduce amount of work required of translators and take advantage of translation memory.
  • Inline links that are not supposed to be translated should be put inside <tvar> to simplify translations and direct all users to the same page, for example: [[<tvar|name>c:somelink</>|description]];
    • For recurring items, use the same tvar, so that translators can use translation memory more easily. link, link2, link3 etc. are good generic tvar labels.
    • When you put displayed text inside a tvar, add directionality markers so it displays properly on RTL wikis (and ideally also the language): <tvar|name><span class="mw-content-ltr" lang="en" dir="ltr">your content</span></>
  • &rlm; can solve some RTL problems. Example.
  • Reference links (e.g. to Phabricator tickets) should be at the end of an item, outside the <translate> tags. External links are preferred (even if an interwiki link is possible) because they're automatically numbered.
  • Due to limitations of the Translate extension, whenever you mark for translation, you need to follow up with a dummy edit and mark for translation again if you want your changes to be propagated.
  • Interface messages (button names, etc) should be internationalized using {{int:...}}. See mw:Help:Magic words#Localization for details. Append ?uselang=qqx (or &uselang=qqx) to a URL, to show the interface message's variable name. Example.

Distribution[edit]

See an overview of the process in this 2014 blog post

The distribution generally happens on Monday around 7:00 am (UTC). If you change that time, update the deadline linked to from the upcoming issue.

  1. Do the final polish
    1. Open all translations on Meta and check for red links, in case there was an error during the translation.
    2. Remove the "deadline" template, and mark for translation.
  2. Generate the multilingual text of the newsletter
    1. Go to Tech/News/Sandbox and open the edit window:
    2. Replace the existing issue number with the one that's being sent out (for example, week=28);
    3. After the issue number, insert language codes for languages that have at least partial translations, for instance fr|ko|ja|pl|pt|uk. Do not add en for the English version; as the default language, it is automatically included.
    4. Replace any code that automatically creates dates with month and day written with characters and numbers in the English text. {{#time:<tvar|defaultformat>j xg</>|<tvar|date1>2017-07-11</>|<tvar|format_language_code>{{CURRENTCONTENTLANGUAGE}}</>}} should be 11 July in the English version, but not in the other languages.
    5. Save your edit
  3. Test the message
    1. Manually test the message on a few wikis (e.g. on your user page) using the whole generated text, and look for issues (red links, line breaks, etc.). You can do this in two different ways:
      • Copy/paste the whole generated text manually on a few of your user pages, and preview without saving;
        • Check that it begins with <section begin=, ends with a timestamp, and that it uses the right edition (both text and link);
      • Use Special:MassMessage for a dry run using a test distribution list (see example); the process is the same as for the actual delivery (described further below), except for the target list.
    2. A good rule of thumb is to check:
      • on the English Wikipedia
      • on another language available
      • on another language not available (defaulting to English)
      • on an RTL wiki
      • and on a community page in a localized namespace.
    3. Test it exactly like you plan to send it, including the subject of the message. If you see a mistake, test it again after you fixed the mistake.
  4. Launch the delivery
    1. Open Special:MassMessage in another tab or window
      • Page containing list of pages to leave a message on: Global message delivery/Targets/Tech ambassadors
      • Subject of the message (also used as the edit summary): [[m:Special:MyLanguage/Tech/News/2017/40|Tech News: 2017-40]] (update the link and description with the actual week number)
      • Body of the message: The whole multilingual text generated earlier.
    2. Click on the Preview button on the page; only the English text will show, because it's Meta-Wiki's language
    3. Do a final check, and if everything looks good, click on the Send button on the page
  5. Wrap up
    1. Thank the translators on their mailing list at translators-l@lists.wikimedia.org.
    2. Send the English version of the newsletter to the Tech ambassadors at wikitech-ambassadors@lists.wikimedia.org in an HTML e-mail. Copy the text of the newsletter from the desktop site. You may have to copy the language bar into a text document and copy it again to get the right amount of formatting.