Jump to content

Tech/News/Manual

Add links
From Meta, a Wikimedia project coordination wiki
< Tech | News
(Redirected from Tech/News/For contributors)
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 just below for editors who want to contribute or translate.

What Tech News is

[edit]

Tech News is a newsletter documenting technical changes to the Wikimedia sites that affect Wikimedia editors. It is not a general Wikimedia newsletter, nor a technical newsletter for anything related to wikis.

It is "technical" in a fairly strict sense: Almost everything the Wikimedia movement does is related to technology one way or another. There's a cost for every item in Tech News. The longer the newsletter, the more likely people are to stop reading it because the information is overwhelming. The longer the newsletter, the more difficult it is for the translators to find time to translate it every week. The point of Tech News is to have a central source of information where Wikimedians can find technical updates that are important for their work.

What is typically not included

[edit]
  • Changes only relevant for one language or one wiki, where it's not a first example of something that will be available for other wikis in the future. There are easier ways of getting that information out than putting it in a movement-wide newsletter translated to a fair number of languages. Exceptions to this are Wikidata and Commons because other wikis depend on them.
  • Non-technical changes. Very little that happens in the Wikimedia world is more than one step removed from being technical. We are a collection of websites. However, this also means that once we stop defining technical change as something that is technical in itself, rather than something that can lead to technical change, we lose much of the definition that separates Tech News from being a general Wikimedia newsletter. Examples could be news about WMF team strategies or statistics about our sites, as opposed to a new technical feature Wikimedians can use to get statistics.
  • Fancy things related to the Wikimedia sphere that don't really affect reading, editing or developing. A good example would be Listen to Wikipedia, to the sound of which more than one issue of Tech News has been written.
  • Small changes with very little effect on Wikimedians, for example very minor changes to the UI or minor updates of existing products that will only affect a small number of editors.
  • Backend change. If users won't notice and it doesn't affect their user scripts, we typically don't include it.
  • Short disruptions or limited-scale incidents, like a wiki being down for a short period of time. Only very long or global outages are reported with an explanation of why.

Otherwise, be bold and add your information! We will discuss it with you if needed.

Adding to Tech News

[edit]

There are a few ways to add information to Tech News. If you are familiar with the item you want to add, please include simple explanation in one to three sentences that explains what is changing and how it affects Wikimedia contributors, written for non-technical readers.

An ideal item consists of

