【Learn From Edits】What's new blu

刚来Citrix时，边总结别人的作品边仿写【工作总结】如何写What's New。现在写得多了，不像之前那么费劲啦。但仍有不小的提升空间。与Martin（My Manager)的每周一小时的1:1上，我会拿一些作品（通常是我没有十足把握的内容）与他一起线上review，他会read out loud，并与我一起修订，告诉我他之所以做这些修改。这是非常非常难得的机会，

除了管理职位外，他还是一位非常富有经验的writer，在Citrix做writer有20多年了。20多年前，Citrix的一位中国同事，建议他从localization转做writer，他说这改变了他的命运。他是瑞典人，18岁来到美国。1：1 有时间有富余时，他会分享他的人生与投资经历（可以说是赢家了）。60出头的他，单身，仍辛勤地工作着，日夜颠倒，为了照顾我们亚洲团队不在夜晚开会。扯远了...

我把before 与 after editing的内容记录总结下来，定期回顾，不断提升。语言不断投入时间，不断学习提高，相信总会有进度。-- 语言时常让我想放弃，但每到有所收获时，又重新振作，继续前进 for a better me.

经过几番与Jack公共编辑我的What's new, 我的体会是：1. 简洁第一（这不是写手册，不需要按步骤每个入口都写；不一定要用主动态）2. 一定要写对用户的benefit. 3. 一定要细细体会后，用语言总结出来的话，不是机械的表面的操作。4. 很多情况下，用表状态的形容词比用动词好。比如available with XX vs that XX supports)

Before:

Ability to import machine profiles from ARM template specs when creating machine catalogs in Microsoft Azure Resource Manager cloud environments. Previously, you could import machine profiles only from VMs you had created as machine profile VMs. With ARM template specs,  you can now share machine profiles across multiple subscriptions, which eliminates the need to create machine profile VMs in each subscription. For more information, see XXX.

After:

Ability to import machine profiles from ARM template specs. Previously, you could import machine profiles only from VMs you had created as machine profile VMs. Starting with this release, you can also import machine profiles from ARM template specs when creating machine catalogs in Microsoft Azure Resource Manager cloud environments. This enhancement allows you to share machine profiles across multiple subscriptions, which eliminates the need to create machine profile VMs in each subscription. For more information, see XXX.

Comment:

Short and clear are the rule of thumb. If the title is long, rewrite it.

Don't be afraid of losing some details: title is used to make the most important item outstanding from others.

No context no text. Judging from the keywords such as ARM template, users already have the context. So, in the title we can omit the long premise.

Before:

Info icon to notify you of an unverified hypervisor plug-in. When adding host connections in the Hosting node, in the Connection Type options, you can now see an info icon next to any hypervisor or cloud service whose hypervisor plug-in is not Citrix-verified. Clicking the info icon, you are informed to upgrade the hypervisor plug-in. For more information, see XXX.

After: 1st

Info icon to notify you of unverified hypervisor plug-ins. In the Hosting node > Connection Type options, you can now see an info icon next to any hypervisor or cloud service whose hypervisor plug-in is not Citrix-verified. After you hover over the info icon, the tooltip informs you to upgrade the hypervisor plug-in. For more information, see XXX. //Joy: the tooltip can't stand a thorough grammar review cos the tooltip is something that readers can't indicate.

After: 2nd

Info icon to notify you of unverified hypervisor plug-ins. When selecting a hypervisor or cloud service from the connection type list, you can now see an info icon next to it if its plug-in is not Citrix-verified. When you hover over the icon, a tooltip appears, informing you to upgrade the plug-in. For more information, see [Step 1. Connection](/en-us/citrix-virtual-apps-desktops-service/install-configure/connections.html#step-1-connection).

Comment:

To shorten the description part, Martin suggested stating the UI only instead of describing the action in UI. So the Italic words are omitted.

Avoid using passive voice.

The 2nd versions is based on Jack's edits. He omitted the entry point: Hosting node in the consideration that users are quite familiar with the usage. No context no text! --Sometimes, we can leave obvious things out.

Before:

Blade-style applies to Machine Catalogs and Policies nodes in Full Configuration. All nodes in Full Configuration now have blade-style wizards.

After:

Blade-style wizards applied to all nodes in Full Configuration. In this release, we applied blade-style wizards to the remaining Machine Catalogs and Policies nodes.

Comment:

To shorten the title and also focus on what readers really have interests in.

Before: Introduced a policy to automatically reattach VHDX disks in sessions

After: New policy to automatically reattach VHDX disks in sessions

Comment:

For headings, don’t use past tense to indicate what we did. That style is okay for tools but not for components/products.