刚来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. 简洁第一（这不是写手册，不需要按步骤每个入口都写；不一定要用主动态; 不一定要提到UI所有信息，提到关键字即可）2. 一定要写对用户的benefit. 3. 一定要细细体会后，用语言总结出来的话，不是机械地表面描述操作。4. 很多情况下，用表状态的形容词比用动词好。比如available with XX vs that XX supports)
Before:
Add VMs to Azure AD security groups through the Full Configuration interface. An action, Azure AD security group: Create new, is now available on the Machine Catalog setup > Machine Identities page when Azure Active Directory joined is selected as the VMs' identity type. Perform that action if you want to have the provisioned VMs automatically added to an Azure AD dynamic security group.
After:
Add VMs to Azure AD security groups through Full Configuration. An option, Azure AD security group, is now available when you create Azure AD joined VMs. The option lets you add the VMs to a dynamic Azure AD security group.
Comments: Emphasize the user task instead of the page where the new option appears.
Before:
Machine display name changed. In the Full Configuration interface, machine display names are now changed from the form “DomainNetBIOS name\machine account” to “Full domain name\machine account”. This change ensures unique machine identifiers when your environment has two or more domains that use the same NetBIOS name.
After:
Machine display name change. In the Full Configuration interface, machine display names now change from the “DomainNetBIOS name\machine account” to the “Full domain name\machine account” form. This change ensures unique machine identifiers when your environment has two or more domains that use the same NetBIOS name.
Comments:
1. Conciseness is more important than noun cluster.
2. The XXX format (the format, XXX, ) vs the format XXX
My wife Sally is healthy. (I have one than one wives. One of them, whose name is Sally, is health) -- The format XXX
My wife, Sally, is health. ( I have only one wife. Her name is Sally) -- The XXX format or the format, XXX,
Before:
More user authentication methods support in non-SSO scenarios. Previously, with single sign-on disabled, users could log on to Citrix Workspace app and a session using different user accounts. Starting with this release, users can log on to them using user accounts or smart cards. For more information, see Session launch credentials.
After:
Support for more user authentication methods in non-SSO scenarios. Previously, with single sign-on disabled, users could log on to Citrix Workspace app and to a session using different user accounts. Starting with this release, users can log on using user accounts or smart cards. For more information, see Session launch credentials.
Comment:
- Support for XXX vs XXX support: If XXX represents a lengthy phrase, use support for such as in the second version. Otherwise, use the latter, such as Windows 11 support.
- Adding the "to" makes the sentence parallel in structure and easy to understand.
- Omitting "to them" because they refer to CWA and session, but pronouns often identify them to the nearest noun although sometimes we ignore this rule if it is easy for users to identify what the pronoun is referred to.
Before:
Restart schedule support for single-session OS machines. Previously, the restart schedule feature was available only for multi-session OS machines. You can now apply it to single-session OS machines. For more information, see Create and manage restart schedules for machines in a delivery group.
After:
Restart schedule support for single-session OS machines. Previously, the restart schedule feature was available only for multi-session OS machines. It's now also available for single-session OS machines. You can now create restart schedules for delivery groups containing single-session OS machines. For more information, see Create and manage restart schedules for machines in a delivery group.
Comment:
We need to avoid abstract concept (such as apply in this case). Instead, providing instructional descriptions can make it more practical to readers. 而且，第一二句的对仗, 更好地让用户capture the differences. 改后版本后半部分提到如何achieve the goal briefly.
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.
Punchy and brief ! Sometimes leave out the mention of the new field name introduced in the new feature.
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.