[edit]
  • 1–4 sentences summarizing the key point(s):
    • Who (exactly) is the target audience? (E.g. admins? Wikipedia-only editors? all users in some specific languages?)?
    • What (exactly) is happening?
    • Why is it changing, or how is it an improvement? (Explain the feature to unfamiliar people)
    • How should editors react? (e.g. Make edits, share feedback, etc)
    • Where can they learn more?
    • When is the change happening? (If it's a deployment-train feature, use "later this week". Keep in mind the newsletter is delivered on Mondays.)
  • 1–3 links:
    • Ideally it should link to a translatable documentation wikipage as part of the prose.
      • If non-English content isn't available, then link to a Phabricator task (perhaps with a screenshot at the top of the Description) or an announcement-email. For entries in the "Updates for editors" section these are formatted as a plain [external-link] at the end of the entry. For entries in the "Updates for technical contributors" section they can be within the prose.
    • Phabricator links are always welcome as supplementary links (formatted as a plain [external-link] at the end). These are often useful for technical editors to be able to see.
    • The first link in each entry should be the most important one.

For example:

  • Editors at all wikis can now use <feature-name, linking to docs page>. This feature enables <improvement to workflow>. Please <share feedback / read more, linking to relevant page(s)>. [full-URL-phabricator-link]

How to add an item

[edit]

There are options!

  • The easiest way is to just add the item to the next issue yourself. Don't worry about getting it perfect. We'll edit it for simplicity and translatability.
    • If you think something should be included but don't know how to explain it, you can just add a new bullet point with the link and someone else will take a look at it. Like this: * [https://phabricator.wikimedia.org/T131187]
  • You can also add the #user-notice tag to any Phabricator task.
    • If you can, please also add a comment there, roughly explaining what changes your item causes (the goal of what editors need to learn/do), and when/what week it needs to be announced
  • If you want to do something else, maybe write a longer explanation, you can ask us on Talk:Tech/News, which the Tech News writers watch.
  • You can also contact the person writing the issue directly. This is not recommended if you want to be sure the item goes into the next issue, unless you are very sure who to contact that particular week. It is usually handled by Sandister, but she is occasionally traveling/sick/etc and might not be handling some issues. In that case either Quiddity, Uzoma, Johan, or Trizek take care of it.

Occasionally, a non-urgent update might be moved to next week's edition, especially if the current newsletter is already very long, to spare the readers and translators. Even if it's eventually not included, every suggestion is helpful, as the writers and editors depend on them to be able to write the newsletter at all. Never be afraid to add anything because it might not be included. It's still appreciated.

When to add something

[edit]

The optimal times to add something to Tech News are:

  • When the change is happening, add it the week before so that it is in the newsletter that is delivered on the Monday the week your change goes live on the wikis.
  • When you start a new project: If you work on a software team working on a big change, you can include this when you have a project page, the work is starting and there is plenty of room for feedback and use cases.
  • If you're introducing a breaking change and people need to update scripts, bots or other tools, you should include this at least a month or two before things stop working.

Translating Tech News

[edit]

Tech News is translated by volunteers every week, typically into 15–22 languages. The latest issue is found at Tech/News/Latest. It's finalized on Friday evenings (UTC) and sent out on Monday evening (UTC). The best way to keep track of when there's a new issue to translate is to sign up on the translators mailing list, or watchlist the entire year ahead of time. Anyone is welcome to help out.

When is the work done?

[edit]

The issue is written and edited on Thursdays. Preferably, as much as possible of what's going into next issue should already have been linked in the draft, tagged with user-notice in Phabricator or otherwise have reached the Tech News writers by Wednesday evening so there's time to, if necessary, talk to the developers and simplify the language. It is marked for translation and the translators are notified Thursday (late afternoon UTC/morning Pacific time).

It's finalized and frozen on Fridays. Late additions are added during the Friday (UTC). Do not plan to include things on Fridays. The translators are told it is safe to translate Friday late afternoon UTC/Friday morning Pacific time. All new items after this should go into the next week's draft. We depend on the translators to be able to reach out to editors who don't speak English. Please don't add to their burden by adding work after they're supposed to be done.

It's sent out on Mondays. Translations added after it's sent out via MassMessage are very welcome and will be available on Meta, but will not be distributed to other wikis.


Writing guidelines

[edit]
Brief version: Tech/News#contribute

Entry-structure recommendations

[edit]
  • 1–4 sentences summarizing the key point(s):
    • Who (exactly) is the target audience? (E.g. admins? Wikipedia-only editors? all users in some specific languages?)?
    • What (exactly) is happening?
    • Why is it changing, or how is it an improvement? (Explain the feature to unfamiliar people)
    • How should editors react? (e.g. Make edits, share feedback, etc)
    • Where can they learn more?
    • When is the change happening? (If it's a deployment-train feature, use "later this week". Keep in mind the newsletter is delivered on Mondays.)
  • 1–3 links:
    • Ideally it should link to a translatable documentation wikipage as part of the prose.
      • If non-English content isn't available, then link to a Phabricator task (perhaps with a screenshot at the top of the Description) or an announcement-email. For entries in the "Updates for editors" section these are formatted as a plain [external-link] at the end of the entry. For entries in the "Updates for technical contributors" section they can be within the prose.
    • Phabricator links are always welcome as supplementary links (formatted as a plain [external-link] at the end). These are often useful for technical editors to be able to see.
    • The first link in each entry should be the most important one.

For example:

  • Editors at all wikis can now use <feature-name, linking to docs page>. This feature enables <improvement to workflow>. Please <share feedback / read more, linking to relevant page(s)>. [full-URL-phabricator-link]

Language

[edit]

You can check your writing in the Hemingway app and the Up-Goer 6 tools that will highlight complex sentences and rare words. 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.

Do not ever use "we", "us", "our team" -- Tech News does not use first-person, as it's too ambiguous.

[edit]
  • Always use the shortcut-interwiki links:
    • E.g. m:Example to link to anything on Meta-Wiki; w:en:Example to link to anything on English Wikipedia; q:de:Beispiel to link to anything on German Wikiquote, etc.
    • (Context: The full-size interwiki links will break (redlink) on the specific-projects themselves, because for example wiktionary: is also the Project-namespace name on Wiktionaries.)

Special: pages should either be:

  • linked using the English-default/fallback (so they work locally at all wikis), and the labels tvar'd for translation.
    • E.g. [[Special:AbuseFilter|abuse filters]]
    • or - [[Special:AbuseFilter|Special:AbuseFilter]]
  • linked using {{#special:...}} and a custom tvar for a contextual-inline-hint to translators
    • E.g. [[{{#special:Undelete}}]]

Code

[edit]
  • All visible MediaWiki or HTML tags should be wrapped in ...;
  • Add the direction of LTR blocks, for RTL languages compatibility. For instance, .mw-ui-constructive will be properly rendered as LTR text within a RTL translation.
  • For short strings, prevent confusing linewrap with this: 
    <code dir=ltr style="white-space: nowrap;">font-sizecode>
  • A fully bi-directional code-snippet within a tvar might look like this: 
    <bdi lang="zxx" dir="ltr"><code><nowiki> ... the code snippet ... nowiki>code>bdi>
  • A listing of separate code-snippets all within a single tvar might look like this: 
    <bdi lang="zxx" dir="ltr"><code>.class1code>bdi>{{int:comma-separator/{{TRANSLATIONLANGUAGE}}}}<bdi lang="zxx" dir="ltr"><code>.class2code>bdi>

Translation

[edit]
  • Whenever issues contain text similar to one that had already been published, use the same 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 to simplify translations and direct all users to the same page, for example: [[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): your content
  • ‏ can solve some RTL problems. Example.
  • Reference links (e.g. to Phabricator tickets) should be at the end of an item, outside the tags. External links are preferred (even if an interwiki link is possible) because they're automatically numbered.
  • 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: "{{int:wikieditor-toolbar-tool-file-upload}}"
  • For digit-grouping, consider using {{formatnum:1000}} instead of plain-text of "1,000", however, you must also use the PLURAL code for the associated keywords (example, using {{PLURAL:25|task|tasks}}).
  • For entries that are short and technical, but perhaps don't deserve expansion within the entry itself, consider adding a qqq explanation for the benefit of the translators. For example this one.
  • For lists of wikis, wrap these examples in a tvar:
    • by codename: azwiki{{int:comma-separator/{{TRANSLATIONLANGUAGE}}}}bnwiki{{int:comma-separator/{{TRANSLATIONLANGUAGE}}}}dewiki
    • by localized name: {{int:project-localized-name-azwiki/{{TRANSLATIONLANGUAGE}}}}{{int:comma-separator/{{TRANSLATIONLANGUAGE}}}}{{int:project-localized-name-bnwiki/{{TRANSLATIONLANGUAGE}}}}{{int:comma-separator/{{TRANSLATIONLANGUAGE}}}}{{int:project-localized-name-dewiki/{{TRANSLATIONLANGUAGE}}}}
  • For variables that needs to be shown in the text but that are identical to tvars (e.g. $1), escape them by splitting the text within the tvar into 2 separate nowiki'd chunks, e.g. $1

Standardized lines

[edit]

Here are some standardized lines we occasionally re-use for easier translation workflows:

  • MediaWiki deployment train changes / problems:
    • "There is no new MediaWiki version this week."
      • Add this by replacing the usual line with: * {{safesubst:Tech news text/{{TRANSLATIONLANGUAGE}}|no new version}}
    • MediaWiki 1.36.0-wmf.1 was scheduled to be deployed on some wikis last week. The deployment was delayed because of unexpected problems.
  • Bi-annual server switches:
    • You will be able to read but not edit [[phab:T1111111|some wikis]] for a few minutes on {{#time:j xg|2020-01-01|{{TRANSLATIONLANGUAGE}}}}. This will happen around [https://zonestamp.toolforge.org/1630818058 05:00 UTC]. This is for database maintenance.
    • [[m:Special:MyLanguage/Tech/Server switch|All wikis will be read-only]] for a few minutes on 14 September. This is planned at [https://zonestamp.toolforge.org/1631628002 14:00 UTC].
  • Major incidents:
    • Last week, all wikis had slow access or no access for NNN minutes. This was caused by [??a database problem??].
  • New wiki creations:
    • One new wiki has been created: a {{int:project-localized-name-group-wikipedia/{{TRANSLATIONLANGUAGE}}}} in [[d:Q00000|LANGUAGE]] ([[w:XXX:|w:XXX:]]) [https://phabricator.wikimedia.org/T000000]

Icons

[edit]

You can add the "Recurring item" and "Advanced item" icons to the start of entries (before the entry's own marker), by copying these lines:Tech/News/Writers

  • [[File:Reload icon with two arrows.svg|12px|link=|class=skin-invert|{{safesubst:Tech news text/{{TRANSLATIONLANGUAGE}}|recurrent item}}]]
    • Recurrent item
  • [[File:Cog-icon-grey.svg|12px|link=|class=skin-invert|{{safesubst:Tech news text/{{TRANSLATIONLANGUAGE}}|advanced item}}]]
    • Advanced item
  • [[File:Maki-gift-15.svg|12px|link=|class=skin-invert|{{safesubst:Tech news text/{{TRANSLATIONLANGUAGE}}|wishlist item}}]]
    • Wishlist item

The deadlines

[edit]

For Contributors

[edit]

For the next Monday’s issue, the deadline is Wednesday at 23:59 UTC+0. [note 1]

We begin sending the newsletter to volunteer translators on Thursday. Entries submitted after the deadline or after the content has already been sent to translators disrupts the translation process. Entries submitted after the deadline will therefore be excluded from the newsletter unless there is a reason for the late submission which we can communicate to the translators.

In case you want to make a late addition, please don't add it to the newsletter directly. Post it on the Tech News talk page and notify the Tech News editorial team (especially Sandister) on the same talk page. Alternatively if you are staff or a contractor of the Wikimedia Foundation, please send your post and message to #talk-to-tech-news Slack channel.

For Translators

[edit]

To be sure to have your translation included for off-Meta distribution, please have it done by Monday 09:00 UTC+0.[note 1]

[edit]

Drafting and publication schedule

[edit]
See also: Tech/News/For contributors#When is the work done?

The current distribution date for the newsletter is Monday, during the UTC evening. This deadline is linked to from the upcoming issue.

Time What How
Monday to Wednesday Add draft content Add links to noteworthy changes, and if possible start writing their summaries. See Tech/News#contribute.

Thursday

 Draft the newsletter
  1. Open the Tech/News/Next edition's page.
  2. In the #user-notice board in Phabricator (That link shows "All" tasks that were "Updated in the last 8 days")
    1. Archive items from last week by moving them from the column "In current Tech/News draft" to the column "Archive".
    2. Review items in the column "Announce in next Tech/News"
    3. Review items in the column "To Triage"
    4. Review items in the column "Not ready to announce" to see how they have changed state, and if they are ready yet
    5. Move any items that are now included in this week's edition into the column "In current Tech/News draft"
    6. For all tasks:
      • If it hasn't already been done, then summarize the items in the edition.
      • If the task is unclear, then ask for suggested wording in the task (e.g. "Re: Tech News - What wording would you suggest as the content, and When should it be included? Thanks!").
  3. Review the threads on wikitech-l and the wikitech ambassadors list to see if there are any topics there that ought to be in Tech News.
  4. Add the latest Recently resolved community tasks section.
    1. Before saving, remove any rows about:
      1. "New upstream release" entries made by LibUp-bot.
      2. "Create project tag", and similar Phabricator minutiae.
      3. "GitLab account activation", and similar GitLab minutiae.
      4. "Stuck global rename" requests, and similar semi-private tasks.
    2. If there are any examples within the list that will be of widespread interest, summarize them ("For example, …").
  5. Check for new messages at Talk:Tech/News
  6. Check the incident documentation to find anything that would have had a noticeable effect on editors.
  7. Check for any new wiki creations.
    • But delay announcing until they've had time to setup a Main Page and import content from Incubator.
    • See generic examples in #Standardized lines above.
  8. Check the internal staff channels for any relevant entries (#general, #release, etc).
  9. Check if any databases switches (or any other changes not already covered) are listed on Wikitech wiki.
  10. Write and Format the content. See #Guidelines reminders about writing-style.
  11. Prepare the content for translation.
  12. Request the help of Wikimedia translators through their mailing list at translators-l@lists.wikimedia.org, to translate the early draft of the newsletter
    • Duplicate the last email. Update the Subject-line with a format like "Tech News 2026 - Issue 15", and the first two links.

This is an example of an email for the 15th edition of 2026 sent to translators-l: 

The latest tech newsletter is ready for early translation: https://meta.wikimedia.org/wiki/Tech/News/2026/15

Direct translation link:

https://meta.wikimedia.org/w/index.php?title=Special:Translate&group=page-Tech%2FNews%2F2026%2F15&action=page&filter=&action_source=translate_page

We plan to send the newsletter on Monday afternoon (UTC). The existing translations will be posted on the wikis in that language.

Deadlines:

https://meta.wikimedia.org/wiki/Tech/News/For_contributors#The_deadlines

See https://meta.wikimedia.org/wiki/Template:Tech_news_text for translating the recurring strings.

Let us know if you have any questions, comments or concerns. As always, we appreciate your help and feedback.

Friday

 Finalize and freeze the newsletter
  1. Open the Tech/News/Next edition's page.
  2. Make any final edits or changes needed – E.g. check for edits to #user-notice tasks in the last 32 hours.
  3. "Freeze" the issue by
    • removing the {{tech news draft}} template,
    • removing any empty sections,
    • marking the page for translation;
    After that, new items should be added to the next issue.
  4. Create a draft for next issue by clicking the Next link on the current issue's page
    • update the MediaWiki version number (example) incrementing it from last week,
    • and check for whether the train will be skipped the following week (calendar), in which case use the first of the #Standardized lines
  5. Update the latest and next redirects so that links from the main page work properly.
  6. Add to aggregate at Special:AggregateGroups (under "Tech")
  7. Notify translators on their mailing list, and highlight the changes between the early draft and the final version. If no changes were made, send a message anyway to let them know the content is now final. We usually use a variant of:
    The text of the newsletter is now final.
    No new entries have been added since yesterday.
    One new entry has been added since yesterday.
    There won't be any more changes; you can translate safely. Thanks!
Monday Distribute the newsletter

Distribution

[edit]
See an overview of the process in this 2014 blog post.

The distribution generally happens on Monday between 15:00–19:00 (UTC). If you change that time, update the deadline linked-to from the upcoming issue.

  1. Purge this page to fix the "week numbers" below.
  2. Open the edition and do the final change and checks
    1. Remove the "deadline" template, and mark for translation.
    2. Open all translations on Meta and check for these problems in case there was an error during the translation:
      • red links
        • (or blue links! You should have visited all the links, hence they're purple. E.g. Blue links might indicate an external link tvar that was misformatted with a "|" pipe)
      • broken tvars
      • random linebreaks
    3. Open each of their History pages (alt-shift-h), to thank the translators and check for problems. Do it as you check on pages, as there is a limit to the number of thank you can send.
  3. Test the message – Make a test delivery using a small test distribution list; the process is the same as for the actual delivery (described further below), except for the target list.
    1. Open Special:MassMessage in another tab or window
    2. In "Page or category containing list of pages to leave a message on": use the page-name of your test distribution list (examples by Johan, Quiddity, Trizek)
      • Test distribution list: A good rule of thumb is to check:
        • on the English Wikipedia
        • on another language with an existing translation
        • on another language without a translation (defaulting to English)
        • on an RTL wiki
        • on a multilingual wiki (e.g. mediawikiwiki, commons, wikidata, etc)
        • and on a community page in a localized namespace.
    3. In "Page to be sent as a message", add the page name of the issue you are delivering. Example:
      • Tech/News/2026/41
      • ↑ Check this week number is correct ↑
    4. Add the partial signature in the "Body of the message" using:
      • [[User:MediaWiki message delivery|MediaWiki message delivery]] ~~~~~
    5. Click on the Preview button
    6. Go to "Section of the page to be sent as subject:" and choose "technews-subject"
    7. Go to "Section of the page to be sent as message:" and choose "technews-2026-W41"
    8. Preview again
    9. If everything looks good, click the Send button on the page.
      • Test it exactly like you plan to send it, including the subject of the message.
      • Open each of the pages in your test distribution list, to check if they arrived properly.
        • (Pay attention to any new bluelinks or redlinks, which might indicate a problem)
      • If you see a mistake, test it again after you fixed the mistake.
  4. Launch the actual delivery
    1. Go through the same process as when testing, except in Step #2 replace the target delivery list with the actual one:
      • "Page or category containing list of pages to leave a message on":
        • Global message delivery/Targets/Tech ambassadors
    2. [...]
    3. Do a final check, and if everything looks good, click on the Send button on the page
    4. Check one or two of the delivered editions at local pages (especially a translated edition), to make sure it arrived successfully and that there were no overlooked errors.
  5. Wrap up
    1. Thank the translators on their mailing list at translators-l@lists.wikimedia.org. Reply to our own Friday post (topic: Tech News 2026 - Issue 41), to retain threading. Text to use:
      • Thank you all for your help, the newsletter has now been delivered (in N languages) to N pages.
    2. Send the English edition to wikitech-ambassadors@lists.wikimedia.org and wikitech-l@lists.wikimedia.org in an HTML e-mail (topic: Tech News 2026 - Issue 41).
      • Use private browsing/incognito mode to avoid leaking what pages you have visited (when copying, links you have visited may be copied with the purple visited link color)
      • Manually delete the icons (so that users blocking remote images in their email client don't get the annoying banner)
    3. Publish it on Diff (m:Diff (blog))
      1. Create a new blog post,
      2. copy & paste the content from the edition into the blog-post body,
      3. add a header:
        • Tech News 2026 - Issue 41
      4. categorize it with technology,
      5. tag it with tech news (use the autocomplete feature, otherwise it sometimes creates a new tag)
      6. select a "featured image" (search for "tech" or "rods" or "gears" for a few examples)
        • You can resize the image if you want, as Diff post images have a 1200x675 pixels format.
      7. select "Pending review" and click "Save as pending review". (or click "Publish" and "Submit for review".)
    4. For foundation staff handling distribution, publish it on #movement-communications on Slack to share internally.

Structural components of Tech/News

[edit]

Notes

[edit]
  1. ↑ a b Unfortunately, the UTC time will change with daylight saving time.
Retrieved from "https://meta.wikimedia.org/w/index.php?title=Tech/News/Manual&oldid=31092178"