Content translation/cxupdate style guide
This is a simple publishing and style guide for the Content Translation Update blog.
What to publish
[edit]The main purpose of this blog is to update the end-users about the state of the user-facing features as they are deployed on the production Wikimedia sites. In this regard it's similar to the weekly Tech News, but it's more detailed and focuses only on CX (and sadly it's not translated, but maybe will be in the future if there is demand and resources).
User-facing features include:
- Added, removed or upgraded machine translation engines.
- Machine translation engines failures and fixes.
- Changes in the behavior or the appearance of entry points.
- Changes in the functionality or appearance of the dashboard or the translation interface.
- Changes in the behavior of translation aids, such as link, image and category adaptation, formatting toolbar, etc.
- Changes that affect the wiki syntax of the published article.
- Significant measurable changes in performance.
User-facing features don't include:
- Minor styling changes - colors, font sizes, padding, etc.
- Code cleanup and refactoring (by definition refactoring doesn't change functionality).
- cxserver configuration and other deployment matters that don't directly affect user experience.
Stick to the reality of the deployment as closely as possible: look for the relevant changes directly in Gerrit.
When to publish
[edit]- Shortly after the deployment of the weekly train, with a summary of user-facing features deployed there. This deployment is largely prepared on Tuesday, so the post should be written on Wednesday. Any last minute user-facing changes added in SWAT on Thursday should be included.
- Shortly after every SWAT or emergency deployment.
Each new deployed feature or bugfix mentioned in the post must be tested in production before the publishing.
Style
[edit]- Start the weekly train post by "Month DD CX Update:", for example "July 30 CX Update:". After the colon mention up to three significant changes. The date in the beginning helps the user to know that it's a weekly post, and the descriptions give the highlights that should show that it's not too boring and repetitive.
- Whenever relevant, describe the previous broken behavior, and what got better.
- Add screenshots wherever relevant, but don't invest too much time into creating them ;)
- Usually, put links to relevant Phabricator tickets or Gerrit changes after the change description in the bullet lists. Write "(bug report)" or "(task description)" (for Phab) or "(code change)" (for Gerrit) in the end, make the whole parenthesized expression italic and link the text inside the parentheses. Prefer Phab tickets - they are usually written in less technical language. Linking from the text should be better, but often there's too much doubt about what parts to link, so instead of investing time into thinking about this, simply do this in the end of the list item.
- Try to come up with your own opening sentence. It doesn't have to be super-original, just make sure it's not the same every week.
- Before publishing a weekly post, change the permalink to a YYYY-MM-DD timestamp, for example https://cxupdate.wordpress.com/2015/07/30/2015-07-30/.