tag:blogger.com,1999:blog-64204426421895849212024-02-07T02:41:45.553+00:00Agile DocumentationA blog about writing in agile environmentsRob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.comBlogger102125tag:blogger.com,1999:blog-6420442642189584921.post-28736885206090504502023-03-15T16:57:00.003+00:002023-03-16T18:58:20.769+00:00Power Automate: Use FIRST Instead of "Apply to each" When Pulling Out a Single Value<p><span style="font-family: arial;"><br /></span></p><p><table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto;"><tbody><tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjv2-I2WQFiWj6jiBnOYRwKQ7A86-9vm6-v_FYK8MfO3BnLWsdWjbJJMozeMAF6zyP-yBxUNkHJHnH4WQCiECnmJmxdNjlUtOUsVd_TUg5Ksg0weaJgBgnDrUqAp64KCQzwlSfC_lsn2XbV1SQLc3IB_CPL1Uj29h5YkLzqEpEUs8zLVF2Js18XhH6I/s4460/dusty-sky-with-palm-sihouettes-on-beach-at-sunset.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="3349" data-original-width="4460" height="481" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjv2-I2WQFiWj6jiBnOYRwKQ7A86-9vm6-v_FYK8MfO3BnLWsdWjbJJMozeMAF6zyP-yBxUNkHJHnH4WQCiECnmJmxdNjlUtOUsVd_TUg5Ksg0weaJgBgnDrUqAp64KCQzwlSfC_lsn2XbV1SQLc3IB_CPL1Uj29h5YkLzqEpEUs8zLVF2Js18XhH6I/w660-h481/dusty-sky-with-palm-sihouettes-on-beach-at-sunset.jpg" width="660" /></a></td></tr></tbody></table></p><table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto;"><tbody><tr><td class="tr-caption" style="text-align: center;"><span style="color: #999999; font-family: georgia;"><i>Credit: <a href="https://burst.shopify.com/@impatrickt" target="_blank">Patrick Tomasso</a></i></span></td></tr></tbody></table><p><span style="font-family: arial;">If you're returning rows from a spreadsheet or a SharePoint list, you normally use an "Apply to each" action to pull out the data.</span></p><p><span style="font-family: arial;">But when you use "Apply to each" the entire row is pulled into memory and this can be slow, especially if you've got a lot of columns. </span></p><p><span style="font-family: arial;">If there is only one row this isn't necessary; instead you can use the "First" expression, which is much quicker as it just loads a specific column value rather than the whole row.</span></p><p><span style="font-family: arial;">Let's say you're filtering on a unique refeerence number column called "URN" to return a specific row using an OData Filter Query, such as </span><span style="font-family: courier;">urn eq 'example'</span><span style="font-family: arial;">, and you want to get the value of a column from that row called "Start Date".</span></p><p></p><div style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEir4VPusD8lvo4QmfDn0N1TrikcCF99thqe63_ePxKgEqzLhKhG8DGRQl0zz1vRYCPTEsMmu40O-8GKFHt9iZiI5JqxcIVenE9BQBh8vpy3vx4T4ZdZG9KbZRe0_sXyCeOHKcNd-bAoHXtaWhiTNoETTeFgNTV2RgIQ_Z1sdxXGoq4aRbVU2UCNKZlc/s618/1%20List%20Rows%20Present.png"><img alt="A screenshot of a "List rows present in a table" action showing a filter query" border="0" data-original-height="278" data-original-width="618" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEir4VPusD8lvo4QmfDn0N1TrikcCF99thqe63_ePxKgEqzLhKhG8DGRQl0zz1vRYCPTEsMmu40O-8GKFHt9iZiI5JqxcIVenE9BQBh8vpy3vx4T4ZdZG9KbZRe0_sXyCeOHKcNd-bAoHXtaWhiTNoETTeFgNTV2RgIQ_Z1sdxXGoq4aRbVU2UCNKZlc/s16000/1%20List%20Rows%20Present.png" /></a></div><div class="separator" style="clear: both; text-align: center;"><br /></div><p></p><p><span style="font-family: arial;">Rather than using "Apply to each" to pull the value out, use the following expression in a Compose or Set Variable action:</span></p><p><span style="font-family: courier;">First(outputs('List_rows_present_in_a_table')?['body']?['value'])?['Start Date']</span></p><p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjT1nv_lyGbsfVOw8LYo7YFKp2Vjlj3WPL3Dz17m5FBtsauDuV0ivRrC4UPmH-3W3V3-hYtoBt159J5GKjM7xan5kDySLf4jo1xBlN0DCk-fC5oFmQEhliq-4A2bT52IZyy6ztAgNewZXtybaFCXL--wTD5V1GHePq_9XlJyPiR1S-Qj22m3LSmyINb/s642/2%20Expression.png" style="margin-left: 1em; margin-right: 1em;"><img alt="An "Initialize variable" action showing the FIRST expression" border="0" data-original-height="212" data-original-width="642" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjT1nv_lyGbsfVOw8LYo7YFKp2Vjlj3WPL3Dz17m5FBtsauDuV0ivRrC4UPmH-3W3V3-hYtoBt159J5GKjM7xan5kDySLf4jo1xBlN0DCk-fC5oFmQEhliq-4A2bT52IZyy6ztAgNewZXtybaFCXL--wTD5V1GHePq_9XlJyPiR1S-Qj22m3LSmyINb/s16000/2%20Expression.png" /></a></div><div><span style="font-family: arial;"><br /></span></div><div><span style="font-family: arial;">And now you've got the value you need without having to load all the rows - it's quicker, uses one less step, and is easy to implement.</span></div><span style="font-family: arial;"><br /></span><p></p><p><span style="font-family: arial;"><br /></span></p><p><span style="font-family: arial;"><br /></span></p><p><br /></p>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-62232080586862420412018-09-08T08:44:00.001+01:002018-09-09T08:43:08.260+01:00How To Bulk Publish in SharePoint (without using Site Content and Structure)<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjj3CNxJgqD7I5ZZgPJfbhhZVTQiHFIydsv7TktVxCiI5X88vY_KjD85i3z4Qf5nCv32O1jC7uws0DIkheOVvVq2vawi2vVNzMqMV__Ii6gM17cPZ94WEVqbC-HRPyIbPU4riItCFEJG_w/s1600/Printing+Press.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><span style="font-family: "verdana" , sans-serif;"><img border="0" data-original-height="1068" data-original-width="1600" height="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjj3CNxJgqD7I5ZZgPJfbhhZVTQiHFIydsv7TktVxCiI5X88vY_KjD85i3z4Qf5nCv32O1jC7uws0DIkheOVvVq2vawi2vVNzMqMV__Ii6gM17cPZ94WEVqbC-HRPyIbPU4riItCFEJG_w/s640/Printing+Press.jpg" width="640" /></span></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><div class="_3bJ2H CHExY">
<div class="_1l8RX _1ByhS">
<span style="font-family: "verdana" , sans-serif;">Photo by <a href="https://unsplash.com/photos/Tzm3Oyu_6sk?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Bank Phrom</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></div>
</div>
</td></tr>
</tbody></table>
<div style="text-align: center;">
<span style="font-family: "verdana" , sans-serif;"><br /></span></div>
<span style="font-family: "verdana" , sans-serif;">Back in June 2018, Microsoft announced that they were removing SharePoint Online's <a href="https://support.office.com/en-us/article/work-with-site-content-and-structure-30fcaad9-02b1-4347-8b03-e1ccc5a4c19f#bm4">Site Content and Structure page</a> in October 2018. This had some useful features in it, some of which are being replaced, some of which are not. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">One of Site Content and Structure's popular features is the ability to bulk publish all of the documents in a library to a major version. This is particularly useful if you only allow people with edit rights to see minor versions, and you want to publish a large number of documents at the same time, for example on the launch date of something.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">How can this be done once Site Content and Structure is no longer available?</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Let's go through the steps.</span><br />
<br />
<ol>
<li><span style="font-family: "verdana" , sans-serif;">Create a view that filters items based on
"Version contains .1" OR Version contains .2 OR [all the way up to]
"Version contains .9":</span><div style="text-align: left;">
<span style="clear: left; float: left; font-family: "verdana" , sans-serif; margin-bottom: 1em; margin-right: 1em;"><img border="0" data-original-height="501" data-original-width="734" height="435" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhayCRWlqUSlZDMcswDsGsmsno9Mbr5sqznYVkwRjaK54BTVlU4abLpC3pJVs6wpeaIDjIw3urghyphenhyphenlZu7EiaHjG_x-aUZ3MwKRwMCADHCoEFvfVwoPoRzPE7sMaWWgir750xa6hwxc2D4w/s640/Versions+for+Bulk+Publishing.png" width="640" /></span></div>
</li>
<li><span style="font-family: "verdana" , sans-serif;">Open the list, select this view and click <b>Return to classic experience.</b></span></li>
<li><span style="font-family: "verdana" , sans-serif;">Select all of the items in the list, open the <b>Files</b> tab and click <b>Check Out</b>.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Select all of the items in the list, open the <b>Files</b> tab and click <b>Check in</b>.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">In the <b>Check</b> <b>in</b> panel that opens, select the <b>Major version (publish)</b> radio button and click <b>OK</b></span></li>
</ol>
<div>
<span style="font-family: "verdana" , sans-serif;">Once you've created this view you can use it whenever it's needed. </span></div>
<div>
<span style="font-family: "verdana" , sans-serif;"><br /></span></div>
<div>
<span style="font-family: "verdana" , sans-serif;">You might think it would be easier to just create a view that says "Version does not contain .0", and you'd be right. Unfortunately, SharePoint views don't support "does not contain", so you have to create this filter the long way round, so to speak. If this is a common requirement for your users you can add this view to the libraries in your site template so </span><span style="font-family: "verdana" , sans-serif;">you don't have to keep reproducing it by hand every time </span><span style="font-family: "verdana" , sans-serif;">whenever you create a new site.</span></div>
<div>
<br /></div>
<div>
<span style="font-family: "verdana" , sans-serif;"><br /></span></div>
<div>
<div class="MsoNormal">
<o:p></o:p></div>
</div>
Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-44119769530205979372018-08-28T16:01:00.000+01:002018-08-28T16:01:33.385+01:00Some Word Articles for Those Hot Sunny Evenings<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjjkAgqBmy7E8AyL8z2sQX8VMxFACvsNd2P2P22r42y5hXI6CE2V2KF4AD15EcGJInD-QCFgGGHilSE8FwNVa7E83S2wKiD0n3AYZ4inDgL2rgYRCGDvHvD_urPB4Cx5EuCV_dyd5bITSw/s1600/adult-bench-business-man-272064.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="1067" data-original-width="1600" height="425" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjjkAgqBmy7E8AyL8z2sQX8VMxFACvsNd2P2P22r42y5hXI6CE2V2KF4AD15EcGJInD-QCFgGGHilSE8FwNVa7E83S2wKiD0n3AYZ4inDgL2rgYRCGDvHvD_urPB4Cx5EuCV_dyd5bITSw/s640/adult-bench-business-man-272064.jpg" width="640" /></a></div>
<div style="text-align: center;">
<span style="font-family: Verdana, sans-serif;"><br /></span></div>
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">Thanks to the <a href="https://www.fifa.com/worldcup/">World Cup</a> (turned out <a href="http://time.com/5334946/world-cup-2018-england-its-coming-home-memes/">it wasn't coming home</a>, but it was brilliant nonetheless) and a <a href="https://en.wikipedia.org/wiki/2018_British_Isles_heat_wave">summer heatwave</a>, my output on AgileDocumentation from June through to August hasn't been high. But I've still been writing, just not here. </span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">The fine folks over at <a href="https://www.howtogeek.com/">How-To-Geek</a> asked me to write some articles on Office 365 for them and I'm only too happy to oblige. They've got a much bigger readership than this little old blog and long time readers will know I like to spread the O365 love, especially about <a href="http://www.agiledocumentation.co.uk/2015/11/why-do-some-writers-dislike-word.html">Word</a>. I've got a few SharePoint articles planned for the coming weeks, but in the meantime here's some articles from How-To-Geek to keep your whistles whetted:</span><br />
<br />
<ul>
<li><span style="font-family: Verdana, sans-serif;"><a href="https://www.howtogeek.com/360136/how-to-control-line-and-paragraph-spacing-in-microsoft-word/">How to Control Line and Paragraph Spacing in Microsoft Word</a></span></li>
<li><span style="font-family: Verdana, sans-serif;"><a href="https://www.howtogeek.com/361306/how-to-wrap-text-around-pictures-and-other-objects-in-microsoft-word/">How to Wrap Text Around Pictures and Other Illustrations in Microsoft Word</a></span></li>
<li><span style="font-family: Verdana, sans-serif;"><a href="https://www.howtogeek.com/363208/how-to-position-images-in-a-word-document/">How to Position Images and Other Objects in Microsoft Word</a></span></li>
<li><span style="font-family: Verdana, sans-serif;"><a href="https://www.howtogeek.com/361463/how-to-reduce-the-size-of-a-word-document-apart-from-compressing-images/">How to Reduce the Size of a Microsoft Word Document</a></span></li>
</ul>
Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-10948443335054221782018-06-24T18:26:00.000+01:002018-07-28T09:46:00.809+01:00SharePoint Permissions Part 5 - External Sharing<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh4tdOVmvu7AuhlKBVswZpxCnyj6UIjdMPeUtf_SkU_4afWezDYQG6LYupE1gOqSWAcQzfa4MzDJxamN3QCRMUdZRKI9x9Ry4psfyMGiIG655qN5pGcLAbKIeVTurjnfm8ZaibzQokyc8A/s1600/External+Sharing.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1067" data-original-width="1600" height="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh4tdOVmvu7AuhlKBVswZpxCnyj6UIjdMPeUtf_SkU_4afWezDYQG6LYupE1gOqSWAcQzfa4MzDJxamN3QCRMUdZRKI9x9Ry4psfyMGiIG655qN5pGcLAbKIeVTurjnfm8ZaibzQokyc8A/s640/External+Sharing.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><div class="_3bJ2H CHExY">
<div class="_1l8RX _1ByhS">
<span style="font-family: "verdana" , sans-serif;">Photo by <a href="https://unsplash.com/photos/FWVMhUa_wbY?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">bruce mars</a> on <a href="https://unsplash.com/search/photos/sharing?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></div>
</div>
</td></tr>
</tbody></table>
<div style="text-align: center;">
<br /></div>
<span style="font-family: "verdana" , sans-serif;">In </span><a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-1.html" style="font-family: verdana, sans-serif;">part 1</a><span style="font-family: "verdana" , sans-serif;"> we looked at how permissions inherit and cascade, and using SharePoint groups to avoid inheritance problems. In </span><a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-2-using.html" style="font-family: verdana, sans-serif;">part 2</a><span style="font-family: "verdana" , sans-serif;"> we covered using mail-enabled security groups in O365 to make your permissions more consistent. </span><a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-3-setting.html" style="font-family: verdana, sans-serif;">Part 3</a><span style="font-family: "verdana" , sans-serif;"> focused on reducing your maintenance burden by using dynamic security group membership, and <a href="https://www.agiledocumentation.co.uk/2018/06/sharepoint-permissions-part-4-creating.html">part 4</a> was all about the creation of a permissions strategy and accompanying design guide.</span><br />
<br style="font-family: verdana, sans-serif;" />
<span style="font-family: "verdana" , sans-serif;">This has all been very internal user-focused. What if you want to allow external users to access your site? Or, perhaps more importantly, what if you want to make sure that only some things (or even nothing) can be shared with external users? It's time to talk about <i>external access</i>.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">External access is controlled at 2 levels: the <b>tenant</b>, and the <b>site collection</b>. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Unlike site permissions, which cascade down and can be changed to be less or more restrictive at each of the site collection, site, library/list, folder and document levels, external sharing cannot be made less restrictive at the site collection level. So your site collections cannot allow more external sharing rights than the tenant allows. On the other hand, you can make your site collections more restrictive than the tenant, so if external access is allowed at the tenant level, you can prevent it at the site collection level if you want. (For reasons which will become obvious quite soon, this is probably the setup you'll want to use.) But these are the only 2 levels at which you can change the external access settings - all of the sites, libraries/lists, folders and documents under a site collection will get their external permission settings from the site collection.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Let's start with preventing any external access to your SharePoint instance, because this is the easy part. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">To do this, you just need to turn off external access in the tenant settings by going to <b>O365 Admin</b> > <b>SharePoint </b>> <b>Sharing </b>and selecting the <b>Don't allow sharing outside your organisation</b> radio button.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">If you do this then no-one will be able to share a document from a SharePoint site, nor will adding an external user to a site give them access (because when you add a user to a site, even as an administrator, you are actually sharing the site with them). But there is a big caveat:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div style="text-align: center;">
<span style="font-family: "verdana" , sans-serif;"><b><i>Turning off external sharing at the tenant level stops users sharing externally from OneDrive as well.</i></b></span></div>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Now, that might be fine for you, in which case congratulations, you're done here, don't bother reading the rest of this article.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">But if you want your users to be able to share externally from OneDrive, or need to allow one or more teams to share externally from SharePoint, then this won't work for you. If you're wondering why this affects OneDrive, it's because OneDrive is a series of SharePoint sites, one for each of your users. If you go to <b>O365 Admin </b>> <b>OneDrive </b>> <b>Sharing</b>, you'll see a note under <b>External sharing</b> that says "Your sharing settings for OneDrive can't be more permissive than your setting for SharePoint". Hence, if you turn off external sharing for SharePoint, you're also turning it off for OneDrive.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">In a scenario where even a single user needs to be able to share externally from OneDrive or SharePoint, you'll need to turn external sharing on at the tenant level. Your options are as follows:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhwu71Nv9gqSDVin9fVT2J6q1YC2vc1q942OUJkIqaqrLGLikkVA5tolAcadD281jgSl_ruLioXMn_HSaO8K9m7_j0DjO3cq8zjxKhqD45bRIwWh_TB4T06kOeCGz78ZYSbvVtXSwNecfU/s1600/O365+Admin+-+Sharing.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="366" data-original-width="943" height="248" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhwu71Nv9gqSDVin9fVT2J6q1YC2vc1q942OUJkIqaqrLGLikkVA5tolAcadD281jgSl_ruLioXMn_HSaO8K9m7_j0DjO3cq8zjxKhqD45bRIwWh_TB4T06kOeCGz78ZYSbvVtXSwNecfU/s640/O365+Admin+-+Sharing.png" width="640" /></a></div>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">The options are described in detail by Microsoft <a href="https://support.office.com/en-us/article/turn-external-sharing-on-or-off-for-sharepoint-online-6288296a-b6b7-4ea4-b4ed-c297bf833e30">here</a>, where you'll also find an explanation of the other parameters that limit which external users can be shared with, and what those external users can do with their shared files.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">One section of the parameters not covered by that Microsoft page is the sharing by security groups section:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgmIq4ThqCSd5mKlqJ1xF1wKbwk1SdnKYKFKJV2VUyoF2nul7muMdpBQhFBIf2SkFZhbK0MdNlLq5fxL26OtduqRJnDqTC9nNrBG5LMDCQ0kZjh9dS8140Ma7eNWODYH6ZUCeOwH09_i-I/s1600/O365+Admin+-+Sharing+and+Security+groups.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="122" data-original-width="1106" height="68" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgmIq4ThqCSd5mKlqJ1xF1wKbwk1SdnKYKFKJV2VUyoF2nul7muMdpBQhFBIf2SkFZhbK0MdNlLq5fxL26OtduqRJnDqTC9nNrBG5LMDCQ0kZjh9dS8140Ma7eNWODYH6ZUCeOwH09_i-I/s640/O365+Admin+-+Sharing+and+Security+groups.png" width="640" /></a></div>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">This is known more formally - and unintuitively - as "per-group sharing". It allows you to chose which security groups are allowed to share externally (the second option will only appear if you've chosen to allow users to share anonymous links) and you can find out more about it from Microsoft <a href="https://techcommunity.microsoft.com/t5/Microsoft-OneDrive-Blog/New-feature-Per-Group-Sharing-Controls/ba-p/74780">here</a>. Note that it also affects OneDrive, so it gives you a little more control there too.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">But whatever parameters you've set, once you've allowed external sharing at the tenant level you now need to set up your site collections appropriately as well.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">First things first, lets look at how you allow or not allow external sharing in a site collection. Go to </span><b style="font-family: verdana, sans-serif;">O365 Admin </b><span style="font-family: "verdana" , sans-serif;">> </span><b style="font-family: verdana, sans-serif;">SharePoint </b><span style="font-family: "verdana" , sans-serif;">> and the SharePoint admin portal will open in the </span><b style="font-family: verdana, sans-serif;">Site Collections</b><span style="font-family: "verdana" , sans-serif;"> </span><span style="font-family: "verdana" , sans-serif;">option. Select the site using the checkbox next to it on the left hand side and click <b>Sharing </b>from the toolbar at the top:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEih1LiP6WS9uNREJsp4kec38GT1Gedx7ccZHBsrRmulcUs90L1KGsrRkIwELDZ14BhiAwZzeApCfKOgZHMvY5u0gxr-E2NfbqH13x_bRlmkrTVR-BLJIhXr_OGXEY7T9tSE3pwX7f3nqNw/s1600/Site+Collection+Sharing.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><span style="font-family: "verdana" , sans-serif;"><img border="0" data-original-height="195" data-original-width="788" height="98" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEih1LiP6WS9uNREJsp4kec38GT1Gedx7ccZHBsrRmulcUs90L1KGsrRkIwELDZ14BhiAwZzeApCfKOgZHMvY5u0gxr-E2NfbqH13x_bRlmkrTVR-BLJIhXr_OGXEY7T9tSE3pwX7f3nqNw/s400/Site+Collection+Sharing.png" width="400" /></span></a></div>
<br />
<span style="font-family: "verdana" , sans-serif;">If you don't want your site collection to allow external sharing, select the </span><b style="font-family: Verdana, sans-serif;">Don't allow sharing outside your organization</b><span style="font-family: "verdana" , sans-serif;"> radio button, click </span><b style="font-family: Verdana, sans-serif;">Save</b><span style="font-family: "verdana" , sans-serif;">, and you're done: </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjBabm4tJrjnU9MiSws2t8BM7Kj87gTaXsbl5OmDZlLJig5X6XkYrge-jeASLAOWoScjFvfEnnvs-oW4caxyNPjX5Azes2Pg1EimmpuhVdsgLSZ5CXbbvaFhIW9qjjFrRpdR7arEZCY4GU/s1600/Sharing+outisde+your+company.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="396" data-original-width="811" height="195" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjBabm4tJrjnU9MiSws2t8BM7Kj87gTaXsbl5OmDZlLJig5X6XkYrge-jeASLAOWoScjFvfEnnvs-oW4caxyNPjX5Azes2Pg1EimmpuhVdsgLSZ5CXbbvaFhIW9qjjFrRpdR7arEZCY4GU/s400/Sharing+outisde+your+company.png" width="400" /></a></div>
<br />
<span style="font-family: "verdana" , sans-serif;">If your permissions strategy doesn't generally allow external sharing, set this in your template site and it will be copied through to any sites that use that template. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">If you do want to allow external sharing t</span><span style="font-family: "verdana" , sans-serif;">he full explanation of what each of these options will and will not allow can be found on </span><a href="https://support.office.com/en-us/article/turn-external-sharing-on-or-off-for-sharepoint-online-6288296a-b6b7-4ea4-b4ed-c297bf833e30" style="font-family: Verdana, sans-serif;">this Microsoft page</a><span style="font-family: "verdana" , sans-serif;">. T</span><span style="font-family: "verdana" , sans-serif;">he first thing to note is that the <b>Sharing outside your company </b>options are missing some options that are in the tenant level options. </span><span style="font-family: "verdana" , sans-serif;">At the tenant level you could decide if anonymous links expire, and if so after how long, and also whether anonymous links allow anonymous users to view or edit. You can't change this at the site collection level. These are tenant-wide </span><span style="font-family: "verdana" , sans-serif;">settings that every site collection will inherit. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">You can then choose the <b>Default link type</b> and <b>Default link permission</b>, both of which by default will inherit from the default organisation setting, but can be changed.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">You've then got the ability to whitelist, or blacklist, domains which people can share with:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjplwIio4bPQSCsoFdyFD4lWHxyXMhsoOuUbeChaLS6wlcHXGJwb7hr4ecAhrxjbF2apSZrNxa7ge7dlxfDppdbD_cQAXsO3J21ZvKRHLZDx7TeVIHKmhHeYiHdPuzxYbKwIh_k-0ng4Os/s1600/Limit+external+sharing+by+domain.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="310" data-original-width="801" height="153" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjplwIio4bPQSCsoFdyFD4lWHxyXMhsoOuUbeChaLS6wlcHXGJwb7hr4ecAhrxjbF2apSZrNxa7ge7dlxfDppdbD_cQAXsO3J21ZvKRHLZDx7TeVIHKmhHeYiHdPuzxYbKwIh_k-0ng4Os/s400/Limit+external+sharing+by+domain.png" width="400" /></a></div>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">You can either whitelist certain domains (users can only share externally with users who have an email address in a whitelisted domain) or blacklist certain domains (users can share with any external users except those with an email address in a blacklisted domain). You can't do both at the site collection level, although you can have a blacklist at tenant level and a whitelist at the site collection level.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">The blacklisting is a rather odd option, in that a user from a blacklisted domain could simply create a free email address from a service that isn't blacklisted, and use that. So there would be no point blacklisting a competitor service when a user who really wanted to share with a competitor could just tell the competitor to create a new email address from a common service like gmail or outlook.com. This is especially true when the blacklist must be filled in by hand, rather than syncing automatically with, for example, the untrusted site list used by a security program. The use case for blacklisting therefore seems a bit lacking at the moment.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">The whitelisting make perfect sense, however. One site collection can only share with your external regulator, for example, while another site collection can only share with your parent company, and so on. This gives the administrators a way to allow sharing with trusted organisations without worrying about people sharing things with whomever they want.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">These lists can also be setup at the tenant level as part of the additional settings I mentioned. If you've set this up at the tenant level, then <a href="https://support.office.com/en-us/article/restricted-domains-sharing-in-sharepoint-online-and-onedrive-for-business-5d7589cd-0997-4a00-a2ba-2320ec49c4e9?ui=en-US&rs=en-US&ad=US">this Microsoft page</a> details the priorities, which I'll list here for ease:</span><br />
<ul xmlns:antixss="urn:AntiXSSExtensions">
<li><span style="font-family: "verdana" , sans-serif;">In the case of conflicts, the tenant-level configuration takes precedence over the site collection configuration.</span></li>
<li>
<span style="font-family: "verdana" , sans-serif;">If a tenant-level allow list is configured, then you can only
configure an allow list at the site collection level. The site
collection allow list must be a subset of the tenant allow list.</span><br />
</li>
<li>
<span style="font-family: "verdana" , sans-serif;">If a tenant-level deny list is configured, then you can
configure either an allow list or a deny list at the site collection
level.</span><br />
</li>
<li>
<span style="font-family: "verdana" , sans-serif;">For individual OneDrive for Business site collections, you can only configure this setting by using the <a class="ocpExternalLink" href="https://technet.microsoft.com/library/fp161394.aspx" ms.cmpgrp="content" ms.pgarea="Body" target="_blank">Set-SPOSite</a>Windows PowerShell cmdlet.</span></li>
</ul>
<span style="font-family: "verdana" , sans-serif;">Note that the logic outlined above means that if a domain is blacklisted at the tenant level, this will overrule that same domain being whitelisted at the site collection level. </span><span style="font-family: "verdana" , sans-serif;">You can list up to 1000 domains at the tenant level, but only 60 at the site collection level. </span><span style="font-family: "verdana" , sans-serif;"> </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Following on from this, you've also go the option to prevent users from sharing with external users without owner approval:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh4JGwZ62R2SsJmnd8N_0m-rUagv-BNGWxd-dZBxVkECgP8SeTVBrMFQW6RIPIk6WqPLO3ayt0UYFefM-B2fM_JNKSj4ulipUiF1pKaQO6xYV4HwTBvXvSDjgbOVNx4OjdHJWfskARjrh4/s1600/Allowing+non-owners+to+invite+new+users.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="259" data-original-width="802" height="129" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh4JGwZ62R2SsJmnd8N_0m-rUagv-BNGWxd-dZBxVkECgP8SeTVBrMFQW6RIPIk6WqPLO3ayt0UYFefM-B2fM_JNKSj4ulipUiF1pKaQO6xYV4HwTBvXvSDjgbOVNx4OjdHJWfskARjrh4/s400/Allowing+non-owners+to+invite+new+users.png" width="400" /></a></div>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">You'll have to decide if you want to change the default from allowing users to share freely, to requiring site owner approval to share. This applies to ALL sites in the site collection and ALL sharing, whether it's internal or external. </span><span style="font-family: "verdana" , sans-serif;">If your <a href="https://www.agiledocumentation.co.uk/2018/06/sharepoint-permissions-part-4-creating.html">permissions strategy</a> has the administrators as site owners,</span><span style="font-family: "verdana" , sans-serif;"> this will create a lot of work, and you'd need to consider giving an information owner enhanced rights to handle this workload.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Once you've set the permissions for your site collection appropriate, click <b>Save</b>.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">If you want to know what's being shared externally (which can often be a good way to tell if your permissions are correct) you can <a href="https://support.office.com/en-gb/article/keyword-queries-and-search-conditions-for-content-search-c4639c2e-7223-4302-8e0d-b6e10f1c3be3?ui=en-US&rs=en-GB&ad=GB#external">search for content that's been shared externally</a> in the Security & Compliance Centre.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">And that's the mechanics of external sharing. Hopefully this series on SharePoint Permissions has been useful for you. If there's a permissions issue you want to me to cover, drop a comment below and I'll do my best to oblige.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">[Update: I was planning to write a 6th installment on SharePoint and AIP (Azure Information Protection) but there's a lot of new work going on there at the moment. Luckily the World Cup was on, so I could spend a month watching that, but we're still waiting for some new SharePoint-related AIP functions, so I'll come back to this topic another time.]</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-54251119204492658032018-06-02T12:07:00.000+01:002018-06-16T08:35:25.692+01:00SharePoint Permissions Part 4 - Creating a Permissions Strategy and Design Guide<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgp-QcELPFoyAqKGCWqOkPkl1E3JNuyYzG8aLJE9YgLNqMprCPpylsLCNBNUiXPImbSt0rKSjAnsmbqGggLOL8eC-6uxE-Iodf6ELBofSQuGd-83cZDKc7QGv2ury2JLRVpCj4VGE5CvNw/s1600/Chess+Board.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1067" data-original-width="1600" height="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgp-QcELPFoyAqKGCWqOkPkl1E3JNuyYzG8aLJE9YgLNqMprCPpylsLCNBNUiXPImbSt0rKSjAnsmbqGggLOL8eC-6uxE-Iodf6ELBofSQuGd-83cZDKc7QGv2ury2JLRVpCj4VGE5CvNw/s640/Chess+Board.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><div class="_3bJ2H CHExY">
<div class="_1l8RX _1ByhS">
<span style="font-family: "verdana" , sans-serif;">Photo by <a href="https://unsplash.com/photos/86qvlyDfMvo?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">rawpixel</a> on <a href="https://unsplash.com/search/photos/chess-board?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></div>
</div>
</td></tr>
</tbody></table>
<div style="text-align: center;">
<span style="background-color: white;"><span style="color: #1f1f1f; font-family: "verdana" , sans-serif; font-size: 14px;"><br /></span></span></div>
<span style="font-family: "verdana" , sans-serif;">In <a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-1.html">part 1</a> we looked at how permissions inherit and cascade, and using SharePoint groups to avoid inheritance problems. In <a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-2-using.html">part 2</a> we covered using mail-enabled security groups in O365 to make your permissions more consistent. In <a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-3-setting.html">part 3</a> we looked at reducing your maintenance burden by using dynamic security group membership.<br /><br />These 3 articles covered the technical side of setting up permissions that don't break the permission inheritance rules, adding a user to a single security group so they automatically get permissions to many sites at once, and how to add users to security groups automatically by setting up dynamic group membership in AAD.<br /><br />This is the <i>how</i> of setting up permissions, but it's also important to understand the <i>why</i> of setting up permissions. If you don't understand why you're setting your permissions up the way you are, you'll just be providing permissions on an ad hoc basis without any structure. This will store up problems for the future because your permissions scheme won't be consistent, and the rationale for any given permissions can only be explained by the person who set them up. Why is Joe Bloggs in this security group when he's not a member of that department? Why does Jane Bloggs have Edit rights to this library when everyone else has Contribute rights? What's this security group used for? Why does every site have different permission levels to all the other sites? These kind of questions should not come up - and if they do come up, they should be easy to answer - if you have a <i>permissions strategy</i>.<br /><br />As always when creating a strategy, the first question to ask is "What do we want to achieve?" Are you looking for minimal admin burden? The removal of data silos? Highly restrictive permissions to protect sensitive information? The chances are you want all of these things, but in different areas. So your strategy should lay down some general principles that guide you towards the most important goal for a particular site, but also ensure a consistent, structured approach to permissions.<br /><br />Some useful principles:</span><br />
<ul>
<li><span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><b>Only restrict a site if necessary.</b> Most of your sites can be open, that is, everyone in your organisation has read access to the site. You might have a library restricted to a particular team, but otherwise the site is readable (and importantly, searchable) to the whole organisation. This helps breakdown data silos and reduces the admin burden. A few sites will be closed, that is, only those people who need access will be given it, and this is done where there is sensitive data.</span></span></li>
<li><span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><b>The higher the permission level, the less people should have it.</b> This means the group with the highest permission level - Full Control - should also be the group with the fewest members. Normally this is your System Admin group, commonly the people responsible for maintaining the structure and security of your SharePoint instance. Conversely, the group with Read access will be the group with the largest membership (normally the built-in "Everyone except external users" group).</span></span></li>
<li><span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><b style="font-size: 14px;">Minimal complexity for maximum performance.</b><span style="font-size: 14px;"> The more unique permissions you have in a library, the lower the performance. This is not such a big deal for small libraries, but in larger libraries where each individual document could have unique permissions provided by users sharing things, it can cause a drop off in performance. There's a good discussion of this problem </span><a href="https://www.titus.com/blog/2011/04/sharepoint-2010-capacity-and-performance-recommendations-permission-planning/" style="font-size: 14px;">here</a><span style="font-size: 14px;">, and although the article is talking about SharePoint 2010 on-premise, the basic elements of load-balancers, web servers, databases and CPUs haven't changed significantly. The performance can depreciate on both </span><a href="https://sharepoint.stackexchange.com/questions/193549/would-a-large-number-of-unique-permissions-cause-performance-issues" style="font-size: 14px;">the indexing crawl</a><span style="font-size: 14px;"> and <a href="https://support.office.com/en-gb/article/plan-your-permissions-strategy-c6183e49-9287-4689-999e-0d3f817a41a3#__toc268492731">the site performance</a> itself.</span></span></li>
<li><span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><b style="font-size: 14px;">Breaking inheritance is the last resort, not the first.</b><span style="font-size: 14px;"> If you have sensitive information in several folders across different libraries and you need to restrict access to these, but the rest of your libraries and documents can be read by anyone, you'll have to break inheritance for all of those folders. That's the easy way to "fix" the access immediately, but in the long run it's just more maintenance complication and potential access problems to troubleshoot. When you're designing the site take these issues in mind and create a single library for sensitive information. This will make the permissions much simpler and correspondingly easier to maintain.</span></span></li>
<li><span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><b>Security by design, not by accident.</b> Your organisation has to comply with a regulatory framework, whether that be industry- specific (e.g. </span><a href="https://www.investopedia.com/terms/s/sarbanesoxleyact.asp" style="font-size: 14px;">Sarbanes-Oxley</a><span style="font-size: 14px;">) country-specific (e.g. local data protection laws) or trading-bloc specific (e.g. </span><a href="https://www.eugdpr.org/" style="font-size: 14px;">GDPR</a><span style="font-size: 14px;">). A logical, well thought out permissions strategy can help prevent breaches, and, in case of a breach, also demonstrate that you incorporated sensible security measures into your design from the outset, which can help lower penalties and maintain your organisation's reputation.</span></span></li>
<li><span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><b style="font-size: 14px;">All permissions are documented.</b><span style="font-size: 14px;"> Out of all the principles, this is probably the most important. It's certainly the most useful, because even if you have no other principles to follow then at least you've got information about what permissions have been applied and why. In the design document for each site - you've got a design document for each site, right? - set aside a standard section explaining what SharePoint groups you've used with what permission level you've applied, which security groups are in each SharePoint group, and an explanation of any unusual or unique permissions, and any deviations from your standards. This information will be invaluable in a whole host of different future scenarios.</span></span></li>
</ul>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">A permissions strategy is part of the governance of your SharePoint implementation. It should be written down and accessible to the whole organisation. All administrators who are able to add or amend permissions from the library level up should be familiar with it, and no site collection or site design should be applied to a site unless it meets the requirements of the strategy.</span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><br /></span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">But whilst writing it and making it accessible is important, it's not enough. What doesn't often get talked about is the need to convert your strategy into practical actions. It can be difficult to understand how the strategy should be applied in day-to-day work, especially for people more used to solving technical problems than creating and interpreting policy.</span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><br /></span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">So the strategy document should also have an accompanying <i>permissions design guide </i>that translates the strategy into concrete actions and requirements. The guide should include what default SharePoint groups are in your site template and why, under what circumstances it's acceptable to deviate from these groups, naming conventions for security groups, and so on. </span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><br /></span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">The contents of your permissions design guide will vary according to your strategy (e.g. you may prioritise accessibility over security, or vice versa) and the overarching design decisions you've made (e.g. what your naming conventions will be, what default SharePoint groups you use, etc), so just as there is no "correct" strategy, there is no "correct" design guide. The design guide is there to provide your designers with the practical information they need to implement your strategy. Think of it as a tactical handbook which, if followed by everyone, will allow you to realise your strategy successfully.</span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><br /></span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">A design guide takes a long time to write and is a living document. As new functionality is added to SharePoint, the design guide will change and grow. It would be nice to say "don't build anything until your design guide is finished!" but that's unrealistic in a production environment. Instead, start by working out your strategic principles and getting all of the stakeholders on board. Then at least you're all working from the same starting point. This is doubly important if you're well into a SharePoint implementation or you've got a mature implementation you want to improve (and realistically most people reading this will be in these positions). </span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><br /></span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">The further into your implementation you are, the more potential work there will be to implement a strategy and corresponding design guide on your pre-existing sites, so don't expect to make sweeping changes. An incremental approach that gradually improves things has a better chance of success than a radical redrawing of your permissions to fit a new strategy. Start by creating a strategy and corresponding design guide that can be used for any new sites from now on, and when it's stable and well-understood you can look to implement it in existing sites over time.</span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;"><br /></span></span></div>
<div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="font-size: 14px;">The technical work of creating and implementing the permissions strategy is part of the admin's role. In the next article we'll take a look at user sharing, how to modify the out of the box settings (both at tenant and site level) and what you can and can't stop your users doing.</span></span></div>
<div>
<br /></div>
<span style="color: #1f1f1f; font-family: "verdana" , sans-serif;"><span style="background-color: white; font-size: 14px;"><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-52420989225022761382018-05-20T12:57:00.000+01:002018-05-20T12:57:29.171+01:00SharePoint Permissions Part 3 - Setting up Dynamic Security Group Membership<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjFYJE9PM68pfWkrRiL4ErF3_laEaEjpvlVwfBZbKgdUilmgP4U_OondYvcvpMSbBcn-Ux-IXLWDF4NlXCUrttxgBUMDq26bAnxcaN3oAE3LDKfNsj-A9u_0GOql3OU3KrfP1INRXeQyfw/s1600/Dynamic+security+group.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1065" data-original-width="1600" height="425" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjFYJE9PM68pfWkrRiL4ErF3_laEaEjpvlVwfBZbKgdUilmgP4U_OondYvcvpMSbBcn-Ux-IXLWDF4NlXCUrttxgBUMDq26bAnxcaN3oAE3LDKfNsj-A9u_0GOql3OU3KrfP1INRXeQyfw/s640/Dynamic+security+group.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><div class="_3bJ2H CHExY">
<div class="_1l8RX _1ByhS">
<span style="font-family: Verdana, sans-serif;">Photo by <a href="https://unsplash.com/photos/iDGwopsIOI0?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Henry Be</a> on <a href="https://unsplash.com/search/photos/security?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></div>
</div>
</td></tr>
</tbody></table>
<div style="text-align: center;">
<span style="font-family: Verdana, sans-serif;"><br /></span></div>
<span style="font-family: Verdana, sans-serif;">In <a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-1.html">part 1</a> we looked at how permissions inherit and cascade, and using SharePoint groups to avoid inheritance problems. In <a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-2-using.html">part 2</a> we covered using mail-enabled security groups in O365 to make your permissions more consistent. Now it's time to look at reducing your maintenance burden by using <i>dynamic security group membership</i>.</span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">This sounds quite complicated, but in reality it simply means letting Azure Active Directory (AAD) handle group membership based on attributes like department or role.</span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">If you set this up then when people join, move, or leave they will automatically be added to or removed from security groups. If you're using security groups in SharePoint, this will lower your maintenance burden considerably. It also allows you to set up a permissions strategy that doesn't require everyone who deals with user accounts to know the ins and outs of what permissions any given user requires. Dynamic security group membership is a "set it and forget it" system where AAD will handle putting people in whichever security groups are appropriate based on their user profile attributes.</span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">This doesn't mean it doesn't need management, as you'll need to add the dynamic membership requirements to new groups, and change the requirements for existing groups if/when your organisation's structure changes. But, after you've set it up for the existing groups, that's <i>all you'll have to do</i> in the future.</span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">Here's how to add dynamic membership to a group.</span><br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<ol>
<li><span style="font-family: Verdana, sans-serif;">Open AAD and find your security group:<br /><br /><div class="separator" style="clear: both; text-align: center;">
<img border="0" data-original-height="248" data-original-width="588" height="267" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiM9l6FNlkk7RUg3W_WeFvbFV0Dm1RqeLmo15Sab5wZ7VxhmW-Pt5_gDC2qg_JVHC6aZAsmcJ2NgRaQo7vWxZmODLzhY7JcJ6E4_d3CzbKA7ica9t1ziyunNe3Tnx22RXiw0CylUXVhX04/s640/1+-+Select+your+group.png" width="640" /></div>
<div style="text-align: center;">
<br /></div>
(If you've not done this before, open the O365 Admin portal, select Azure Active Directory in the left hand launch panel, and there is a "Find a group" option in the default dashboard view.)<br /><div class="separator" style="clear: both; text-align: center;">
</div>
<div style="text-align: left;">
<br /></div>
</span></li>
<li><span style="font-family: Verdana, sans-serif;">Click on the group to select it. The menu on the left hand side will display the options for that specific group. Click <b>Properties</b>:<br /><br /><div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi-c5mZWd9RyVh5G65UqoCRjUOxO0Pi6cAlp3pfsu5aFy8w4KD9GHGsM1pyXbq-XdfCRkk0XbVaCXj3MoJNf1EVdwW2nLhJqNXIde47DtTQrfc7QyYmb03cV9RQ1aE1BUGDyHSlRoI7UWg/s1600/2+-+Select+Properties.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="378" data-original-width="314" height="400" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi-c5mZWd9RyVh5G65UqoCRjUOxO0Pi6cAlp3pfsu5aFy8w4KD9GHGsM1pyXbq-XdfCRkk0XbVaCXj3MoJNf1EVdwW2nLhJqNXIde47DtTQrfc7QyYmb03cV9RQ1aE1BUGDyHSlRoI7UWg/s400/2+-+Select+Properties.png" width="331" /></a></div>
<div style="text-align: center;">
<br /></div>
</span></li>
<li><span style="font-family: Verdana, sans-serif;">The <b>Membership type</b> of your group will be displayed:<br /><br /><div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjUqZu5LBm9hhisJ6zj-_j5I6SIXeSMUbQyuvpEZ_myIK-mD3-0mr0cA6kMrap0ygsXHSFX_KIKoZa_VOJZ-bqr7QiFEVNNTC6Zv_2_Tc4n4nFfUa1CxhKdjlfioXKA-LLT9BX0FXS9PAE/s1600/3+-+Select+Membership+type.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="419" data-original-width="480" height="348" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjUqZu5LBm9hhisJ6zj-_j5I6SIXeSMUbQyuvpEZ_myIK-mD3-0mr0cA6kMrap0ygsXHSFX_KIKoZa_VOJZ-bqr7QiFEVNNTC6Zv_2_Tc4n4nFfUa1CxhKdjlfioXKA-LLT9BX0FXS9PAE/s400/3+-+Select+Membership+type.png" width="400" /></a></div>
<div style="text-align: center;">
<br /></div>
</span></li>
<li><span style="font-family: Verdana, sans-serif;">Change the <b>Membership type</b> from "Assigned" to "Dynamic User". A confirmation dialogue will pop up; click <b>Yes </b>on this:<br /><br /><b><span style="color: red;">WARNING:</span></b> Doing this will remove existing users from your group.<br /><br /><div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjkdzy2hQGxQS_3bGHSRyHX17xVg1j7THBHocjbLf6y7Tc1ttAL-wVwoCEjJpd4s_jXqm2mHF2MDHYyBtvynFrEBATReqtzuq3lmU72ilvNNYOb0WFz2JTtzn-3n2XR6dr7k1MILdlxh04/s1600/4+-+Change+Membership+type.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="817" data-original-width="777" height="640" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjkdzy2hQGxQS_3bGHSRyHX17xVg1j7THBHocjbLf6y7Tc1ttAL-wVwoCEjJpd4s_jXqm2mHF2MDHYyBtvynFrEBATReqtzuq3lmU72ilvNNYOb0WFz2JTtzn-3n2XR6dr7k1MILdlxh04/s640/4+-+Change+Membership+type.png" width="608" /></a></div>
<div style="text-align: left;">
<br /></div>
</span></li>
<li><span style="font-family: Verdana, sans-serif;">Click the new <b>Add dynamic query</b> option that has appeared at the bottom of the Properties panel, and create your rule from the dropdowns:<br /><br /><div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhInqVbwxnDCG31-evv_u1nhRyT_0mAP__u8j2aS0_sWk9C3zjDjKPcrLRO_apINw-4m83qv5QXRVa1sFBrsViACP_NiBRRpvo7kOoVlsdeNiZTI-vkfncayy9v6raYCzYj1NvBuxxM0tI/s1600/5+-+Add+query.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="254" data-original-width="744" height="217" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhInqVbwxnDCG31-evv_u1nhRyT_0mAP__u8j2aS0_sWk9C3zjDjKPcrLRO_apINw-4m83qv5QXRVa1sFBrsViACP_NiBRRpvo7kOoVlsdeNiZTI-vkfncayy9v6raYCzYj1NvBuxxM0tI/s640/5+-+Add+query.png" width="640" /></a></div>
<div style="text-align: left;">
<br /></div>
</span></li>
<li><span style="font-family: Verdana, sans-serif;">Click <b>Add query</b> at the bottom of the panel to add the query to your group. AAD will then populate the group membership with all users who match your query.</span></li>
</ol>
<span style="font-family: Verdana, sans-serif;">If you want to add more than one query (e.g. department = Sales AND Location = New York) then instead of adding the query through the dropdowns you'll need to click on the <b>Advanced rule </b>tab. This provides a code window for you to enter a more complicated query. </span><div>
<span style="font-family: Verdana, sans-serif;"><br /></span></div>
<div>
<span style="font-family: Verdana, sans-serif;">Microsoft have provided <a href="https://docs.microsoft.com/en-us/azure/active-directory/active-directory-groups-dynamic-membership-azure-portal">a thorough overview of the syntax and valid terms</a> for advanced queries which I encourage you to work through. It might appear intimidating initially (especially if you're not used to command line or PowerShell scripting) but it's really quite simple once you understand the logic. Being able to write multi-part queries will significantly increase your options for dynamic membership, especially if you have situations where some, but not all, members of a team need to be in a group.</span></div>
<div>
<span style="font-family: Verdana, sans-serif;"><br /></span></div>
<div>
<span style="font-family: Verdana, sans-serif;">Once you've added the appropriate membership rule to a group, you've finished. Your group now has a dynamic membership that will change automatically based on user attributes.</span></div>
<div>
<span style="font-family: Verdana, sans-serif;"><br /></span></div>
<div>
<span style="font-family: Verdana, sans-serif;">Between SharePoint groups, security groups, and dynamic group membership, you've got all the tools you need to make sure that the right users have the right access to the right SharePoint areas, all done automatically based on their user attributes. However, knowing how to do this is just the technical side of permissions. You also need to understand who should have access to what, and why. This is the function of a <i>permissions strategy</i>, which we'll look at next.</span></div>
<div>
<div style="text-align: left;">
<br /></div>
<br /></div>
Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-85055417731338356922018-05-12T11:39:00.000+01:002018-06-01T07:23:51.609+01:00SharePoint Permissions Part 2 - Using Security Groups<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjchoGPjdvLJpiUiGtOETavfQrcAVjO4cmajIwu3wvTXMhpqbPCCMxPy3WHgqDXXIOme-FeMTCtUXXx2bWpmiQCJUdKXCyFf3AW-uG9rruMrkeqGkdaD-cTIWitb2rJTn2q7GRZeE4nDEo/s1600/security+groups.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1022" data-original-width="1600" height="408" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjchoGPjdvLJpiUiGtOETavfQrcAVjO4cmajIwu3wvTXMhpqbPCCMxPy3WHgqDXXIOme-FeMTCtUXXx2bWpmiQCJUdKXCyFf3AW-uG9rruMrkeqGkdaD-cTIWitb2rJTn2q7GRZeE4nDEo/s640/security+groups.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><div class="_3bJ2H CHExY">
<div class="_1l8RX _1ByhS">
<span style="font-family: "verdana" , sans-serif; font-size: x-small;">Photo by <a href="https://unsplash.com/photos/vWI1kTcMcDI?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Alex Block</a> on <a href="https://unsplash.com/search/photos/sorted?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></div>
</div>
</td></tr>
</tbody></table>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">In <a href="https://www.agiledocumentation.co.uk/2018/05/sharepoint-permissions-part-1.html">Part 1</a> of this series we looked at user groups in SharePoint sites, and how they allow you to add member permissions without breaking inheritance. Now we're going to take this a step further and look at adding groups of users to your SharePoint groups, rather than individual members.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Firstly, why would you want to give permissions to a group of users all at once, rather than individuals? There are a number of reasons:</span><br />
<br />
<ol>
<li><span style="font-family: "verdana" , sans-serif;">It cuts down on your work by allowing you to add/amend permissions for multiple users at once.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">You can provide <i>role-based security</i>, which means giving permissions to users based on their role, by using 1 group for each role.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Your permissions will be more consistent, as everyone in a group will have exactly the same permissions.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">A group can be given permission to more than one site, which means adding a new user is as simple as adding them to a group, which then gives them permissions to multiple sites.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Security groups can also be used to give users access to shared mailboxes, and Yammer and O365 groups, have specific permissions for documents labelled through Azure Information Protection, and various other elements of the O365 family.</span></li>
</ol>
<span style="font-family: "verdana" , sans-serif;">
A simple example is having an Administrators group, which your SharePoint administrators are a member of. If you add this group to the Owners group in your site template, then every time an admin creates a new site using that template, all of the administrators will be in the Owners group for the new site. (I'll cover creating and deploying a site template in a future article).</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">How do you practically create one of these groups? O365 allows admins to create security groups, and these security groups can then be added to SharePoint sites as if they were users. </span><span style="font-family: "verdana" , sans-serif;">Security groups are <a href="https://support.office.com/en-us/article/Create-edit-or-delete-a-security-group-in-the-Office-365-admin-center-55C96B32-E086-4C9E-948B-A018B44510CB">created in the O365 Admin portal</a> and contain whichever users you choose. They can then be given permissions to a SharePoint site collection (or site, list, library, folder or document). </span><span style="font-family: "verdana" , sans-serif;">So if you create a security group called Administrators, you can then select this security group when adding a user to the Owners group in your SharePoint site.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">When you create a security group in O365, you have an option of selecting either "security group" or "mail-enabled security group". There is no difference between these, except that you can send email to a mail-enabled security group and it will be sent to the members, which you can't do with a security group. I haven't yet come across a SharePoint permissions use case where this has made a functional difference, unless you want to be able to send a mail to the group when you change their permissions. But I still recommend mail-enabled security groups, because it future-proofs your implementation in case you hit a use case where you do need to mail the group.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Make sure that when you create your mail-enabled security group you turn OFF the "Allow people outside of my organization to send email to this Mail-Enabled security group" setting. This setting is on by default for mail-enabled security groups, distribution lists, and O365 groups, presumably because Microsoft feel the majority of use cases call for this functionality. There are pros and cons of this for distribution lists and O365 groups, but why would you want people outside your organisation to a) know your security group names (which could be useful information for someone trying to breach your security), and b) send that security group an email? Unless you've got a good answer to these 2 questions, turn this option off.</span><br />
<br />
<span style="font-family: "verdana" , sans-serif;">At the time of writing the O365 Admin portal doesn't distinguish between different types of group very well. So when you're looking in the Groups option there is no way to tell if "Administrators" is a security group, a mail-enabled security group, or just a plain old O365 group, unless you set the right filter. This doesn't seem like a big deal, but when you spend a lot of time working with groups, and your users create lots of O365 groups for collaborating, it gets rather frustrating looking through the Groups list and not knowing what type most of them are. There's also no way to tell what a security group is used for unless you open it and look at the description, which you and your colleagues probably aren't as fastidious about filling in as you should be (I'm not judging, I forget to do it just as often as the next admin). </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">To combat this problem you should use naming conventions for your security groups. Something like "SG-[role name]" will work fine, assuming you're doing role-based security. You can also/instead incorporate a team name, a function name, or whatever works for you. But do this up front, and get your admins to stick to it as much as possible. It'll make your work a lot easier over the years, especially if you have a lot of joiners/leavers/movers, or you regularly have to create new sites. There's also - currently - no way to tell where a security group is used unless you're willing <a href="https://social.technet.microsoft.com/wiki/contents/articles/31071.get-all-groups-in-a-site-collection-using-powershell.aspx">to use PowerShell</a>, so good naming conventions and descriptions will help you keep track of your security groups.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Now that you're using security groups to add users to SharePoint groups, the next step is to look at reducing your maintenance overhead by introducing <i>dynamic group membership</i>. We'll look at this in the next article.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-46051981174199619702018-05-07T21:05:00.000+01:002018-05-12T09:49:33.724+01:00SharePoint Permissions Part 1 - Understanding Inheritance and Cascading<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjCkHA0oezEsr-JAoLrJkEF6EY4ltx9IR8PT1hwO2wOX0o7EsB8fFkaClfvsj6M4-Jukb3XC7IDakwfeMxLd_5dwT7eLpn0l9cnU21zFQ-YWg7QZzYbBf5mAcg3RCJHteLdmPg7ULzOntU/s1600/Cascading+security.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1067" data-original-width="1600" height="425" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjCkHA0oezEsr-JAoLrJkEF6EY4ltx9IR8PT1hwO2wOX0o7EsB8fFkaClfvsj6M4-Jukb3XC7IDakwfeMxLd_5dwT7eLpn0l9cnU21zFQ-YWg7QZzYbBf5mAcg3RCJHteLdmPg7ULzOntU/s640/Cascading+security.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-family: "verdana" , sans-serif; font-size: x-small;">Photo by <a href="https://unsplash.com/photos/bBavss4ZQcA?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="text-align: start;">Jon Moore</a><span style="text-align: start;"> on </span><a href="https://unsplash.com/search/photos/security?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="text-align: start;">Unsplash</a></span></td></tr>
</tbody></table>
<br />
<span style="font-family: "verdana" , sans-serif;">SharePoint permissions are a common source of confusion and frustration. This isn't because adding permissions for a new user is particularly difficult for an admin (although I'll cover one way to do that below), and nor is it because sharing a document with someone is particularly difficult for a user (although I'll cover that in a future article). It's because it's very common to find yourself in a situation where you've given the correct permissions to a user, but they still can't see what you expect them to see.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Fear not though, because once you understand how permissions work you'll be able to fix your problems and prevent them happening in the future. (Note: we'll be going through permissions for team sites - sites with lists and libraries - not Communications sites or the recently introduced Hub sites. That's for a different time.)</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">To understand how SharePoint permissions work, you need to understand the <i>hierarchy of objects</i>, as well as <i>inheritance</i> and <i>cascading</i>. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">The <i>hierarchy of objects</i> in SharePoint is the equivalent of a family tree. You have a node at the top (the parents), with nodes underneath (the children), nodes underneath them (the grandchildren), and so on. In SharePoint the hierarchy is:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh94bqHwz0FkoQrNeA8rAAIQKWuCQPjulOYRp0oj-DbzgnivdXxuREbM4Rv_YuVoYi1WJQ9IyKWr4QYqKFQTuV83PW_wuRC5FV4wfT-uNxYtx2RD0TLO7HrPC1X8gg3BKTrW0mZ1r946VA/s1600/Hierarchy+of+Objects.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="353" data-original-width="290" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh94bqHwz0FkoQrNeA8rAAIQKWuCQPjulOYRp0oj-DbzgnivdXxuREbM4Rv_YuVoYi1WJQ9IyKWr4QYqKFQTuV83PW_wuRC5FV4wfT-uNxYtx2RD0TLO7HrPC1X8gg3BKTrW0mZ1r946VA/s1600/Hierarchy+of+Objects.png" /></a></div>
<br />
<span style="font-family: "verdana" , sans-serif;">The permissions for each of these nodes are <i>inherited </i>from the node above (the parent). The Document node inherits permissions from the Folder node, which inherits from the Library node, and so on up to the Site Collection node. (If you're not using Folders then the Document node will inherit from the Library node.)</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">The converse of inheritance is <i>cascading</i>, that is, the permissions cascade down from the node above to the node below. When you give a user permission to view a site, that permission cascades down to the library, then cascades down to the folder, then down to the individual documents.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Ok, so far so good: You create a site collection, give permission to people to view it, and they'll be able to view every site, list, library, folder and document underneath that site collection.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">But that is the simplest possible option, and assumes a) that you don't need to give specific permissions to any particular object, b) that you won't give anyone else permissions to a specific object in the future and c) that no user will share a folder or document with anyone. If any of those things happen then you'll find that the permissions aren't doing what you expected.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">The reason for this is quite simple, and is at the heart of understanding SharePoint permissions: <b>Giving unique permissions to an object breaks the inheritance</b>. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">This means that if you, for example, give permissions to a user to see a specific library, the inheritance is broken. So when you change the permissions in the site or the site collection, those changes won't cascade down to the library that has unique permissions. Let's work through an example.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">You create a site collection with yourself as Primary Site Collection Administrator. Your site collection has one site, and 3 libraries called TestLib1, TestLib2, and TestLib3. Each library has a folder called TestFolder1, TestFolder2, and TestFolder3 respectively, and each folder has a document called TestDoc1, TestDoc2 and TestDoc3 respectively. Diagrammatically:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEijQtzKZeVaRYDDP9PvKvIfeXbWe8N1ZNX-8cSfoN6FnUF4-Nor6W1NeqSNdOta7__Z9DC5zjFaCsrKyplpHUjsMF0jRoA8bSEXWjl58-rhVumLAoTtRoUnqIwcfEhwsBJTeP5UEt5tokM/s1600/Example+1.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="342" data-original-width="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEijQtzKZeVaRYDDP9PvKvIfeXbWe8N1ZNX-8cSfoN6FnUF4-Nor6W1NeqSNdOta7__Z9DC5zjFaCsrKyplpHUjsMF0jRoA8bSEXWjl58-rhVumLAoTtRoUnqIwcfEhwsBJTeP5UEt5tokM/s1600/Example+1.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
<span style="font-family: "verdana" , sans-serif;">You give Alice and Bob edit permissions at the site level. This cascades down to the nodes below, shown here as <b><span style="color: #6aa84f;">green </span></b>nodes:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjpDDcm0oWU9vtOzbzcuTKG0HoFZkdcj6UzXct5Dc28KOnCUmbW0gfPOxtE6jxdb_tNHu_1LrNTyiPSs_4g4096IQuGfPtGN0SlZRBe1fyQRLlhLz2j0xhDGNdMVU2x-8OJVNDM7G0K1ZU/s1600/Example+2.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="341" data-original-width="431" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjpDDcm0oWU9vtOzbzcuTKG0HoFZkdcj6UzXct5Dc28KOnCUmbW0gfPOxtE6jxdb_tNHu_1LrNTyiPSs_4g4096IQuGfPtGN0SlZRBe1fyQRLlhLz2j0xhDGNdMVU2x-8OJVNDM7G0K1ZU/s1600/Example+2.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
<span style="font-family: "verdana" , sans-serif;">Alice and Bob have edit permissions to all of the green nodes. If they - or you - add additional libraries, folders or documents then all 3 of you will be able to see the new objects, because the permissions will cascade down to those objects from the site. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Now you decide to allow Charlotte to have access, but only to TestLib3. This permission cascades down to the folder and document. Charlotte's permissions are shown here as <span style="color: orange;"><b>orange </b></span>nodes:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg-b7Xr1qqaMIpNhkG1l8eOZkvshiVo-VjZE2txPxihhyphenhypheng-rhMJY4NKR47LrQWYfDcCkGkFk3rdLF9h0wIqgC-Ohbc1mn3M_q2ZrYOz1dO13cYZAYAVSwrMqx4eVxp_N-TYHb7RXHujZ6M/s1600/Example+3.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="344" data-original-width="427" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg-b7Xr1qqaMIpNhkG1l8eOZkvshiVo-VjZE2txPxihhyphenhypheng-rhMJY4NKR47LrQWYfDcCkGkFk3rdLF9h0wIqgC-Ohbc1mn3M_q2ZrYOz1dO13cYZAYAVSwrMqx4eVxp_N-TYHb7RXHujZ6M/s1600/Example+3.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
<span style="font-family: "verdana" , sans-serif;">Now Alice, Bob and Charlotte can all see TestLib3 and the folder and document underneath it, but only Alice and Bob can see TestLib1 and TestLib2. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Now you give permission to Dave to the whole site - in other words, you want him to have the same access as Alice and Bob. So you give him permission to see the site, and.....he can only see TestLib1 and TestLib2, and the folders and documents contained within them, shown in <b><span style="color: red;">red </span></b>below:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhjk9pOF19gOgiRUcARvkGgL3_UBKMpLGBnBYyyqHZOfuyzfavT7J9jG3zR42NnnyhuE-rddX_IgqLm8dSMXidYLY-z_w2Y7LYBzAWyQnrsxw5KORWjiz24DL7BQJKsklIJJVhdcTsTRL0/s1600/Example+4.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="344" data-original-width="430" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhjk9pOF19gOgiRUcARvkGgL3_UBKMpLGBnBYyyqHZOfuyzfavT7J9jG3zR42NnnyhuE-rddX_IgqLm8dSMXidYLY-z_w2Y7LYBzAWyQnrsxw5KORWjiz24DL7BQJKsklIJJVhdcTsTRL0/s1600/Example+4.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
<span style="font-family: "verdana" , sans-serif;">Why? </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><i>Because by giving TestLib3 unique permissions - for Charlotte - you broke the inheritance, so permission changes at the site level will not cascade down to TestLib3.</i></span><br />
<br />
<span style="font-family: "verdana" , sans-serif;">Now imagine that Dave shared TestFolder1 with someone else in the organisation. You give Ellie permission to the site, and her permissions are shown in <span style="color: purple;"><b>purple</b></span>:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhshDkR7woPqgaN04ijz6KlDY5ZtdwV1hyU2rlGssi7zJv2BYoo6vjTdkIRq-W7ad5YjJ3wTvl0_Igr8FeiolsRYngDZEliUwP9P45uB3sw_06JRZOVzJiDDPxdcX6fJb70z9mmR5JQ4zQ/s1600/Example+5.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="342" data-original-width="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhshDkR7woPqgaN04ijz6KlDY5ZtdwV1hyU2rlGssi7zJv2BYoo6vjTdkIRq-W7ad5YjJ3wTvl0_Igr8FeiolsRYngDZEliUwP9P45uB3sw_06JRZOVzJiDDPxdcX6fJb70z9mmR5JQ4zQ/s1600/Example+5.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
<span style="font-family: "verdana" , sans-serif;">Because Dave shared a folder (a very common action for users to perform), the inheritance</span><span style="font-family: "verdana" , sans-serif;"> for that folder is broken, and permission to it (and the document it contains) no longer cascades down.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">To make matters more confusing, the inheritance that <i>is </i>working means that if Dave adds TestFolder1a to TestLib1, Ellie will be able to see it, because TestFolder1a will inherit permissions from its parent, TestLib1:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj_xz0OuoVF1Wx67ZtG5gQpLgiGkIebtKVs6M2RcjbBl8NBVJwnUH0zw_9d2TeMH0fHp4dTGSiHdW72q8Oq44uAVy-WpM4xoRNgS3QjCSkktZ6B1302d7LRca6rauqBzsyS8xgE8vt0wdA/s1600/Example+6.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="348" data-original-width="572" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEj_xz0OuoVF1Wx67ZtG5gQpLgiGkIebtKVs6M2RcjbBl8NBVJwnUH0zw_9d2TeMH0fHp4dTGSiHdW72q8Oq44uAVy-WpM4xoRNgS3QjCSkktZ6B1302d7LRca6rauqBzsyS8xgE8vt0wdA/s1600/Example+6.png" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<br />
<span style="font-family: "verdana" , sans-serif;">The situation now is that:</span><br />
<br />
<ul>
<li><span style="font-family: "verdana" , sans-serif;">Alice and Bob can see the site, all 3 TestLibs and the folders and documents contained in them.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Charlotte can only see TestLib3 and the folder and document within it.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Dave can only see TestLib1 and TestLib2, and the folders and documents within them.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Ellie can see TestLib2, along with the folder and document in it, as well as TestLib1 and TestFolder1a, but not TestFolder1 and the document in it. </span></li>
</ul>
<br />
<span style="font-family: "verdana" , sans-serif;">Oh, and if you remove Alice's permissions by mistake, then give her those exact same permissions back....she'll have the same permissions as Ellie, because of all the breaks in inheritance.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">It should be easy to see how complicated this can get. At this stage you're already in a mess, and if you have an organisation with hundreds of users and a few sites, it's almost impossible <i>not</i> to get in this mess. </span><br />
<br />
<span style="font-family: "verdana" , sans-serif;">However, there is a simple solution to stop this mess happening: </span><b style="font-family: Verdana, sans-serif;">Groups</b><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">If you give access to a group, then you can add and remove users from that group without breaking inheritance because the group always has permissions. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">To take a simple example, you might create a group that has Admin rights to the site and a group that has Edit rights to the site. These permissions will cascade, and all lists, libraries, folders and documents will inherit those rights. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">In the example shown in the diagrams, you would be in the Admin group and Alice and Bob would be in the Edit group. If you give Charlotte edit rights to just TestLib3, and then add Dave to the Edit group, he will now have access to all 3 libraries because he is a member of a group that already has access to them. After Dave shares TestFolder 1, you add Ellie to the Edit group, and again she has access to all 3 libraries and all of the folders and documents in them because she is a member of a group that already has access to them. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">But if you then gave Frank edit permissions to the site as an individual, rather than adding him to the Edit group, he wouldn't be able to see TestLib3 (because you broke the inheritance when you gave Charlotte edit rights to it), nor would he be able to see TestFolder1 or the document in it (because Dave broke the inheritance when he shared TestFolder1).</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">So groups allow you to maintain your intended permissions no matter which user you add to them or in what order the users are added. To add a group, go to <b>Site Settings</b> > <b>Site Permissions </b>and click <b>Create Group </b>in the ribbon. However, you'll find that there are already a number of default groups there, as per <a href="https://support.office.com/en-us/article/Understanding-SharePoint-groups-94D9B261-161E-4ACE-829E-ECA1C8CD2EB8#__toc339543059">this list</a> from Microsoft, and you may find the the ones you want are already there. You can delete any you don't need, or create any that you do.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">It's common to just use the Owners, Members and Visitors groups, with Full Control, Edit and Read rights respectively. This is something that Microsoft suggests, but it's by no means required. Set up whatever groups you need! If you want to know more about each of the default groups and what permissions they provide, there is a full list <a href="https://support.office.com/en-us/article/understanding-permission-levels-in-sharepoint-87ecbb0e-6550-491a-8826-c075e4859848?ui=en-US&rs=en-US&ad=US">here</a>, under the Default Permission Levels dropdown.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">Next time we'll talk about using security groups to make your security both more robust and more manageable.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-79960715576057284932018-04-28T22:28:00.000+01:002018-06-30T16:34:51.823+01:00Something-As-A-Service in the Cloud<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhCL6gSDap3-g9iRThxP9eU5lgjPO-1xkwOWs0l46vsFpOVBssKX9xPEZlvjx6Lv63UaNhT-nfY6MAVN5UlBp59HKutpaM505kiG0mB0KPo3FphGy2qYHmRK-GTwYckuo-i9x_zmqhhI_Q/s1600/cloud+computing.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1068" data-original-width="1600" height="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhCL6gSDap3-g9iRThxP9eU5lgjPO-1xkwOWs0l46vsFpOVBssKX9xPEZlvjx6Lv63UaNhT-nfY6MAVN5UlBp59HKutpaM505kiG0mB0KPo3FphGy2qYHmRK-GTwYckuo-i9x_zmqhhI_Q/s640/cloud+computing.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-family: "verdana" , sans-serif;">Source: <a href="https://www.pexels.com/photo/nature-laptop-outside-macbook-6508/">Pexels</a></span></td></tr>
</tbody></table>
<div style="text-align: center;">
<span style="font-family: "verdana" , sans-serif;"><br /></span></div>
<span style="font-family: "verdana" , sans-serif;">I'm going to be writing quite a bit about Azure, Office 365 and SharePoint over the next few months. The initialisms IAAS, PAAS and SAAS will come up from time to time, so it would be helpful to explain these terms in advance:</span><br />
<br />
<ul>
<li><span style="font-family: "verdana" , sans-serif;"><b>IAAS </b>- Infrastructure As A Service</span></li>
<li><span style="font-family: "verdana" , sans-serif;"><b>PAAS </b>- Platform As A Service</span></li>
<li><span style="font-family: "verdana" , sans-serif;"><b>SAAS </b>- Software As A Service</span></li>
</ul>
<br />
<span style="font-family: "verdana" , sans-serif;">Before we talk about the Infrastructure, Platform, and Software parts, let's talk about the as-a-service part. What does this mean?</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">To understand as-a-service, you need to know what <i>cloud computing</i> is. This has been a buzzword for a good few years now, and it's the backbone of as-a-service. Wikipedia provides a good <a href="https://en.wikipedia.org/wiki/Cloud_computing">definition</a>:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<div style="text-align: center;">
<span style="font-family: "verdana" , sans-serif;">"Cloud computing is an information technology paradigm that enables ubiquitous access to shared pools of configurable system resources and higher-level services that can be rapidly provisioned with minimal management effort, often over the Internet. Cloud computing relies on sharing of resources to achieve coherence and economies of scale, similar to a public utility."</span></div>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">In less technical terms, cloud computing providers have huge racks of servers loaded with useful tools like databases, storage, load-balancers, web servers, and software. They then lease space on these servers to remote users, along with access to the (usually pre-configured) tools. This is referred to as AAS, or As A Service. It's important to understand that cloud computing is a <i>service provision model</i>, not a generic term to refer to remote computers, which it's often misunderstood to mean. Cloud computing is what's used to deliver AAS.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">AAS is in contrast to "on-premise" where the servers, databases, storage, etc are all physically located within a company. It's much cheaper to lease space on a server with access to the tools you need than it is to buy, configure and mantain all the servers and tools yourself, especially if you only need access for a short or ill-defined period of time. Think of AAS as the digital equivalent of hiring a van - they buy the van, service it, clean it and repair it, and different people hire the van as and when they need it, then return it. The van leasing company has the costs but makes a profit once the hiring fees have covered those costs, and you get the van you need for a relatively small outlay without any of the hassle and cost of having to actually buy a van. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">So, cloud computing providers lease space and tools <i>as a service</i>, but different users want different services. Therefore there are different <i>service models</i> of AAS, of which the 3 standard ones are IAAS, PAAS and SAAS. These service models are defined by the National Institute of Standards and Technology (an agency of the American Department of Commerce) in their <a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-145.pdf">NIST Definition of Cloud Computing</a> (link to PDF). This is a surprisingly readable 7-page document which is a model of economy and information, and if you're at all interested in cloud computing or AAS then I encourage you to spend a few minutes reading it.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">In short, the service models explain which parts of the tech stack the vendor is responsible for, with the obvious correlation that the customer is responsible for the other parts. Here's a diagram showing how IAAS, PAAS and SAAS divide up the responsibilities between the vendor and the customer, with On-Premise included for comparison:</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjr9GGleYnmCxRjc05MzqH__wmztsJdJnLh-ZYsIFguzo2EbBEt2g-QxpdYH08T2P-qjxkMGis72N0raupqTnYIp_aJSIUcjekQ1TN573SKjDXtaQBvGJfLxxXZZPCSb49Y1kPL5EzDkII/s1600/IAAS+vs+PAAS+vs+SAAS.png" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="508" data-original-width="979" height="331" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjr9GGleYnmCxRjc05MzqH__wmztsJdJnLh-ZYsIFguzo2EbBEt2g-QxpdYH08T2P-qjxkMGis72N0raupqTnYIp_aJSIUcjekQ1TN573SKjDXtaQBvGJfLxxXZZPCSb49Y1kPL5EzDkII/s640/IAAS+vs+PAAS+vs+SAAS.png" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><span style="font-family: "verdana" , sans-serif; font-size: x-small;">Reproduced from Kevin Remde's <a href="https://blogs.technet.microsoft.com/kevinremde/2011/04/03/saas-paas-and-iaas-oh-my-cloudy-april-part-3/" style="text-align: start;">Technet blog</a></span></td></tr>
</tbody></table>
<span style="font-family: "verdana" , sans-serif;">With On-Premise, you manage all of the hardware and all of the software in the tech stack.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span><span style="font-family: "verdana" , sans-serif;">With IAAS, the vendor manages the hardware, but you choose the operating system and everything above it. This is typically</span><span style="font-family: "verdana" , sans-serif;"> used for things like web hosting and data centres.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span><span style="font-family: "verdana" , sans-serif;">With PAAS, the vendor manages everything except the application and the data. This is commonly used by software companies as a base for developing an application.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span><span style="font-family: "verdana" , sans-serif;">With SAAS the vendor manages everything. A good example of this would be GMail, where every part of the tech stack is managed by Google. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">With both IAAS and PAAS the customer can choose how many resources to use as and when they need them (this is why cloud computing is often called "computing on demand"). The billing is usually dynamic and depends on the resources that have been consumed during the billing period. It's typical to buy IAAS/PAAS capabilities and spin up additional virtual servers as required (a virtual server is a software representation of a real server), then apply a template that provides standard O/S, Middleware and Runtime. With IAAS the customer maintains the template and with PAAS the vendor provides one or more templates to choose from. The customer pays for every server they use. With SAAS you're getting access to a piece of software and usually the price is determined by the number of user licences you buy.</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">As an example of how this works, consider the following scenario:</span><br />
<br />
<ul>
<li><span style="font-family: "verdana" , sans-serif;">Vendor A buys, configures and maintains networking, storage, servers and virtualisation to sell as IAAS.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Web hosting company B buys IAAS from vendor A, then configures several templates for O/S, Middleware and Runtime that will appeal to different customers. They then sell this as PAAS.</span></li>
<li><span style="font-family: "verdana" , sans-serif;">Software development company C buys PAAS from company B, picks a template and a number of servers, then develops a piece of software on it. </span></li>
<li><span style="font-family: "verdana" , sans-serif;">Finally, company C sells their software as a SAAS offering to customers around the world, running on company B's PAAS, which runs on company A's IAAS.</span></li>
</ul>
<br />
<span style="font-family: "verdana" , sans-serif;">It's not uncommon for a vendor to offer at least 2 of the 3 service models, although normally this would be IAAS/PAAS or PAAS/SAAS. It wouldn't make a lot of sense to offer IAAS and SAAS without PAAS, because if the vendor has the capability to offer both infrastructure and software services then they've got the capability to offer a platform service. </span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;">That covers cloud computing and as-a-service to the level that I'll be using it over the new few months. There might be cause to look into deployment models (also covered in the </span><a href="https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-145.pdf" style="font-family: Verdana, sans-serif;">NIST Definition of Cloud Computing</a><span style="font-family: "verdana" , sans-serif;">), in which case there'll be a separate article, but that can wait until it's needed...</span><br />
<span style="font-family: "verdana" , sans-serif;"><br /></span>
<span style="font-family: "verdana" , sans-serif;"><br /></span>
Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-78787471676448032442018-04-26T20:37:00.000+01:002018-04-26T20:37:05.609+01:00More Strings to the Bow<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi_sgxkhyphenhyphenPgtEqgALTsw2kyhiehqDI_srRRsW1FxiI6eutqIst2fhdAJBQa_xdNSYHmmz3XsgY7_79d8o5fzFm0sUPxgU3Z-QX7LwQTAX0h82hEgMCCEhAo9HOB0YPcSW4WgCAhDdQM_ks/s1600/strings.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1067" data-original-width="1600" height="426" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi_sgxkhyphenhyphenPgtEqgALTsw2kyhiehqDI_srRRsW1FxiI6eutqIst2fhdAJBQa_xdNSYHmmz3XsgY7_79d8o5fzFm0sUPxgU3Z-QX7LwQTAX0h82hEgMCCEhAo9HOB0YPcSW4WgCAhDdQM_ks/s640/strings.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;"><div class="_3bJ2H CHExY">
<div class="_1l8RX _1ByhS">
<span style="font-family: Arial, Helvetica, sans-serif; font-size: xx-small;">Photo by <a href="https://unsplash.com/photos/sBwDoomztfE?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Soroush Karimi</a> on <a href="https://unsplash.com/search/photos/strings?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span></div>
</div>
</td></tr>
</tbody></table>
<div class="separator" style="clear: both; text-align: center;">
</div>
<span style="font-family: Arial, Helvetica, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">Over the last year I've been working on a SharePoint implementation in my day job as a contractor. I have a few years' experience doing content management and site collection administration on a SharePoint on-premise instance from a previous role, but this is brand new, SharePoint online, evergreen SAAS where O365 and Azure are important elements. There are a million things to learn, and a million more after that, and then you might, <i>might </i>know enough to say that you know what you're doing. </span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">All of which is very exciting and I have indeed learnt millions of things. However, this has left me with a problem: this blog. AgileDocumentation was always intended to be a blog that was generally about technical writing and specifically about documenting in agile environments. Whilst I'm the Scrum Master/agile coach for the SharePoint project team, and I'm writing lots of documentation - how-tos, instructions, design docs, comms, etc - it's not an agile documentation role. So I haven't blogged much over the last year or so because my mind was on non-agile documentation things.</span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">But I still think of myself as a writer. At my core, what I am, what I do, what I enjoy, is writing. So maybe I can't write about writing as much as I used to, but I can still write about technical subjects. And that's what I'm going to do. </span><br />
<span style="font-family: Verdana, sans-serif;"><br /></span>
<span style="font-family: Verdana, sans-serif;">Agile Documentation will still be in its heart a blog about technical writing, and I hope to return to that subject as much as possible. It's just that you might find it's pivoted towards the technical side of SharePoint, with some O365 and Azure thrown in, for a while at least. Think of it as an extended series on getting an enterprise-level content management system set up. That's documentation-related enough for me. For now.</span><br />
<br />Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-14365201370212502252017-12-09T14:42:00.000+00:002017-12-10T07:58:29.261+00:00A Dictionary for Documentation People<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhZTAf4wqUfgFUJ1hsDJKF_dIbW3o1l7g6-T6njDCqYXLWxmXZmYBX8F2gNND3xI4rC-3SCbYBf1omoxOCga6divlU1Ujm3sQVgu8zma0ODXb0o9THhCcR3fMonMqmIG1h3kLmkNlDwoZQ/s1600/Glossary.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="1200" data-original-width="1600" height="300" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhZTAf4wqUfgFUJ1hsDJKF_dIbW3o1l7g6-T6njDCqYXLWxmXZmYBX8F2gNND3xI4rC-3SCbYBf1omoxOCga6divlU1Ujm3sQVgu8zma0ODXb0o9THhCcR3fMonMqmIG1h3kLmkNlDwoZQ/s400/Glossary.jpg" width="400" /></a></div>
<div style="text-align: right;">
<br /></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Whether you're new to technical writing, a seasoned pro moving to a new role, or just someone who likes to make sure they know their stuff, there are a lot of terms, tools and methodologies for documentation people to get their head around. Below is a list of things which are common in our industry, with a short explanation and links for further reading. It's not an exhaustive list, so if something's missing leave a comment and I'll add it in.</span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Agile</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.agilealliance.org/agile101/" target="_blank">Agile</a> "is an umbrella term for a set of methods and practices based on the values and principles expressed in the <a href="http://agilemanifesto.org/" target="_blank">Agile Manifesto</a>." An agile methodology is primarily one which focuses on self-organising, multi-functional teams (that is, teams where every member can do more than one job), a prioritised to-do list in which the priorities can be reordered in response to external changes (e.g. stakeholder feedback, shifting business priorities, etc) and an iterative approach to development that delivers small parts of the whole over time. Agile methodologies have their roots in <a href="https://www.lean.org/WhatsLean/" target="_blank">Lean manufacturing</a> and arose in direct response to the formally prevailing Waterfall methodology, also known as "big bang delivery". In practise, Agile is often a synonym for Scrum, which is <a href="https://explore.versionone.com/state-of-agile/versionone-11th-annual-state-of-agile-report-2" target="_blank">by far the most used and most familiar agile methodology</a>. However, there are other agile methodologies, such as <a href="http://www.extremeprogramming.org/">XP</a> (eXtreme Programming), <a href="https://disciplinedagiledelivery.wildapricot.org/" target="_blank">Disciplined agile delivery</a> (DAD), <a href="http://kanbanblog.com/explained/" target="_blank">Kanban</a> and many other. See also: <b>Kanban</b>, <b>Scrum</b>, <b>Waterfall</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">API</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">An <a href="https://techterms.com/definition/api" target="_blank">API</a> (Application Programming Interface) is a set of functions that can be used to interact with an application. In modern software development, with its emphasis on web technologies, <a href="https://rajivramachandran.wordpress.com/2012/06/19/cloud-service-models-iaas-vs-paas-vs-saas/" target="_blank">Infrastructure/Platform/Software-as-a-Service</a> and <a href="https://www.interoute.com/what-cloud-hosting" target="_blank">Cloud hosting</a>, it's very common to encounter web APIs, but there are also large numbers of API suites for operating systems, client applications and software frameworks. API documentation is a specialist skill that requires knowledge of the code the API was written in, as well as scripting and markup languages like JavaScript and/or XML. There are tools such as </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://dapperdox.io/" target="_blank">DapperDox</a></span></span> and <a href="https://swagger.io/specification/" target="_blank">Swagger</a> that help developers and writers create API content and if you move into API documentation you'll almost certainly use these or similar tools. See also: <b>DapperDox</b>, <b>Swagger/OpenAPI</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">AsciiDoc</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://asciidoc.org/index.html" target="_blank">AsciiDoc</a> is a free, open source Help Authoring Tool that allows you to write in plain text and convert it to HTML, XHTML and DocBook formats (there are open source tools to convert the DocBook format to PDF, Epub and other formats). It is lightweight, configurable and has a strong user community, and is maintained, updated and <a href="http://asciidoc.org/userguide.html" target="_blank">documented</a> by Stuart Rackham, the original author of the programme. Of course, such benefits come with a cost: AsciiDocs is designed on and primarily for Linux, so although there is a port to Windows it is still command line heavy and will come as a bit of a shock if you're used to a slick GUI as your primary interface. Nonetheless, it's a popular choice, especially amongst writers with a technical background, and its command line nature means it works well if you want to add a level of automation to your document build process See also: <b>Help Authoring Tools</b>, <b>Markup</b>, <b>Plain Text</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Confluence</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.atlassian.com/software/confluence" target="_blank">Confluence</a> is an enterprise wiki used for documentation, knowledge management, and collaboration. It is part of the Atlassian suite of enterprise productivity software that includes Jira. See also: <b>Content Management Systems</b>, <b>Jira</b>, <b>Knowledge Management</b>, <b>Wiki</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content is specifically the part of written output that is concerned with delivering meaning. Whereas formatting is concerned with how the output is displayed, content is concerned with what the output contains. Technical writers generally write in a Help Authoring Tool that divorces the content from the formatting, or in plain text which can then be imported into some form of HAT to apply the formatting in the output. Content can also mean, more generally, the output itself. This is the context in which "content" is used in content marketing and Content Management Systems, which are concerned with, respectively, using output to help drive sales, and storing, sharing and managing output. See also: <b>Content Marketing</b>, <b>Content Management Systems</b>, </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>Formatting</b>, <b>Help Authoring Tools</b>, <b>Plain text</b>, <b>Technical Writer</b></span></span><br /> </span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Design</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.gov.uk/guidance/content-design/what-is-content-design" target="_blank">Content design</a> is the process of designing and creating content based on user needs. This sounds like a fancy term for a standard technical writer responsibility - we write for our users already, surely? - but it's the heavy focus on the user need rather than the product that marks content design as something different from previous approaches. Content design either started with, or was championed from very early stages by, GDS (Government Digital Service) and in particular <a href="https://twitter.com/escmum" target="_blank">Sarah Richards</a>, the (now former) Head of Content Design at GDS. Her <a href="https://www.amazon.co.uk/Content-design-Sarah-Richards/dp/1527209180/ref=sr_1_1?s=books&ie=UTF8&qid=1510995601&sr=1-1&keywords=sarah+richards+content+design" target="_blank">book</a> is the standard tome on the subject and reflects the GDS mantra of designing for user needs in whatever field, not just content. As with Content Strategy, this is something that will not go away and isn't a buzzword, which is why more and more technical communication roles refer to Content Design as a function, or name the role as a Content Designer. If you're struggling to find roles called "Technical Writer", they're still there but they're probably called "Content Designer" instead. See also: <b>Content</b>, <b>Content Strategy</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Management</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.vasont.com/resources/what-is-content-management.html" target="_blank">Content Management</a> is the creation, publishing and maintenance of content, primarily written documents and multimedia such as graphics and video. Where Information Management is concerned with the regulation of information as a corporate asset (retention, permissions), and Knowledge Management is concerned with making that information available to the right people at the right time (searching, sharing), Content Management is concerned with the actual information itself (writing, maintaining). Content Manager may be a specific role, although it is often part of the responsibility of a Technical Writing/Documentation Manager who will make content management part of the standard day-to-day activities of their team of writers. Content Management Systems (CMS) are used to store, share and publish content to the appropriate audiences, and Content Managers normally have (at least) some responsibility for managing these tools.<br /><br />In the sense that Content Strategy deals with the overarching questions about the goals of the content, Content Management is concerned with the tactics of achieving that strategy by writing the content that the strategy demands and publishing it appropriately. This includes designing the content to make sure it meets the users needs, something which is critical if the content is to meet the Content Strategy aim of "useful, useable content". See also: <b>Content</b>, <b>Content Design</b>, <b>Content</b> <b>Management Systems</b>, <b>Content Strategy</b>, <b>EDRMS</b>, <b>Information Management</b>, <b>Knowledge Management</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Management Systems</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Management Systems (CMS) are applications that are used to store, share and publish content to an audience. Normally they are designed to display content through a browser, either on an intranet or website. Unlike an Electronic Document and Records Management System (EDRMS), a CMS is not (generally) a document storage application, although the boundaries are blurry and it's a rare enterprise-level CMS that doesn't allow attachments to be added to pages. But the key difference is that a CMS will have pages showing content, whilst an EDRMS will have folders or libraries of documents. Wikipedia is probably the most well-known CMS (even if most users have never heard of a content management system) but there are many others around, such as <a href="https://wordpress.org/" target="_blank">WordPress</a> and <a href="https://www.atlassian.com/software/confluence" target="_blank">Confluence</a>. See also: <b>Confluence</b>, <b>Content</b>, <b>Content Management</b>, <b>EDRMS</b>, <b>Information Management</b>, <b>Wik</b> </span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Marketing</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Marketing tries to pretend that what used to be known as "advertising" is actually "content". When thinking of "content marketing", remember that it is "marketing", plain and simple. There's nothing wrong with marketing <i>per se</i>, but it's nothing to do with content design, content strategy or technical communication, as these things are based on helping users, not convincing them to buy stuff. Your content can help keep existing customers and encourage new customers, but that's a by-product of good documentation and not the core function. If content is helping people <b>use </b>your product, content marketing is trying to persuade them to <b>buy </b>your product. </span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content Strategy</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Content strategy "plans for the creation, publication, and governance of useful, usable content." This quote is taken from the <a href="https://alistapart.com/article/thedisciplineofcontentstrategy" target="_blank">seminal article</a> on the subject by <a href="https://twitter.com/halvorson" target="_blank">Kristina Halvorson</a>, an article which I should probably just quote verbatim rather than trying to put my own spin on it. (Alternatively, you could just buy <a href="https://www.amazon.co.uk/Kristina-Halvorson/e/B002XW0738/ref=sr_ntt_srch_lnk_2?qid=1512827732&sr=8-2">her book</a>.) Content strategy seems to be one of those things which has gained traction in the content community and isn't going away. Because it's a philosophy, attitude and approach, rather than a specific tool or technology, and because it's self-evidently useful as we build our cathedral of knowledge about how to "do" content, it really is worth spending some time diving into content strategy. Jobs that mention content strategy experience or specifically Content Strategists are becoming more common and this is unlikely to change any time soon. So read the article, and then look at this <a href="http://www.jonathoncolman.org/2013/02/04/content-strategy-resources/" target="_blank">massive list of content strategy resources</a> to continue your learning. See also: <b>Content</b>, <b>Content Design</b>, <b>Content Management</b></span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b> </b> </span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">DapperDox</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://dapperdox.io/" target="_blank">DapperDox</a> is an open-source API documentation tool that allows you to overlay rich content authored in GitHub-flavoured markdown onto Swagger/OpenAPI specifications. As with AsciiDocs and Jekyll it is command line heavy and designed on, and primarily designed for, Linux/UNIX but it can also be run on a Windows machine. DapperDox was written by <a href="https://twitter.com/zxchris" target="_blank">Chris Smith</a>, noted <a href="https://www.amazon.co.uk/ZX-Spectrum-Ula-Microcomputer-Computer/dp/0956507107/ref=pd_sim_14_4?_encoding=UTF8&psc=1&refRID=F9J22YCTPQEYYGA8WBK9" target="_blank">ZX Spectrum electronics expert</a>, software architect and API designer (caveat: I know Chris and have <a href="http://technicalcommunicationuk.com/wp/wp-content/uploads/2017/10/Rob-Woodgate-Creating-Integrated-API-Documentation-Experiences-for-Users.pptx" target="_blank">presented with him on API documentation</a>). See also: <b>AsciiDocs</b>, <b>API</b>, <b>GitHub</b>, <b>Jekyll</b>, <b>Swagger/OpenAPI</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Diacritics</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A diacritic is a symbol or glyph added to a letter, primarily to show how that letter is to be pronounced in the context of the word. English is one of the few languages that has virtually no diacritical marks outside of ones borrowed along with a word from another language, such as <i>naiveté </i>from French. You can find out more about diacritics and how to add them in various help authoring tools <a href="http://www.agiledocumentation.co.uk/2017/01/the-basics-diaritics-and-alt-codes.html" target="_blank">here</a>. See also: <b>Help Authoring Tools</b>, <b>Grammar</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">DITA</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture" target="_blank">DITA</a> (Darwin Information Typing Architecture) is an open source XML data model for designing and publishing written content. It's a form of <a href="https://techwhirl.com/series/structured-writing/" target="_blank">structured content</a> that employs topic-based authoring and metadata for content reuse and conditional processing (adding topics to different outputs automatically based on metadata). DITA has an extensive user community that provides much <a href="http://dita.xml.org/book/dita-wiki-knowledgebase" target="_blank">information and guidance</a> and there are a <a href="http://dita.xml.org/10-dita-resource-lists" target="_blank">myriad resources</a> for everyone from <a href="http://www.learningdita.com/" target="_blank">complete beginners</a> to <a href="http://www.learningdita.com/courses/advanced-reuse-in-dita/" target="_blank">experienced professionals</a> looking to take DITA further. See also: <b>Content</b>, <b>Formatting</b>, <b>Markup</b>, <b>Single Sourcing</b><br /> </span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">EDRMS</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">EDRMS (Electronic Document and Records Management System) is the rather clunky name for the modern equivalent of a filing cabinet. Unlike a Content Management System, the primary role of an EDRMS is not to display content but to store it. An EDRMS will at minimum allow granular permissions over who can view and edit the documents, and provide automated retention functionality that deletes or archives documents after a certain time period. The aim of an EDRMS is to provide a secure, accessible space over the whole document life cycle. The best known EDRMS is probably <a href="https://products.office.com/en-us/sharepoint/collaboration" target="_blank">SharePoint</a>, Microsoft's widely-used enterprise application that can also act as a Content Management System (as both intranet and external facing website), but there are a host of <a href="https://blog.capterra.com/top-20-document-management-software/" target="_blank">other providers</a>. See also: <b>Content Management Systems</b>, <b>Information Management</b>, <b>Knowledge</b> <b>Management</b><br /> </span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Flare</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.madcapsoftware.com/products/flare/" target="_blank">MadCap Flare</a> is a Help Authoring Tool for content development. Created by a large chunk of the team that used to work on Adobe's <a href="https://www.adobe.com/uk/products/robohelp.html" target="_blank">RoboHelp</a>, it's rapidly become the strongest contender for the crown of most fully-featured and popular HAT. Unlike tools such as AsciiDocs, Flare has a complete GUI and lots of features and functionality that turns writing and publishing into a workflow rather than stand-alone tasks. Madcap provide certifications both for students and trainers, and there are a plethora of in-person and online training courses available, as well as the <a href="https://www.madcapsoftware.com/conference/madworld-2018/" target="_blank">annual MadWorld conference</a> and a healthy online community of users. There are also multiple <a href="https://www.madcapsoftware.com/products/" target="_blank">additional MadCap products</a> that help manage the entire document life cycle. In short, Flare and its associated family of products are the 800-lb gorilla of the tech writing world, so there's a good chance you'll use it if you have a long and/or varied career as a writer. See also: <b>AsciiDocs</b>, <b>FrameMaker</b>, <b>Help Authoring Tools</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Formatting</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Formatting is the part of written output that is concerned with how the content is displayed. This covers things like font choice and size, emphasis (bolding, italics), and location of text on the page. Help authoring tools divorce formatting from content so that the writer can concentrate on the content. The formatting is dealt with at the level of the output, which means content can be single sourced into different outputs without requiring changes by the writer. See also: <b>Content</b>, <b>Help</b> <b>Authoring Tools</b>, <b>Single sourcing</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">FrameMaker</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.adobe.com/uk/products/framemaker.html" target="_blank">Adobe FrameMaker</a> is a Help Authoring Tool designed primarily for writing long documents like books or manuals. Whilst some consider it as a direct competitor to Flare, the use cases are slightly different. Flare is more of an all-rounder, but its focus on single sourcing multiple outputs makes it ideal for topic based authoring and quick deployment. FrameMaker is a more specialised tool (although it too has all-round capabilities) that makes it ideal for building large and complex documents. This means that FrameMaker use skews towards industries that need large, complex, highly-structured documents with a long life cycle, such as rail engineering, or publishing companies that don't have much of a need for topic reuse, chunking or publishing on Content Management Systems. Adobe prefer to sponsor conferences rather than run them, and there are no official certifications for FrameMaker, but there is still a <a href="https://forums.adobe.com/community/framemaker" target="_blank">vibrant user community</a> and plenty of in-person and online training courses (I recommend <a href="https://www.cherryleaf.com/training/framemaker-training-courses/" target="_blank">CherryLeaf</a> if you're in the UK). See also: <b>Flare</b>, <b>Help Authoring Tools</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Git</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://git-scm.com/" target="_blank">Git</a> is a free and open source distributed version control system that is immensely popular amongst developers. It holds code in repositories (or "repos") and tracks every change ever made to the files in each repo. Whilst the Git website claims that Git is "easy to learn", and they provide <a href="https://git-scm.com/documentation" target="_blank">comprehensive documentation</a>, Git is still a developer tool that can only be fully used via the command line. It has a notoriously high learning curve, especially for non-developers, to the extent that jokes about the complexity of doing things such as <a href="https://media.giphy.com/media/cFkiFMDg3iFoI/giphy.gif" target="_blank">a merge or a rebase</a> are common even amongst the developer community. That being said, Git can and is used for non-development work, not least of all documentation, and there are <a href="https://git-scm.com/downloads/guis" target="_blank">GUI clients</a> that will allow you to do a significant subset of things that you can do on the command line, although <a href="https://git-scm.com/book/en/v2/Getting-Started-The-Command-Line" target="_blank">some commands are only available through the command line</a>. This <a href="https://alvinalexander.com/git/git-cheat-sheet-git-reference-commands" target="_blank">cheat sheet</a> of Git commands might help you here. There are plenty of training options for Git, such as <a href="https://try.github.io/levels/1/challenges/1" target="_blank">Try Git</a>, and other example such as <a href="https://www.linkedin.com/learning/git-essential-training" target="_blank">here</a>, <a href="http://think-like-a-git.net/" target="_blank">here</a>, and <a href="https://www.slideshare.net/KatrinaSylorMiller/giting-out-of-your-git-messes-fluent-conf-2017" target="_blank">here</a>, and more advanced training like <a href="https://learngitbranching.js.org/" target="_blank">Learn Git Branching</a> and <a href="http://ohshitgit.com/" target="_blank">Oh Shit, Git!</a> Like many of the items in this glossary Git has a very active user community, so Google is your friend if you're looking for help, training or tutorials. See also: <b>GitHub</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">GitHub </span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://github.com/" target="_blank">GitHub</a> is a web-based repo hosting system for Git, so that users don't need to host their own repos. It also provides access control, the ability to request features, bug tracking and various other functionality built on top of Git. As with Git, there are many online resources to help you learn GitHub, and realistically learning Git without learning GitHub is a bit like learning to be a mechanic without ever learning to drive. Some example tutorials are <a href="http://product.hubspot.com/blog/git-and-github-tutorial-for-beginners" target="_blank">here</a>, <a href="https://www.youtube.com/watch?v=0fKg7e37bQE" target="_blank">here</a>, and <a href="https://help.github.com/categories/bootcamp/" target="_blank">here</a>, but there are plenty of others. GitHub is also the birthplace of <a href="https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github/" target="_blank">GitHub Flavoured Markdown</a>, which due to the popularity of Git/GitHub is a widely used markdown variant. See also: <b>Git</b>, <b>Markdown</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Grammar</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://en.wikipedia.org/wiki/Grammar" target="_blank">Grammar</a> is the set of rules that determines the structure of a language. It includes such things as syntax, morphology, phonetics, and semantics. Very roughly, these can be treated as sentence rules (syntax), word rules (morphology), sound rules (phonology) and meaning (semantics). The skill of a writer is concerned primarily with semantics (the message being conveyed in natural language), whereas the skill of a developer is concerned primarily with syntax (the correct logical construction to yield the intended result in a programming language) See also: <b>Natural language</b>, <b>Programming</b> <b>language</b>, <b>Semantics</b>, <b>Syntax</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Help Authoring Tools</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A Help Authoring Tool, also known as a HAT, is a program that technical communicators use to generate their output. The primary benefits of a HAT include, but are not limited to, the divorce of content from formatting, the ability to single source different output types (HTML, CHM, PDF etc) from the same content, auto-generation of TOCs and glossarys, and versioning. See also: <b>AsciiDoc</b>, <b>Flare</b>, <b>FrameMaker</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Information Management </span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://www.aiim.org/Resources/Glossary/Information-Management#" target="_blank">Information Management</a> </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">(IM) </span></span>is concerned with what, how and when information should be retained and distributed as well as how long it should be retained for. Unlike content management it is not primarily concerned with creating or maintaining information, only the management of it once it enters the system. IM is heavily process and policy driven, normally using an EDRMS, and treats information as a corporate asset to be identified and catalogued. There is some overlap with Knowledge Management, but the two functions are distinct as IM is normally responsible for meeting legal and regulatory requirements for record keeping and knowledge management is not. See also: <b>Content Management</b>, <b>Content Management System</b>, <b>EDRMS</b>,<b> Knowledge Management</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">ISTC</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">The <a href="http://www.istc.org.uk/" target="_blank">ISTC</a> (Institute of Scientific and Technical Communicators) is the world's <a href="http://www.istc.org.uk/about-the-istc/history-of-the-istc/" target="_blank">oldest professional body</a> for people who write documentation. It hosts an annual conference called <a href="http://technicalcommunicationuk.com/" target="_blank">TCUK</a> which attracts many of the biggest hitters in the UK industry. If you're a technical communicator in the UK then the ISTC is your professional body, and it's dedicated to helping its members develop as professionals by sharing knowledge, skills and opportunities. See also: <b>STC</b>, <b>WriteTheDocs</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Jekyll</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://jekyllrb.com/" target="_blank">Jekyll</a> is a static website generator that allows you to take plain text and turn it into a website. It is a Ruby/Python application built on and primarily run on Linux, although there is a <a href="http://jekyll-windows.juthilo.com/" target="_blank">unofficial Windows port</a>. As with AsciiDocs, Jekyll is command line heavy, which makes it ideal for automating builds, but also gives it a high learning curve if you're used to GUI interfaces. There are lots of tutorials available such as easy guides to <a href="http://jekyllcodex.org/getting-started/" target="_blank">setting up a simple website</a> and <a href="https://jekyllrb.com/tutorials/video-walkthroughs/" target="_blank">video tutorials</a> but be warned that to use Jekyll you'll need to have a good grasp of website deployment, Linux and coding principles. See also: <b>AsciiDocs</b>, <b>Plain text</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Jira</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.atlassian.com/software/jira" target="_blank">Jira</a> is an issue tracking application used by development and project teams to track their work. Originally it was a simple bug tracking application, but over the years it has metamorphosed into a fully-featured workflow management and reporting tool, primarily designed for teams working in agile sprints. It is part of the Atlassian suite of enterprise productivity software that includes Confluence. See also: <b>Agile</b>, <b>Confluence</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Kanban</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://kanbanblog.com/explained/" target="_blank">Kanban</a> is an agile methodology that takes a production line approach to developing software. Unlike Scrum, which uses repeating iterations of time (also called sprints), Kanban uses continuous flow to move whatever is the highest priority job through a pipeline until the job is completed. The best-known element of Kanban is the <a href="http://www.expertprogrammanagement.com/wp-content/uploads/2016/12/Kanban-Board.png" target="_blank">Kanban Board</a> which displays tasks in columns based on their place in the pipeline. These columns can be as simple as To-Do, In Progress and Done, although you can use as many columns as there are steps in your process. Kanban boards are used in Scrum, and are popularly used in task tracking software such as Jira and <a href="https://trello.com/" target="_blank">Trello</a>. See also: <b>Agile</b>, <b>JIRA</b>, <b>Scrum</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Knowledge Management </span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://www.kminstitute.org/blog/what-meant-knowledge-management" target="_blank">Knowledge Management</a> (KM) is concerned with the collection and use of information within an organisation. Unlike Information Management, which focuses on the legal and regulatory requirements for record keeping, KM is primarily concerned with the effective and efficient use of information within the business to improve outcomes. This means preventing data silos, making tacit knowledge explicit, knowledge transfer, especially from a single point of failure (that one person/team who are the only ones who know about a certain business critical thing), providing new and better ways to easily collaborate, and building a culture where things are written down in publicly accessible places. Documentation/technical writing is sometimes considered a subset of KM. See also: <b>Information Management</b>, <b>Technical Writing</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Lorem Ipsum</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://lipsum.com/" target="_blank">Lorem Ipsum</a> is filler text that is used as a proxy for the content when designing the formatting of a document. Originally this was used in physical typesetting so that printers could produce demonstration pages before a writer had provided the content; this had the added benefit that they would be ready to print as soon as the content was provided. Nowadays lorem ipsum is used primarily in electronic content formatting for websites, PDFs, and other content. Word can <a href="https://www.laptopmag.com/articles/microsoft-office-lorem-ipsum-generator" target="_blank">produce lorem ipsum text for you</a> and you can specify the number of paragraphs and lines per paragraph that you want. There are a number of <a href="http://mashable.com/2013/07/11/lorem-ipsum/#BYBrXzNzFiqO" target="_blank">lorem ipsum generators</a> if you don't want to use the traditional quasi-Latin text but be warned that some of them contain NSFW language. <a href="https://baconipsum.com/" target="_blank">Bacon Ipsum</a> is of course highly recommended. See also: <b>Content</b>, <b>Formatting</b>, <b>Word</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Markdown</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://daringfireball.net/projects/markdown/" target="_blank">Markdown</a> is a markup language that uses extremely simple tags. It is designed to allow people to write documents in plain text, which can then be converted into well-formed HTML or XHTML. There are a number of variants of Markdown, most of which extend the original syntax to include things like tables, and well-known variants include <a href="https://help.github.com/articles/about-writing-and-formatting-on-github/" target="_blank">GitHub Flavoured Markdown</a> and <a href="https://michelf.ca/projects/php-markdown/extra/" target="_blank">Markdown Extra</a>. See also: <b>Git/GitHub</b>, <b>Markup</b>, <b>Plain text</b></span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b> </b> </span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Markup</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A markup language uses tags to annotate text so that readers (such as web browsers) can parse the tags and add formatting. The best-known examples of markup languages are HTML and XML, but there are many others. The W3 consortium maintains <a href="https://www.w3schools.com/default.asp" target="_blank">complete tutorials</a> for HTML and XML, alongside other common and standardised languages used in web development. See also: <b>Content</b>, <b>Formatting</b>, <b>Markdown</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Natural language</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Natural languages are languages that have evolved or grown organically without premeditated planning or structure, such as English or German. The term "natural" is used to differentiate between "normal" human languages and artificial languages that have been designed specifically for a purpose, such as a programming language. The primary functional difference between a natural language and a programming language is that programming languages have tightly controlled syntax and semantics. This means that even a small error in the syntax renders the programme unintelligible to the computer running it, and the meaning of the terms in the language - the semantic content - is static, context independent and universal (every element of the language means the same thing in every programme as each element can only be treated one way by the computer). Natural languages have syntax rules as well, otherwise no-one could communicate with each other, but there is more flexibility and redundancy in these rules. The semantic content of a natural language is dynamic, context dependent and localised (dialects, for example). Technical writers use their skill in natural language semantics to communicate a message, whereas developers use their skill in programming language syntax to tell a computer to perform an operation. See also: <b>Grammar</b>, <b>Programming language</b>, <b>Semantics</b>, <b>Syntax</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Plain text</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Plain text is text completely divorced from formatting. At its most basic, this means ASCII or Unicode encoded characters with no specific requirement for font, font size, colour, or formatting like line breaks or emphasis. The practical reality of plain text, seen best in a .txt file opened by a programme like NotePad, NotePad++ or vi, is that line breaks and tab spaces are normally encoded in plain text as well. As long as the programme rendering the text can deal with ASCII or Unicode (which it almost certainly will be able to do, as these are the prominent global character encoding standards) then text that is divorced from formatting is largely platform-agnostic. This has many advantages, not least that the writer can specify how something should be formatted - e.g. with emphasis - and leave it to the programme consuming the text to format it. This allows single-sourcing, where a piece of content can be displayed in different formats without having to be changed, as the rendering programme will deal with the format. See also: <b>Content</b>, <b>Formatting</b>, <b>Single Sourcing</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Programming language</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A programming language is an artificial language used to provide instructions for a computer, usually as a sequence of operations to be performed under certain conditions. They are differentiated from natural languages such as English or German, which have evolved or grown organically without being designed. Programming languages have syntax (the rules governing the correct usage of the elements of a language) and semantics (the meaning of the elements of a language), but unlike natural language both of these things are tightly prescribed. Developers are much more concerned with the syntax of a language, whereas technical writers are much more concerned with the semantics. This is because the skill of the developer is in passing instructions to the computer to make it perform the desired operations, whereas the skill of a writer is in communicating information and understanding to a reader. See also: <b>Grammar</b>, <b>Semantics</b>, <b>Syntax</b>, <b>Natural languages</b>,</span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Scrum</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://www.scrum.org/" target="_blank">Scrum</a> is an agile methodology that uses iterations (also known as sprints) to produce a working product piece by piece. This is in marked contrast to the "big bang delivery" of traditional <a href="https://www.techrepublic.com/article/understanding-the-pros-and-cons-of-the-waterfall-model-of-software-development/" target="_blank">Waterfall</a> projects. Scrum is comfortably the most used agile methodology with 58% of respondents to the 11th annual <a href="https://explore.versionone.com/state-of-agile/versionone-11th-annual-state-of-agile-report-2" target="_blank">State of Agile report</a> from 2017 using Scrum as their methodology of choice and a further 10% using a Scrum/XP hybrid. Due to this popularity and 2 well-known Scrum bodies (<a href="http://scrum.org/">Scrum.org</a> and <a href="https://www.scrumalliance.org/" target="_blank">Scrum Alliance</a>) there are plenty of forums, communities and trainers around to help you learn Scrum. Both Scrum bodies offer <a href="https://www.scrumalliance.org/certifications/certifications2017" target="_blank">certifications</a> and <a href="https://www.scrum.org/resources" target="_blank">resources</a> to help you master the methodology. When you see a job application that requires experience of agile methodologies, then if it doesn't specify a particular methodology you can be fairly sure it means Scrum. See also: <b>Agile</b>, <b>Kanban</b>, <b>Waterfall</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">SDK</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">An <a href="https://techterms.com/definition/sdk" target="_blank">SDK</a> (Software Development Kit) is a "collection of software used for developing applications for a specific device or operating system". These collections often require extensive technical documentation to allow a user to become familiar with the tools, frameworks and environments. This normally includes code samples written in the appropriate language and other highly technical information, so technical writers who can write SDK documentation are highly sought after (and normally well-paid). See also: <b>API</b>, <b>Programming language</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Semantics</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>Semantics</b> is a subset of grammar and deals with the meaning of words and sentences. Natural languages can have extremely complex and/or ambiguous semantic contexts, whereas programming languages have semantics which are always very precisely defined. See also: <b>Grammar</b>, <b>Syntax</b>, <b>Natural languages</b>, <b>Programming languages</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Simplified Technical English</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://asd-ste100.org/index.html" target="_blank">Simplified Technical English</a> (STE) is a language standard originally created for the aviation industry, although it can be used in other industries as well. STE is an example of a "controlled language", that is, a language which limits what users can say and how they can say it. The aim is to provide a standard that guarantees that non-native English speakers at a certain basic level of competency will be able to understand what's been written. Contrary to popular belief, <a href="http://www.tcworld.info/rss/article/a-close-look-at-simplified-technical-english/" target="_blank">only around 3% of the words in STE relate to the aviation industry</a>; it is the simple sentence structure and removal of ambiguity like synonyms and metaphors that makes STE so useful, especially in international companies or industries. There are plenty of STE resources such as <a href="https://instrktiv.com/en/simplified-technical-english/" target="_blank">this</a>, a <a href="https://plus.google.com/communities/103427555409835063525" target="_blank">Google+ forum</a>, and even <a href="https://www.madcapsoftware.com/blog/2013/05/16/controlled-language-with-simplified-technical-english-how-to-integrate-the-hyperste-plug-in-in-flare/" target="_blank">a plugin for Flare</a> to validate your STE. See also: <b>Flare</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Single Sourcing</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://www.agiledocumentation.co.uk/2015/09/the-basics-what-is-single-sourcing.html" target="_blank">Single sourcing</a> is an example of the "Create once, use many" philosophy. It is also known as content reuse and is analogous in concept to code reuse, in that you can change the source code/documentation, compile your project and create a new deliverable with that change made everywhere the content is reused. Markup languages like HTML and XML allow the divorce of content and presentation. The essence of single sourcing is to write the content once and then use markup to present it in different ways. This can be in a different format - PDF, CHM, HTML, printed, etc - or in the same format but with different content "chunks". Large, homogeneous documents such as entire help files don't lend themselves to single sourcing, unless identical copies are going to be created in different formats (e.g. a PDF and a printed format). Therefore single sourcing requires a topic based authoring approach, where individual topics can be reused in different outputs and in different formats. It is for this purpose that DITA and its structured topic approach were designed. See also: <b>Content</b>, <b>DITA</b>, <b>HTML</b>, <b>Markup</b>, <b>XML</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Slack</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://slack.com/" target="_blank">Slack</a> is a chat application that allows users to post in group channels or by direct message to individuals. It is not a documentation-specific tool but is mentioned here because its use is so ubiquitous within (especially) software development circles. If you've never used Slack before then you can <a href="https://slack.com/create#email" target="_blank">create your own Slack work space for free</a> and have a play around with it, which is recommended if you are planning on joining a company that uses it. Slack has become the default communication tool in many workplaces, far outstripping email in volume of messages passed (at the time of writing I am the owner of a Slack instance and an O365 global admin for my organisation and the stats say that the dev teams on Slack send virtually no email in comparison to their Slack usage), so get used to using it.</span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">STC</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">The <a href="https://www.stc.org/" target="_blank">STC</a> (Society for Technical Communication) is a professional society for American technical communicators. It claims to be the <a href="https://www.stc.org/about-stc/" target="_blank">oldest such organisation in the world</a>, despite it being created 5 years after the ISTC (1953 vs 1948). However, being British we don't like to make a fuss, and we know how important these things are to our American cousins, so we're happy to let them keep fooling themselves. After all, kids, eh? What can you do? Anyway, if you're a North American, this brash upstart is your professional body and they're very active, with an <a href="https://summit.stc.org/conference/" target="_blank">annual conference</a> and multiple regional conferences throughout the year. See also: <b>ISTC</b>, <b>WriteTheDocs</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Swagger/OpenAPI</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">The <a href="https://swagger.io/specification/" target="_blank">OpenAPI specification</a> (formerly known as the Swagger Specification) is a definition format to describe RESTful APIs. Commonly described as a "Swagger spec", an OpenAPI specification of an API provides users with an explanation and description of the elements of an API without requiring the user to read the actual code. The specification can also be used to auto-generate code and documentation using various tools that have been developed. <a href="https://twitter.com/tomjohnson" target="_blank">Tom Johnson</a> has written an excellent <a href="http://idratherbewriting.com/learnapidoc/pubapis_swagger.html" target="_blank">tutorial for Swagger</a>, alongside his highly-regarded API documentation tutorials, but there are plenty of resources online to learn about Swagger/OpenAPI. See also: <b>API</b>, <b>DapperDox</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Syntax</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://en.wikipedia.org/wiki/Syntax" target="_blank">Syntax</a> is a subset of grammar, for which it is often confused. Whilst grammar deals with language as a whole, syntax is concerned primarily with the structure of sentences and how words should be ordered within them (i.e. the grammar above the word level). See also: <b>Grammar</b>, <b>Semantics</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Technical Communication</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Technical communication is the communication of technical concepts and/or instructions on how to do something. The term covers a broad church that includes technical writing, technical illustration/drawing, content strategy and content design, as well as referring to specialist tools and techniques that technical communicators use. See also: <b>Content Design</b>, <b>Content Strategy</b>, <b>Technical Writer/Author</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Technical Writer/Author</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A technical writer is someone who creates and maintains technical documentation about how things work. This may be in the form of manuals, help files, FAQs, guides, tutorials, release notes, installation notes, explanations, descriptions, specifications, SDKs docs, or any other form of documentation that transfers knowledge to others. In modern technical communication a writer may also produce video material, spoken material and presentations. Normally the writer is expected to use various applications such as help authoring tools, version control and content management systems, as well as understand methodologies such as Scrum, Kanban and other agile methodologies. See also: <b>Every single item in this glossary</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Version Control</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Version control is the management of information, primarily permissions, versioning, branching and merging. Documentation and software development are traditionally heavy users of version control (or source control for software, from "source code"). Common practise now is to use a Distributed Version Control System (DVCS), where every user has a complete repository held locally, rather than the older centralised systems where people worked on a single centrally located repository. This has led to a rise in branching (where users create a separate, unique version of one or more parts of the repository) and merging (merging the branches back in to the master version), which requires a more complex tool set than previous version control systems needed. Whilst many content management systems and EDRMS applications provide permissions and versioning, it is the branching and merging that truly sets a DVCS apart when using one for documentation. Popular DVCS applications include Git/GitHub, Microsoft's <a href="https://www.visualstudio.com/tfs/" target="_blank">Team Foundation Server</a> (TFS) and <a href="https://subversion.apache.org/" target="_blank">Subversion</a>, although there are plenty of others. See also: <b>Content Management Systems</b>, <b>EDRMS</b>, <b>Git/GitHub</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Waterfall </span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://en.wikipedia.org/wiki/Waterfall_model" target="_blank">Waterfall</a> is a project management methodology that was predominant until the advent of Agile. Unlike Agile methodologies, which develop in an iterative fashion to provide incremental elements of a solution over time, Waterfall is a linear process which delivers everything in one go, hence why it's often called "big bang delivery". Traditionally, a software project being run using Waterfall will complete (something like) the following steps, in order: Analysis, Design, Build, Test, Deploy, Maintain. Each step must be complete before starting the next step. The arguments about which is the better methodology to use <a href="http://www.base36.com/2012/12/agile-waterfall-methodologies-a-side-by-side-comparison/" target="_blank">are legion</a>, but there's no doubt that Scrum is far more popular in software houses. Productivity tools like <a href="https://www.atlassian.com/software/jira" target="_blank">Jira</a> and <a href="https://trello.com/" target="_blank">Trello</a> are designed for Agile environments and it's a rare software house nowadays that asks for Waterfall experience rather than Agile experience, although that doesn't mean that it's easy to get Agile right and not end up with each sprint being a <a href="http://www.agiledocumentation.co.uk/2015/02/what-is-water-scrum-fall-and-is-it.html" target="_blank">mini-Waterfall</a>. See also: <b>Agile</b>, <b>Jira</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Wiki</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A <a href="https://en.wikipedia.org/wiki/Wiki" target="_blank">wiki</a> "is a website on which users collaboratively modify content and structure directly from the web browser. In a typical wiki, text is written using a simplified markup language and often edited with the help of a rich-text editor." By far the best known wiki is <a href="https://en.wikipedia.org/wiki/Main_Page" target="_blank">Wikipedia</a>, from where the quoted description is taken, which uses <a href="https://www.mediawiki.org/wiki/MediaWiki" target="_blank">MediaWiki</a> although there are many <a href="https://en.wikipedia.org/wiki/List_of_wiki_software" target="_blank">different wiki providers</a>. Wikis are popular as knowledge management hubs because users can edit the pages themselves, unlike a traditional website or intranet, and technical writers are often responsible for updating their organisation/department's wiki. See also: <b>Confluence</b>, <b>Knowledge Management</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Word</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://products.office.com/en-GB/word" target="_blank">Word</a> is a word processing application for writing documents. It's the writing package that just about everyone who's ever used a computer is familiar with, although professional writers rarely use it for writing documentation (we tend to use specialised Help Authoring Tools). In the same way that people who don't know much about football - that's soccer, to our American cousins - expect players to be great at <a href="https://www.youtube.com/watch?v=Zts3v4J8VyU" target="_blank">keepy-uppy</a>, even though the skill is rarely required in an actual game, people who don't know much about technical communication will expect technical writers to be good with Word. You can either be one of those rude people that mocks anyone who asks for help, or you can help them and be a, you know, <i>decent human being and good colleague</i>. If you go with the latter approach then you'll find lots of good training material from Microsoft <a href="https://support.office.com/en-us/article/Word-video-training-7bcd85e6-2c3d-4c3c-a2a5-5ed8847eae73" target="_blank">here</a>. See also: <b>Help Authoring Tools</b></span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">WriteTheDocs</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://www.writethedocs.org/" target="_blank">WriteTheDocs</a> (WtD) is a community of practise that doesn't have memberships or fellowships or offer certifications. Instead, its aim is to create, hold and encourage conferences and meetups, both online and in real life, where anyone interested in creating great documentation can learn, teach, network and generally grow their knowledge and understanding of how to create great documentation. WriteTheDocs has <a href="http://www.writethedocs.org/slack/" target="_blank">an active Slack instance</a>, a regular <a href="http://podcast.writethedocs.org/" target="_blank">podcast</a>, holds a couple of <a href="http://www.writethedocs.org/conf/" target="_blank">big conferences every year</a>, has <a href="http://www.writethedocs.org/meetups/" target="_blank">active meetup groups</a> in cities around the world and they also have specialist <a href="http://apithedocs.org/" target="_blank">APITheDocs meetups</a>. If you're looking for a community of like-minded documentarians, WriteTheDocs is for you. See also: <b>ISTC</b>, <b>STC</b></span></span><br />
<br />
<br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">If there's something missing from this list, or you've got a link to a useful tutorial, let me know in the comments and I'll add it in (and give you a shoutout to boot).</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-23500836212898570752017-07-29T08:58:00.000+01:002017-07-29T08:58:41.953+01:005 Things Writers Need From Developers<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgwFtmMabs_2On2MQZ9ffCMxvgDG7gS7_jkXkNy_8YTF-PaVqduyjo5PaKuEqfJmSFxARviCWJvePugEtgRzWfGZtooYFDG7vaawC1IeT6Yj-nEw1g4nMRFH7KC1mEBdhVxSqq-qPYgrM8/s1600/Developer.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="806" data-original-width="1600" height="321" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgwFtmMabs_2On2MQZ9ffCMxvgDG7gS7_jkXkNy_8YTF-PaVqduyjo5PaKuEqfJmSFxARviCWJvePugEtgRzWfGZtooYFDG7vaawC1IeT6Yj-nEw1g4nMRFH7KC1mEBdhVxSqq-qPYgrM8/s640/Developer.jpg" width="640" /></a></div>
<br />
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Developers don't like writing documentation in the same way that cats don't like having a bath. There might be <a href="https://purrfectcatbreeds.com/cat-breeds-list/cat-breeds-that-like-water/" target="_blank">the odd breed of cat</a> that likes a bath, just like there is the odd developer who likes writing documentation, but generally cats and developers are quite predictable when it comes to baths and documentation.<br /><br />But people like being able to get necessary-but-onerous jobs done with the minimum of effort, time and thought, and developers are no different. So here is a list of 5 things writers want from developers. <br /> </span></span><br />
<h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Clarity </span></span></h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Don't provide a steam of consciousness brain dump about the work item you're documenting. List things in some kind of order.</span></span><br />
<br />
<h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Accuracy </span></span></h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Can't remember why you added a radio button to the UI? Don't make up an answer. When you're not sure, tell us you're not sure. If you know the name of someone who might know, give us that name. We'll do some legwork for you. But don't ever make stuff up. </span></span><br />
<br />
<h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Timeliness</span></span></h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Not just about when you get the docs to us, but when you write them. Yeah, the next piece of work you've been looking forward to is much more interesting that documentation, but tough luck. Your memory is fallible and you will forget details of the work you've done. So either document as you go, or at least document before you move on to the next piece of work. It will save you and the writer a lot of pain later on as they have to spend time interrogating you and your terrible memory.</span></span><br />
<br />
<h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Completeness </span></span></h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Also known as 5WH: What, When, Who, Where, Why and How. WHAT was done, WHEN was it done, WHO did it, WHERE was it done, WHY was it done, HOW was it done. If you take nothing else away from here, remember 5WH. </span></span><br />
<br />
<h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Consistency </span></span></h3>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Provide the same information every time in the same place. Create a template. Ask the writer to create a template for you. Get every developer to use the same template and save it in the same place - a new Confluence page in the Release space for every work item, in the comments of the JIRA item, in a dedicated Slack channel for that release, in a README for every GitHub pull request, wherever works for the team. Then do the same thing every time.<br /><br /><br />Some notes on the above:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">There are pieces of information that it's just common sense to include, like the names of people who worked on something and the numbers of linked work items. Forgetting to include these makes you look anything from unprofessional to incompetent.</span></span></li>
</ul>
<ul>
<li><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">There are pieces of information that the non-writer may not think need to be included. Ask the writer if they want that information included. This is one of the ways a template really helps.</span></span></li>
</ul>
<ul>
<li><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Writers hate it when their work can be called into question, especially if it's because a developer has fed them some made-up information. Reputation is important to writers, so don't make them look bad at their job. (This is a pretty good rule of thumb for all interactions in your life.)</span></span></li>
</ul>
<ul>
<li><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Being part of the "too cool for school" culture that mocks people, especially developers, who write documentation is boring, unprofessional and frankly pathetic. It's part of the "bro culture" that everyone hates (apart from bros, obviously). It should be embarrassing to you if you get your kicks from ripping on other professionals in your office. Stop it. If you're reading this then hopefully you're not that kind of developer. Spread the professionalism around your office as required.</span></span></li>
</ul>
<ul>
<li><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">Developers who write good docs are normally the better developers in the office. Writing good documentation requires you to be able to step into someone else's shoes, as does writing good software. The most respected (and best paid) developers I've worked with over my career have significantly overlapped with the developers who write good documentation. </span></span></li>
</ul>
<ul>
<li><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;">When all's said and done, developers need to communicate what they've done, whether they want to or not. Learn how, become a better developer, become a better professional.<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;"></span></span> </span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;"><br /> <br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-44109426882658000662017-03-19T15:17:00.000+00:002017-03-19T15:22:30.014+00:00The Craftsmen and the Chart-Makers<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg8triZcFHae6iNDIMM3apN69NLvqy1sxY7uvOVC8YP0Nvke6Ck1VqpRIq8WB15oMj_L9-IhCI-1ctTZpvGpLWP5Uw_hIJ4AEeHTwppJ-MAYCgpiCCkPXJaWyGE-8tEX7FI6aCcaIR5ijw/s1600/Chart.jpeg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="283" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg8triZcFHae6iNDIMM3apN69NLvqy1sxY7uvOVC8YP0Nvke6Ck1VqpRIq8WB15oMj_L9-IhCI-1ctTZpvGpLWP5Uw_hIJ4AEeHTwppJ-MAYCgpiCCkPXJaWyGE-8tEX7FI6aCcaIR5ijw/s400/Chart.jpeg" width="400" /></a></div>
<div style="text-align: center;">
<br /></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><i>We don't make anything any more.</i><br /><br />That lament has followed us through the years as a ghost floats above his killer, never seen with the fullness of the eye but always hovering as a mocking, aggressive reminder of what we've done to ourselves. We've killed our ability to make things, outsourced it to the non-Western world in return for self-righteousness about the lack of pollutants in our post-industrial lands, while we wring our hands about the plight of the people in those barren places where the machinery has cooled and seized. Statues of steel and rust in yellow, grey and brown, abandoned as a warning to our children, mnemonics to those of use who saw them in their prime, moving, growling, far too large to ever be killed, or so we thought. <br /><br />And who is to blame, cry all? <br /><br />The politicians! The corporations! The environmentalists! The unions! The liberals! The elites! <br /><br />Each one says, "But, 'tis not us! We only wanted a clean, technologically-advanced land, where people are educated, work is skilled and life is good! Why do you blame us for the best of our intentions?"<br /><br />And the politicians blame the unions, the corporations blame the environmentalists, the environmentalists blame the market, the unions blame the liberals, the liberals blame the elites, and the elites melt into the ghost that haunts our waking and takes what's best from our sleep. <br /><br />But many have never seen a post-industrial land, let alone an industrial one. Their concern for what we make is limited to discussions about tax, custom tariffs, import and export ratios, figures upon figures arranged in industry-approved charts of all kinds, a blanding of the sweat, effort, sacrifices and pain of the makers into black digits in a white cell. Not for them a life steeped in the stink of manual labour, the ache of muscles from a 12-hour shift, the primal satisfaction of using the power of your body to provide for your family. These are things that belong to a different age, an age of flat caps worn without irony, holidays to the seaside, outside toilets, knowing your neighbours your whole life, living, dying, generations of people, within the same county border, the same town, the same village, the same factory or mine or mill, the same house. <br /><br />A German and his English colleague once talked with horror of man becoming a mere appendage of the machines, workers being no longer the means of production but lowly attendants on those mechanical monsters that have taken over the effort, the sweat, the pride of making things. A portent of what is to come? The chart-makers delight in this thought, this hope, for all they see is minimum costs and maximum production, a line on a graph that moves smoothly and predictably in their favour in a mathematically optimal way. The messy meat variables are being replaced with pristine metal constants. Is this not utopia? Is a land built on the cool predictability of the voiceless machines not better than one uncertainly sustained by the chaos and noise of a directionless mass of writhing limbs? So much chaos. So much noise. So much complexity, too much complexity, a rabble of variables that moves the chart further and further away from a prediction and closer and closer to being no more certain than a prophecy. This is not what the charts should show.<br /><br />The chart-makers say: These lives are an anachronism! We don't need them. We need the figures to balance in our favour, and if they balance in our favour then the anachronisms will have work to do somewhere else. And eventually the figures always balance in our favour. Eventually, but always.<br /><br />All hail the chart-makers, for they shall inherit the earth! <br /><br /><i>We don't make anything any more.</i></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><br />But we do.<br /><br />The chart-makers just can't see it.<br /><br />......<br /><br />When steam relegated the horse to a luxury, the wailing sounded a keen note. Blacksmiths, tanners, farriers, your services are no longer needed! You shall drive trains, mend engines, cast metal, all to feed the new metal equines! Things will be more efficient, quicker, more productive. We can do the work of 10 men with 1 man! Those who tallied ledgers laughed excitedly at all the black ink they would need for their account books; surely red ink would be the preserve only of those unfortunate enough to find themselves on the wrong side of this revolution? But red ink continued to be produced, and the crafts that had been practised for a thousand years were slowly forgotten. <br /><br />Then, a century hence, the wailing begun again. Steam? A historical irrelevance! Internal combustion and electricity are far more reliable, efficient and predictable. No more water towers to fill and maintain at every station, no more coal stokers, no more steam engineers! And these crafts also fell into abeyance, replaced with electricians and mechanics who each did the work of 10 men. And still the red ink was needed by those who tallied ledgers, their initial excitement gradually worn away as their predecessors' had been, a sour cloud of unfulfilled expectations emanating from accounting rooms everywhere as those messy, unpredictable variables stubbornly refused to yield to the new technological constants that were supposed to do away with the chaos of manned labour.<br /><br />After another 70 years or so, enough time had passed for those doomed to repeat history to believe that their time had come. Computerisation meant that the electricians and mechanics, with their specialised training, knowledge of arcane physics and militant unionism, were no longer needed. The mechanical was becoming the digital. Slowly, gradually, inexorably, the levers of day-to-day power were moving further away from men whose hands were covered in dirt to men whose hands had never known such indignity. The blacksmith had become the metal worker, who had become the mechanic, who was becoming the engineer, and soon he would become the developer. The revolutions were coming ever quicker; even the accountants has started to work more with charts than ledgers, and it was only a matter of time. The digital revolution was here and the remnants of the old revolutions needed to be purged to make way. The mine, the mill, the factory, these were legacies from a past time that had no place in the new order. Again the keening wail, frustrated and helpless in the face of relentless progress, again the inevitable loss of the skills and the communities that formed around them. And as before 1 man did the work of 10 men, and those who were becoming chart-makers thought nothing of this except as it affected the colour of the font in their new digital ledgers. <br /><br />Now, we stand as our predecessors did 30, 100, 200 years ago, a decade or more after the last revolution and staring the chart-makers squarely in the eye. We are caught frozen in a moment of calm before we tip one way or another as the momentum of the world shifts to compensate for the weight of the now obsolete craftsmen that have been pushed to the side.<br /><br />But in their absence a new breed of craftsman has arisen. The architect, the graphic designer, the UX specialist, the technical writer - these are the modern stone mason, printer, fresco painter, scribe. Plant maintenance is now IT Operations, the mechanic is the developer. Where once we made horseshoes, now we build containers, where before we listened to our machine to find their problem, now we step through their innards and debug them. Just as in preceding revolutions, the change has opened as much opportunity for us messy variables as it has closed previous avenues.<br /><br />Of course the chart-makers would claim this was their certainty all along. Opportunity for all! But this time the opportunities can be grasped by people using the very tools that have pushed their existing skills to the side and that's not the doing of those who would measure progress using graphs. For graphs measure things, but that measurement has meaning only to those who find it meaningful. To those who measure things not by lines or trends or bars, but integrity, dignity and human relationships, the chart-makers' obsession with these numbers is a measure only of the distance between them and the craftsmen.</span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><br />The chart-makers glide through white corridors, cradling the magic screens that give them purpose and value, to glass-walled sanctums of design and certainty. Outside these numerical monasteries the craftsmen toil, designing, sweating, thinking, building, drinking, testing, checking, laughing, smelling, living, messy variables that defy the digital constants to produce the magic that runs the screens. The craftsmen know that the numbers are malleable, because the craftsm<span style="font-family: "arial" , "helvetica" , sans-serif;">e</span>n make the magic that shows the numbers. <br /><br />Everything the chart-makers do is allowed only by the craftsmen. Every trend-line, pie chart, scatter graph, presentation, calculation, prediction and report, everything they drive, everything they wear, everything they use, their entire world is predicated on the craftsmen, because the craftsmen are everywhere and their magic has seeped into every item, object, tool, process, and system. <br /><br />We don't make anything any more. We make everything.<br /><br />But the divide between craftsm<span style="font-family: "arial" , "helvetica" , sans-serif;">e</span>n and chart-makers is wide, too wide for either side's truth to bridge. <br /><br />So the chart-makers continue, bathing in the sterility of their quiet, calm, rational numbers. And when the next revolution comes and the digital craftsmen feel the impotent rage of obsolescence, the chart-makers will point proudly to their charts and proclaim "We were right!". The brave new world will once again forget the skills of the craftsmen from this age but the trend-lines will keep going up.</span><br />
<br />
<span style="font-family: "arial" , "helvetica" , sans-serif;">The charts don't lie. They never lie, not to the chart-makers. </span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><br /></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-75297499012281847052017-03-19T07:51:00.000+00:002017-03-19T07:51:44.342+00:00What's the Biggest Challenge You Face with SharePoint?<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgT93HYhbDUBGQ399q1SHmXs546NUX5YlfCKo-0gE9dRECHE0ZErYzqIo1o5AzyUGU8AKeTHpwnfWCxvTagOoFRvsrjJpHopcgDT3hyQqiro3G2mlUDgt6F-tXbp3NxI0mpHSVN_CL4cjI/s1600/magic-cube-378543_960_720.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="266" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgT93HYhbDUBGQ399q1SHmXs546NUX5YlfCKo-0gE9dRECHE0ZErYzqIo1o5AzyUGU8AKeTHpwnfWCxvTagOoFRvsrjJpHopcgDT3hyQqiro3G2mlUDgt6F-tXbp3NxI0mpHSVN_CL4cjI/s400/magic-cube-378543_960_720.jpg" width="400" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjmNd13KeP_gtly5DY0V7gEWR1lBUnIt1yUb2m4D9UveNYscF3N1NpHoabJ3JgB1katkmN0n0tWDB4h9Qo3dl4N2xsfkQMF4MeNuoY0L9CFecHKket7FHu4NPCFGfz366ghdT6fWpXjvdY/s1600/SharePoint.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><br /></a></div>
<div style="text-align: center;">
<br /></div>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">I recently had a conversation with someone that went something like this:<br /><br /><span style="font-family: Georgia,"Times New Roman",serif;"><b>Him:</b> "So what do you do then?"</span></span></span><br />
<span style="font-family: Georgia,"Times New Roman",serif;"><span style="font-size: small;"><br /><b>Me:</b> "I'm a Knowledge Management Consultant. I'm currently helping a client implement SharePoint."</span></span><br />
<span style="font-family: Georgia,"Times New Roman",serif;"><span style="font-size: small;"><br /><b>Him: </b>"Oh, that's interesting. We've just started using SharePoint and we're struggling with getting the right branding and styling on our publishing site. Any tips you can give me on working with their CSS?"</span></span><br />
<span style="font-family: Georgia,"Times New Roman",serif;"><span style="font-size: small;"><br /><b>Me:</b> "Not really, I tend to work on the content management and collaboration parts, rather than the publishing side of it. But the Microsoft help material is very good and I can point you...."</span></span><br />
<span style="font-family: Georgia,"Times New Roman",serif;"><span style="font-size: small;"><br /><b>Him [interrupting]: </b>"What do you mean, you don't do publishing sites? I thought you said you were a consultant?"</span></span><br />
<span style="font-family: Georgia,"Times New Roman",serif;"><span style="font-size: small;"><br /><b>Me:</b> "I am, but SharePoint is..."</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><span style="font-family: Georgia,"Times New Roman",serif;"><br /><b>Him:</b> "So you don't know what you're talking about then?"</span><br /><br />The conversation went downhill from there, as my interlocutor almost, but not quite, accused me of lying about what I did and got increasingly irate and frustrated. In the end we parted company with him still muttering and me shaking my head ruefully.<br /><br />Now you might instinctively think bad thoughts about my ill-tempered friend, but that would be a knee-jerk reaction. He was clearly struggling with a complicated and powerful piece of software, and meeting someone who might be able to bring some light to the shadows must have gotten his hopes up, hopes which I promptly dashed. It's only natural that he was frustrated, even if he didn't necessarily express that in the most constructive way. What's more instructive about this encounter is that it represented a microcosm of the way an entire enterprise often feels about implementing SharePoint.</span></span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">If you've encountered SharePoint before then the likelihood is that your experience hasn't been overwhelmingly good. I've met more far more people with negative things to say about SharePoint than I have people with positive things. It's like the England football team - depressing, confusing, poorly performing, promising lots and delivering little. But like the England football team, SharePoint's individual components are good, yet the sum seems to be less than the whole of its parts. To continue this analogy one stage further, the management just doesn't seem able to turn a collection of good things into a better coherent whole.<br /><br />The question is: Why not?<br /><br />Let's start an answer to that with the obvious point that SharePoint is large and complicated. If you have SharePoint then you're going have Microsoft Office, which increases both the size and the complexity by a significant factor. Office itself can be pretty difficult to get to grips with as a whole, when you've got both client and online versions, as well as lots of tools that weren't in the traditional Office package of a few years ago, like Sway, Planner and Video. Then there's OneDrive, which is actually just a personal SharePoint site with a front-end, and Power Apps, Flow and Delve. The sheer number of these apps is dizzying, and they all work together if you want them to, and each one is a whole book and training session on their own just to get comfortable with the basics. Even programs as venerable and well-know as Word, PowerPoint, Excel and Outlook have lots of functionality that most users never know about or haven't got to grips with. Then you add a powerful electronic document and records management system like SharePoint on top of all that and dear Lord, where on Earth do you even begin?<br /><br />This alone is enough to put a lot of people off, and not just users. Designing, implementing, training and supporting that kind of enterprise-level suite of applications, with its mind-boggling array of options, parameters and functionality, is not a job for the faint-hearted or workshy. For users it can be even more daunting because they're not supposed to be the experts and usually have very little time to dedicate to learning these tools.<br /><br />The biggest part of this problem is that often the people deciding to use SharePoint underestimate the investment of time and resources needed to design, implement and support it, and they <i>seriously</i> underestimate the investment of time and resources needed to train users. Many a C-level decision-maker has seen a demonstration, or worked in another company with a successful SharePoint implementation, or seen that it's a highly-recommended tool by a relevant professional body. These are all valid reasons (although not sufficient on their own) for choosing SharePoint, but they're not valid reasons for thinking that SharePoint is easy, simple or quick to implement and maintain. If you've seen SharePoint working well then you can't even begin to imagine how much work has gone into making that happen.<br /><br />It's worth saying as well that when users struggle with SharePoint it's not always because it hasn't been implemented well. SharePoint is so large that you can't even hire a consultant direct from Microsoft that knows all of it to a significant degree. It's also not the most intuitive experience, which makes learning it harder. Training users is always easier when an application has obvious signposts and markers for the users, because once they've got a rough idea of how things work they can generally find their way around and work out how to do things using these signposts and markers. But there are plenty of areas in SharePoint where these signposts and markers are missing, often because a certain feature or parameter is "owned" by one application within SharePoint/O365, so you can only get to it from that application. This means a lot more rote learning is required to know how to do things. On an application as large and complicated as SharePoint this means that the learning curve is high, which acts as a significant barrier to adoption across a business. <br /><br />When you take these problems together - the size, the complexity, the difficulty learning it - it becomes easier to understand why my frustrated friend felt like he was banging his head against a brick wall. He's most likely up against a deadline, he's faced with a suite of applications that is so large it's very difficult to know where to start, and when he does start the amount of learning to be done must feel insurmountable.<br /><br />All of which leads to the reason that many companies struggle to have a successful implementation of SharePoint: <i><b>It's not a one-off implementation, it's an ongoing process of training, learning and incremental advances for the entire life of the application.</b></i> <br /><br />Every user needs to be trained, and not just with a 60 minute introductory session. Every new starter has to be trained. Existing staff have to have access to refresher training. Training material needs to be updated as new functionality is released. Content and working practises have to be analysed so they can be successfully migrated. Deletion, retention and preservation policies must be decided and implemented from the very start. Metadata must be applied to migrated content and added to all new content. Workflows must be designed, created and added. Security must be applied. And throughout all this you have to deal with the change management aspects by engaging the users, communicating the plans and timelines, quelling fears, and listening to concerns. If you can do all this, and still meet your success criteria then you'll have a successful implementation.<br /><br />SharePoint is not an application, it's a long-term commitment of people and time.<br /><br /><br /><br /><i>(Note: A cardinal rule on this blog is that I never discuss current or previous clients. Nothing from this post should be inferred about any company I've worked for; as always this is a general discussion about issues that we find in our industry.)</i><br /><br /><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-61842536873172945872017-02-05T12:40:00.000+00:002017-02-05T12:40:05.015+00:00The Basics: 12 Steps to Writing a Great Knowledge Base Article<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgVeffTCwjpw6_nZrK1jZSfa7-Fl1UvUrPpFlWvq0JOY1hEwxs-XJiNhRFB4VH2oQCOMDV2FPk5ot4i_s_g_2f0GBZD3CIIzmxL1MCQpY_Fp7m7yhK5e8LwGjjU8Ixcn20lRC71qNmXZR4/s1600/Knowedlge+is+Power.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="302" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgVeffTCwjpw6_nZrK1jZSfa7-Fl1UvUrPpFlWvq0JOY1hEwxs-XJiNhRFB4VH2oQCOMDV2FPk5ot4i_s_g_2f0GBZD3CIIzmxL1MCQpY_Fp7m7yhK5e8LwGjjU8Ixcn20lRC71qNmXZR4/s400/Knowedlge+is+Power.jpg" width="400" /></a></div>
<div style="text-align: center;">
<br /></div>
<span style="font-family: Arial,Helvetica,sans-serif;"></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Knowledge Base (KB) articles are normally technical and as such in the realm of the technical writer. Where an FAQ might encourage you to try a new product or feature, a KB article helps a user get past a problem when they're already using that product or feature. So if FAQs represent "sales self service", KB articles represent "support self service". </span></span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">With this in mind, you should focus your initial efforts on writing KB articles that will answer the most asked support questions. This will provide <a href="http://www.agiledocumentation.co.uk/2015/07/improving-documentation-roi-part-4-time.html" target="_blank">the greatest return on investment for your documentation</a>. Once you've built up a library of articles, you should try to move to a position where new KB articles are written in response to incoming customer questions. Ideally, if a customer asks a question once, and the answer isn't publicly available, you'll publish a KB article answering that question within a short period of time </span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">But how do you write a good KB article? Well, the basics of writing good documentation don't change, but there are a few things which are more important when writing KB articles. Let's got through them below.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">1. Know the subject</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">First and foremost, don't publish an article unless you're certain it's correct. This applies to experienced staff who think they know exactly how the product works just as much as it applies to less experienced staff. As an example, I once wrote a KB article on the possible permutations of accounts and permissions that could be setup for a web application and IIS, but I'd misunderstood the scope of the question. The result was a rewrite that took some time because the people who understood the technical side were difficult to get hold of, and more importantly it confused a couple of customers, which was the worst possible outcome. This leads directly to #2.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">2. Proof read for technical correctness</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Get 2 different people to proof read it if necessary. There's no shame in asking for the input and oversight of people who are more technically qualified or experienced than you. As a technical writer you are expected to understand technical issues so you can communicate them, but you're not expected to know all of the technicalities of a product better than anyone else. That's why you have architects, designers, administrators, installation experts, etc. Use them.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">3. Iterate. Then iterate. Then iterate again.</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Preferably find someone who doesn't know how to perform the actions you're explaining and ask them follow the instructions through. If they don't understand it first time, or they ask about an ambiguity, alter the article until it's clear and unambiguous. This is not a negative step, it's a necessary part of writing a good piece of technical documentation. A KB article can deal with complex issues that can be even more complex to explain, so the first draft of a KB is unlikely to be the last. Write, test, alter, repeat.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">4. Don't overestimate the reader's knowledge</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">AKA Know Your Audience. If you're writing for a data entry operator then take the time to explain things that seem obvious to you. Remember, if you weren't knowledgeable enough about the software to write technical documentation about it, you wouldn't be writing KB articles. You know more than your target audience so walk them through things if necessary.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">5. Don't underestimate the reader's knowledge</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">AKA Know Your Audience part II. If you're writing for a System Administrator then try to avoid the whole "teaching your grandmother to suck eggs" thing. It's a tricky balancing act but if the target audience is (supposedly) technically competent or highly knowledgeable then they won't thank you for wasting their time or making them feel stupid.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">6. Make it modular</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">If you find yourself walking through the same process in more than one KB article, then write a separate article that just deals with that process and link to it in future articles. This saves you time and helps the user by not cluttering up articles with information that's duplicated elsewhere.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">7. KISS</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">The old "Keep It Simple, Stupid" acronym. In the case of KB articles, this means that you should try to capture one task or process in one article. Don't try to cram too much in, and don't shy away from writing a series of articles that deal with the distinct stages of a complicated process. At the start of each article in the series tell the reader that they should be familiar with the information in the preceding articles before continuing. This allows them to feel that they are making progress and allows you to write self-contained articles that just deal with the problem in hand. </span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">8. Step-by-step</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Don't explain a process in a paragraph. Use a numbered list, and make 1 numbered point = 1 step. As a rule of thumb, if there is more than 1 action in 1 numbered point then turn it into 2 numbered points.<br /><br />This goes hand-in-hand with points 4 and 5 about knowing your audience. If you're writing for System Administrators who know the product, don't be afraid to write:<br /><br />"1. Log into the application and navigate to screen x" <br /><br />Equally, if you're writing for potentially inexperienced users don't be afraid to write:<br /><br />"1. Log into the application."<br />"2. Navigate to screen x. In a default setup this will be located at System > Parameters > screen x"<br /><br />Generally paragraphs should be used to explain something from a conceptual perspective and numbered lists should be used to explain actions and steps.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">9. One Step, One Screenshot</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">If you write an article with 10 steps, use a good screenshot for each one if it will help the user. A picture tells a thousand words when you're trying to understand something new. Users aren't short of the bandwidth needed to download a 20kb png file and I know that the use of screenshots is controversial, but don't preclude them on a point of principle.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">10. One Screenshot, One Lawsuit</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">I can't say this enough: Check your data. I have seen a KB article published by a colleague who'd taken screenshots using a live database, and those screenshots included identifiable information about customers. If you have access to live databases, or, as if sometimes the case in development teams, a customer database provided for the purposes of testing, then check, check and recheck your data. If in doubt, create dummy data, and if you can't then obfuscate any data or consider not using screenshots. Using live or customer data is a one way ticket to a lawsuit for your company and quite possibly the sack for you.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">11. Quality, not Quantity</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Yes, it looks great if you bang out 20 KB articles in an afternoon, but it doesn't look so great a week later if 19 of them have been the cause of support tickets. You're supposed to be helping support, not making more work for them. You can't rely on a proofreader to weed out every mistake, because it may be that you're the person who's supposed to be an expert on whatever it is you're writing about (this is especially the case if you're not a technical writer and you're adding KB articles). Writing KB articles is not a fast and easy way to look good. It is difficult to write well, and even more difficult to write well at speed. Take your time, think about what you're doing, focus on getting it clear and correct.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">12. Spell check is not optional</span></span></h4>
<h4>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h4>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">If you're a technical writer you'll know this, but if you're not then hear this: You can't spell. Seriously. Technical writers do this for a living and we spellcheck everything. Learn to love Word and its spell checking, grammar checking, and little squiggly lines. These is no excuse for a spelling error in a KB article and it will make you look incompetent. It will also make your company look incompetent and reflects badly on everyone. Don't be the person who makes your users wonder how on Earth your company can write decent code if they can't even use a spellchecker.</span></span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">KB articles are a great way to take the load off support and give customers the power to fix their own problems. Get it right and you'll find the rewards far outweigh the costs.</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"> </span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-81659666557156194132017-01-28T12:17:00.000+00:002017-06-20T18:00:29.001+01:00A List of Style Guides for Writers<div class="separator" style="clear: both; text-align: center;">
</div>
<div style="text-align: center;">
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
<span style="font-size: small;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi_l3qkI09WY1y_nd3jcqPiXIN_5-3P1p3jrx9BEIx-ELTHHKQ6l9r-DKScDaKgBnxKP1BKBVO1KZ07jIbEx61CGeQyzLEiKxiA3cW3HNi3NEZUiWrNOYqZb-ULpYyHFKJgzkIz4DDYbdI/s1600/Style+Guide.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="266" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi_l3qkI09WY1y_nd3jcqPiXIN_5-3P1p3jrx9BEIx-ELTHHKQ6l9r-DKScDaKgBnxKP1BKBVO1KZ07jIbEx61CGeQyzLEiKxiA3cW3HNi3NEZUiWrNOYqZb-ULpYyHFKJgzkIz4DDYbdI/s400/Style+Guide.jpg" width="400" /></a></span></div>
<br />
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Style guides cover a multitude of areas and it can sometimes be difficult to separate the purely writing-focused guides from the general UI/UX guides. This is not surprising, considering how much UI/UX, technical writing and comms/marketing are starting to coalesce around the central idea of user focused design. But if you're not working in that environment, or if you are but you still want some purely writing focused resources, it can be a little difficult to sort the wheat from the chaff.</span></span><br />
<br />
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">With that in mind, I've put together a list of some useful guides below:</span></span><br />
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><br /></span></span>
<br />
<h3>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Online</span></span></h3>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="http://voiceandtone.com/success-message" target="_blank">MailChimp</a> - One of my absolute favourites because they focus on the likely user mood at the point of the interaction, and tailor their writing accordingly. This is a relatively unknown style guide, but it should absolutely be one that you spend time looking through.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Writing_style_guide" target="_blank">Mozilla</a> - A (relatively) short and to the point style guide that focuses on developer documentation. If you write for developers (SDK, API, etc) then this is an excellent resource.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/OSXHIGuidelines/TerminologyWording.html#//apple_ref/doc/uid/20000957-CH15-SW1" target="_blank">Apple</a> - As you would expect from Apple, this is not the longest style guide but it is proscriptive. One of the most useful features is the table that converts "developer speak" to "user speak", so for example "focus ring" for an Apple developer is Highlighted area" or "area ready to accept user input" for an Apple user.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://material.io/guidelines/style/writing.html" target="_blank">Google</a> - This focuses on writing for a worldwide audience and as such is concerned with clarity and simplicity above all. If you're writing for a geographically diverse audience, especially one which is not highly technical, then this guide will help you a lot.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.gov.uk/guidance/style-guide" target="_blank">GDS</a> - The Government Digital Service guidelines for the UK Civil Service. Not as easy to navigate as many guides, because topics are provided in an A-Z format rather than curated into groups, but contains a lot of information and is recommended if you're writing in UK-English. (The lack of curation is odd; GDS people are normally very big on user-focused design, and this...isn't. But if you can get past that, the information contained is often difficult to find elsewhere.) </span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="http://18f.gov/">18f.gov</a> - The American equivalent of the GDS style-guide, this is focused more on US-English and the needs of federal/state public bodies, as you would expect. But it's comprehensive, well-written and very good on grammar and "correct" writing so even if you're not writing in US-English, it's still a very useful resource. And if you ARE writing in US-English, it's indispensable.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.microsoft.com/Language/en-US/StyleGuides.aspx" target="_blank">Microsoft</a> - Microsoft provide one of the best known and popular style guides in print (see below) but this resource is far too valuable to miss off the list. The link takes you to a page with just a single dropdown, from which you can download a PDF style and language guide for just about every language you've ever heard of, and many you haven't. French, German and Russian are fairly obvious, but how about Khmer, Igbo and Xhosa (the African language with the clicks)? If you write in any language other than English then this is probably the single most valuable guide on this list.</span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></span><br />
<h3>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Print</span></span></h3>
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.amazon.co.uk/Elements-Style-Classic-Writing-Guide/dp/1537669648/ref=sr_1_2?s=books&ie=UTF8&qid=1485597680&sr=1-2&keywords=style+guides+writing" target="_blank">The Elements of Style</a> - The classic book on how to write. The focus is not on software documentation (unsurprisingly, as it was first published in 1920), but not having a copy of this is like being a quantum physicist who's never read Einstein's papers on relativity. Some things are just fundamental to your profession.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.amazon.co.uk/d/cka/Economist-Style-Guide-11th/1781253129/ref=sr_1_3?s=books&ie=UTF8&qid=1485597680&sr=1-3&keywords=style+guides+writing" target="_blank">The Economist Style Guide</a> - Another without a software focus, and the first edition was published 30+ years ago, but if you want to write clearly and - according to the Economist - with a little flair, this is the book for you. Its best feature is undoubtedly its effort to focus on real-world examples that are universal in application without being generic to the point of mere common sense.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.amazon.co.uk/Chicago-Manual-Style-Essential-Publishers/dp/0226104206/ref=sr_1_8?s=books&ie=UTF8&qid=1485597680&sr=1-8&keywords=style+guides+writing" target="_blank">The Chicago Manual of Style</a> - If you've only heard of 1 style guide, the chances are it's this one. Now on it's 16th edition, it includes specialised sections on writing for digital technologies, including writing with XML. If your office doesn't have this on its bookshelf, it should be because you've got the next guide on our list.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.amazon.co.uk/Microsoft-Manual-Style-Professional-Communications/dp/0735648719/ref=sr_1_3?s=books&ie=UTF8&qid=1485597760&sr=1-3&keywords=microsoft+writing+technical+documentation" target="_blank">Microsoft Manual of Style</a> - A slightly more specialised guide than Chicago, but no less useful for it (and probably more so if you're a technical writer). Unless you write software for Apple and only Apple, this guide will show you why so much software documentation has the style and tone that it does.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.amazon.co.uk/IBM-Style-Guide-Conventions-Writers/dp/0132101300/ref=sr_1_1?s=books&ie=UTF8&qid=1485597742&sr=1-1&keywords=ibm+writing+technical+documentation" target="_blank">The IBM Style Guide</a> - One of the most comprehensive style guides available for the modern technical writer. It is particularly strong on Information Architecture and content design, but don't let that fool you: this is a standout resource for all writers.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.amazon.co.uk/d/Books/Developing-Quality-Technical-Information-Handbook/0137903200/ref=sr_1_2?s=books&ie=UTF8&qid=1485597742&sr=1-2&keywords=ibm+writing+technical+documentation" target="_blank">Developing Quality Technical Information</a> - Another IBM publication and not strictly a guide, but so useful that leaving it off the list for that reason would be petty. There is significant overlap with the IBM Style Guide, but this focuses more on training you and less on being a reference work. Unless you're an acknowledged expert in technical documentation, you'll gain a great deal from this book.</span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">There are lots more style guides out there. If you have a favourite that's not in the list then tell me in the comments and I'll add it in.</span></span><br />
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-52781902448958250782017-01-07T14:25:00.000+00:002018-05-20T13:53:44.799+01:00The Basics: Diacritics and ALT Codes<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><i> </i></span></span><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjpYHvZ8FIaoVmskGjyZTfGjvuCxAvANLbZcIhucYQ1n5lLHpzR1yuG8Vl6nUl8ErbDucMLF2CFztRpHwauIfHkldPqwaOpoGDW59KaKUrBCkCmGuNxRRkCKhbm-0HXim4ultTFWHSPmhU/s1600/Diacritics+Header.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img alt="Text with colourful accents" border="0" height="264" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjpYHvZ8FIaoVmskGjyZTfGjvuCxAvANLbZcIhucYQ1n5lLHpzR1yuG8Vl6nUl8ErbDucMLF2CFztRpHwauIfHkldPqwaOpoGDW59KaKUrBCkCmGuNxRRkCKhbm-0HXim4ultTFWHSPmhU/s640/Diacritics+Header.png" title="Text With Colourful Accents" width="640" /></a></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><i>This post was inspired by Lori Kaufman's post on How To Geek about adding symbols. She writes a <a href="http://www.howtogeek.com/author/lorikaufman/" target="_blank">regular column</a> on how to do useful things with common applications, and it's very much worth following</i>.<br /><br />It might seem odd to label a post about diacritics and ALT codes under "The Basics" when most people don't even know what the word "diacritic" means, nor have they used ALT codes. But you've seen diacritics, and quite possibly used them, even if you don't know what they are, so you definitely need to know how to add them when you're writing. And the easiest way to add them is with ALT codes.</span></span><br />
<br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">So, what is a diacritic?<br /><br />(Warning: If you've studied linguistics, philology or a European language to any extent you can probably skip down to the part about how to add them to your documents. For everyone else, read on.)<br /><br />A diacritic is a symbol or glyph added to a letter, primarily to show how that letter is to be pronounced in the context of the word. If you ever studied French at school you'll be familiar with accents such as </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>´</b> (acute)</span></span> or </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>`</b> (grave)</span></span>; accents are a type of diacritical mark. For those of you with a more Germanic bent you'll be familiar with the </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>¨</b> (</span></span>umlaut), but even if you've never spoken a language other than English you should still be familiar with the diacritics in façade and </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">naïve </span>(called a cedilla and diaereses respectively). A good example of how a diacritic changes the pronunciation of the word is "r</span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><b><span style="font-size: small;">è</span></b></span></span></span>sum</span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><b><span style="font-size: small;">è</span></b><span style="font-size: small;">" (also known as a CV)</span></span>, where only the accents distinguish it from "resume" (to begin again after a pause).<br /><br />There is plenty of material available on the use of diacritics if you want to delve into it a bit more (and please do, they're fascinating), but what we're concerned with here is how to add these marks when using standard technical communication tools. </span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Adding Diacritics to your Content</span></span></h3>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">We'll focus on 3 types of documentation tool: word processing, content authoring, and wikis. Between them, these cover the vast majority of types of tools that are used for professional technical communication (we're ignoring things like <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html" target="_blank">JavaDocs</a> or <a href="http://swagger.io/" target="_blank">Swagger</a> on the basis that code doesn't have accents). There are a lot of different tools out there, so I'll focus on the following examples:</span></span><br />
<ul>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>Word </b>(word processing)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>FrameMaker </b>(content authoring)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>Confluence </b>(wiki)</span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"></span><br /><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></li>
</ul>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Each of these tools provides built-in fonts and/or glyphs that cover diacritics, as will any decent word processing or content authoring tool. Wikis are often a bit different because they have more or less of a GUI or WYSIWYG interface. As a general rule, the less GUI, the less built-in support you'll get. Confluence does have built-in diacritics, but once we've covered the 3 tool examples we'll look at a more general method for typing diacritics.</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Word</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Word - of course - provides pretty much complete support for every conceivable diacritical mark, of which, when combined with every letter of every currently used alphabet, there are a very large number indeed. For common words like "facade", Word will simply autocorrect them, in this case to "</span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">façade </span></span>". That will probably cover you for most English words, simply because English has only <a href="https://en.wikipedia.org/wiki/Diacritic#English" target="_blank">a small number of words with diacritical marks</a>. But it's always better to know how to do things manually if you have to, so in Word go to <b>Insert </b>on the ribbon and on the far right hand side click the down arrow next to <b>Symbol</b>. On the small dropdown that appears click <b>More Symbols</b> to open the Symbol dialogue:</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"></span></span><br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEipEil75RbyKpPQfiAJ9uDXNDlgJie0pfZWZxGUMpDmVCxRMsKTXf1gL8aIXlgDtc9_mTDA1KyLAO93mdMolg7Ne7YsiswO67SAB2WR12U3ZvuT3UM5PjiTub4TTi2uyk8Ufma4lIxTeSE/s1600/The+Basics+-+Diacritics+and+ALT+Codes+-+Word.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="290" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEipEil75RbyKpPQfiAJ9uDXNDlgJie0pfZWZxGUMpDmVCxRMsKTXf1gL8aIXlgDtc9_mTDA1KyLAO93mdMolg7Ne7YsiswO67SAB2WR12U3ZvuT3UM5PjiTub4TTi2uyk8Ufma4lIxTeSE/s400/The+Basics+-+Diacritics+and+ALT+Codes+-+Word.png" width="400" /></a></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br />(For you keyboard shortcut aficionados, you can also access this dialogue with ALT+N+U+M)<br /><br />By default, this dialogue will open with a <b>Font</b> value of (normal text) and a <b>Subset</b> value of Basic Latin. This will display the familiar Latin alphabet and if you scroll down you'll find lots of diacritically marked letters, grouped into language families. For example, the French diacritics are together, the Slavic ones are together, and so on.<br /><br />Select the <b>Font</b> you want, if it's different from the font you're currently using, and scroll down the list. You will almost certainly find the letter and diacritic combination you want, whether it's the familiar Latin-derived alphabet, Cyrillic, or Greek. If you want to know the official name of a symbol, click the character and the <b>Unicode name</b> will be displayed under the <b>Recently used symbols</b> box. In the screenshot above, I've selected "Latin Small Letter A With Tilde".</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">FrameMaker</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">FrameMaker also provides a way of adding diacritical marks, but in a far smaller range than Word. The list of supported diacritics is as follows:</span></span><br />
<ul>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">´ (acute)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">` (grave)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">˜ (tilde)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">¨ (diaeresis)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">ˆ (circumflex)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">^ (caret)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">° (ring)</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">¸ (cedilla) </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"></span><br /><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></li>
</ul>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">(For those of you who did a little German at school, a diaeresis is identical in formation to an umlaut, although <a href="http://desktoppub.about.com/cs/expertcharacters/a/diacriticals_2.htm" target="_blank">they alter the word in slightly different ways</a>). FrameMaker allows you to enter these supported diacritics by using an Escape key sequence. For example, to type an </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><b>è</b></span></span> (an e with a grave accent) you press the <b>Escape </b>key, then the ` (left quote) key, then the <b>e</b> key. Unlike CTRL+ALT+DEL where all of the keys need to be pressed at the same time (i.e. in combination), in FrameMaker you need to press them one after the other (i.e. in sequence).<br /><br />You can find the list of FrameMaker-supported diacritics and other symbols <a href="http://help.adobe.com/en_US/framemaker/2015/using/using-framemaker-2015/frm_references_re/frm_shortcuts_sh/Entering_special_characters-.htm?rhhlterm=accent&rhsyns=%20" target="_blank">here</a>.</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Confluence</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Confluence
lies somewhere in the middle. It provides more diacritics than
FrameMaker, but substantially less than Word. Like Word, you can select
your diacritic from a modal panel rather than with a keyboard sequence
and the following shows all of the diacritics and symbols that are
available to select:</span></span></span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"> </span></span> </span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h3>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhOeSf3xyKZRCy-D4PVbcJ74GX7whfsvmzvno45DKcVPAXi8t3HvPCkO3Qx9UGGN8O_YCtIRvtbsYGCjESLC1HzXeE0o8N9Fm2XneTV1imgawg01Jt0f31oOS_84LEwUsxRsgHKjCDK9-o/s1600/Confluence+Symbols.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="297" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhOeSf3xyKZRCy-D4PVbcJ74GX7whfsvmzvno45DKcVPAXi8t3HvPCkO3Qx9UGGN8O_YCtIRvtbsYGCjESLC1HzXeE0o8N9Fm2XneTV1imgawg01Jt0f31oOS_84LEwUsxRsgHKjCDK9-o/s400/Confluence+Symbols.png" width="400" /></a></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br />These are good examples of the type of functionality you'll find around diacritics in modern tech comm tools. They range from the comprehensive to the minimal, but they're still better than some applications that provide no functionality at all.</span></span><br />
<br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">What's the generic way of entering diacritics?</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Different applications have different methods for entering diacritics, and different native support, which means more learning and a patchy experience. So for those of you looking for a generic way that will work in any application, you need <b>ALT codes</b>.<br /><br /><a href="https://en.wikipedia.org/wiki/Alt_code" target="_blank">ALT codes</a> are a method of writing special characters that aren't represented on the keyboard. Pressing the ALT key (or Option on a Mac) and a number on the numeric keypad will display the special character. For example, ALT+138 will type <b>è</b>, an e with a grave accent. You can find a complete list of the basic ALT codes <a href="http://www.alt-codes.net/" target="_blank">here</a>. Note that you need to use the numeric keypad - the square of numbers on the right hand side of a standard keyboard - to type these in.<br /><br />However, there is a little more to it than that, because some ALT codes do the same thing. If you type ALT+0232 you'll get the same è that you do with ALT+138, which seems...odd. What's going on?</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"></span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">An Incredibly Brief History of ALT Codes</span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Historically, ALT codes were used in early Microsoft computers to access the character set that couldn't be typed using the standard keyboard. The early DOS machines were based on the IBM architecture which used a character set called <b>code page 437</b>, and the ALT codes for these are ALT+0 - 255. In this character set ALT+138 gives you the è. Because this character set comes from the architecture and not the operating system it's known as the OEM-encoded (Original Equipment Manufacturer) character set. (Originally IBM used the ISO 7-bit character set that went from 0 - 127, but the ISO extended it to 8-bit to provide space for non-English characters, which led to the classic 256 character set - known as the extended set - that is so commonly used.) <br /><br />But 256 characters is quite limited, and other architectures slowly emerged as well, so Microsoft decided to use their own, additional character set, which is known technically as Window's ANSI/ISO Latin-1/ANSI Extended ASCII. This provided additional space for more codes by prefixing them with a 0, and in this Windows-encoded character set ALT+0232 will produce è. </span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">You can download an ALT code cheat sheet in PDF format <a href="http://usefulshortcuts.com/downloads/ALT-Codes.pdf" target="_blank">here</a>
(Warning: link goes straight to the PDF) that includes both the OEM-
and Windows-encoded ALT codes, grouped together in useful sections
rather than a numeric list. </span></span><br />
<br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Unicode </span></span></h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">In modern incarnations of Windows the Unicode 16-bit character set is used, as it's the global standard, but the original OEM- and Windows-encoded character sets are still there and the ALT codes for those still work. </span></span><br />
<br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Because the Unicode 16-bit character set is vast (see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/dd374069(v=vs.85).aspx" target="_blank">here</a> for some figures, but as a spoiler there are over 70,000 encoded Chinese characters alone), remembering even a tiny fraction of the codes that represent them is beyond mere mortals. Luckily Windows includes a Character Map that will show you all of the available characters and tell you what their ALT code is. To access this pre-Windows 10, type <b>Character Map</b> in Windows search. In Windows 10 the Character Map is - for reasons known only to Microsoft - hidden away, and you'll have to launch it manually. Hit Win+R and enter <b>charmap</b>, and up it'll pop:</span></span><br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgwEC4AqV6unqv5fE8uvvYKsK8LAGukid60qVxzhWZRPgdJiyYV5LgOLWFdDeopBGxi_SJ2RgYPPSU8GEfGKlvPM0Nuud4wXzKoxa01yzW0Cb8nmDoF1tRqWnA0zYIPwvSlnLpt-kkObcc/s1600/Character+Map.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="346" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgwEC4AqV6unqv5fE8uvvYKsK8LAGukid60qVxzhWZRPgdJiyYV5LgOLWFdDeopBGxi_SJ2RgYPPSU8GEfGKlvPM0Nuud4wXzKoxa01yzW0Cb8nmDoF1tRqWnA0zYIPwvSlnLpt-kkObcc/s400/Character+Map.png" width="400" /></a></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">As you can see in the bottom left, the Unicode value is shown for the selected character. To use this as an ALT code just use ALT+[the four digits], in this case 0021.</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">If you switch on the <b>Advanced view</b> checkbox you'll also be able to choose a character set, group by types of ideograph and, most importantly, search for a character. This is very useful when you've got so many characters to search through. In the example below I've search for "grave":</span></span><br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEie3_5ZzkBqDx6xmZ7eXyrKADPqBAkPqntWS3fdhSK3kXUhvbXWJVbAbkpk906swz4NrLtI20wCvUooVz2eVG-d0Gt8C6ef9pXikVfexB4BuyazCUz_D6nZVHO4wKIKbx_Fkivt-RpIDo8/s1600/Character+Map+Advanced+Search.png" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="400" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEie3_5ZzkBqDx6xmZ7eXyrKADPqBAkPqntWS3fdhSK3kXUhvbXWJVbAbkpk906swz4NrLtI20wCvUooVz2eVG-d0Gt8C6ef9pXikVfexB4BuyazCUz_D6nZVHO4wKIKbx_Fkivt-RpIDo8/s400/Character+Map+Advanced+Search.png" width="375" /></a></div>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">The Character Map is probably the single easiest way to search for and find the ALT code you need, and will allow you to handle any diacritics with ease.</span></span><br />
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><br /></span></span>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">The history and technical specification of character sets, and how they're used, is a vast topic. What I've mentioned above is the briefest outline of a long, complex and thoroughly interesting subject. If you're at all interested in the topic then these links are good jumping off points:</span></span><br />
<ul>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Wikipedia on<a href="https://en.wikipedia.org/wiki/Character_encoding" target="_blank"> character sets and encoding</a> </span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A good primer on <a href="https://codeworks.gnomedia.com/archives/2003/programming/a-short-history-of-character-sets/" target="_blank">the history of the ISO character set standards</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A good primer on <a href="https://danielmiessler.com/study/encoding/#gs.jGKNeFc" target="_blank">encoding and encoding history</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">The w3c guide to <a href="https://www.w3.org/International/articles/definitions-characters/" target="_blank">essential concepts in character encoding</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">ASCII Code for <a href="https://www.ascii-codes.com/" target="_blank">code page 437</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">IBM's official (stiff, bland, entirely silent on it's importance) page about <a href="https://www.blogger.com/[https://www-01.ibm.com/software/globalization/ccsid/ccsid437.html" target="_blank">437</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://www.aivosto.com/vbtips/charsets-codepages-dos.html" target="_blank">DOS code pages and their history</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="http://www.aivosto.com/vbtips/charsets-codepages-windows.html" target="_blank">Windows code pages and their history</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://msdn.microsoft.com/en-us/library/windows/desktop/dd317752(v=vs.85).aspx" target="_blank">Characters sets in modern Windows</a></span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;"><a href="https://blogs.msdn.microsoft.com/shawnste/2007/03/13/a-history-of-code-pages-or-what-made-code-page-xxxx-or-many-other-computer-things-the-way-it-is/" target="_blank">A History of Code Pages or What Made Code Page XXXX The Way It Is?</a></span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"></span><br /><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></li>
</ul>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">If you know of other good resources about character sets and encoding for the educated non-developer, put them in the comments.<br /><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-71147562168165184382016-12-10T07:50:00.000+00:002016-12-10T07:50:20.743+00:00AgileTheDocs Presentation Slides and Notes (5th Dec 2016, London) <span style="font-family: Arial,Helvetica,sans-serif;">The lovely people at <a href="https://gds.blog.gov.uk/">GDS</a>, in association with <a href="http://www.writethedocs.org/">Write the Docs</a>, put on a great one day mini-conference, <a href="https://www.meetup.com/Write-The-Docs-London/events/234913157/">Agile the Docs</a>, on 5th December in London. I was asked to present on whether documentation was in the definition of done and I was more than happy to oblige.</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;">Without further ado, here are <a href="https://docs.google.com/presentation/d/1yVvmCj9UqTVPS6dGpfatKOMGBVeQQoe43D8Lkq5U2Cs/edit?usp=sharing" target="_blank">the slides</a> I used, and here are <a href="https://docs.google.com/document/d/1STag-BHbTVkxVKndtvuuhyd7YeTlr61VUr8gYPa0cFs/edit?usp=sharing" target="_blank">the notes</a> (I haven't done a lot of editing or formatting on the notes; the links below contain everything I talked about in a more comprehensive - and formatted - way).</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;">If you're interested in learning more about this topic then check out the following articles:</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"></span><br />
<ul>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="http://www.agiledocumentation.co.uk/2015/02/should-documentation-be-in-definition.html" target="_blank">Should Documentation be in the Definition of Done? </a></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="http://www.agiledocumentation.co.uk/2015/02/factors-that-determine-if-documentation.html" target="_blank">Factors that Determine if Documentation Should be in the Definition of Done</a> </span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="http://www.agiledocumentation.co.uk/2015/02/the-unicorn-at-heart-of-scrum.html" target="_blank">The Unicorn at the Heart of Scrum</a></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="http://www.agiledocumentation.co.uk/2015/02/what-is-water-scrum-fall-and-is-it.html" target="_blank">What is Water-Scrum-Fall and is it inevitable?</a></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="http://www.agiledocumentation.co.uk/2015/02/why-arent-there-more-cross-functional.html" target="_blank">Why Aren't There More Multi-Functional Teams?</a></span><div class="post-title entry-title" itemprop="name">
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span></div>
</li>
</ul>
<span style="font-family: Arial,Helvetica,sans-serif;">Thank you to Trisha, Rosalie, Jen and Lydia from GDS, and Kristof from Writer the Docs. You organised a short, sharp, interesting conference</span><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-family: Arial,Helvetica,sans-serif;"> with interesting and diverse speakers</span>, in a good location, at a sensible time, near a decent pub and a tube station. Top work all round.</span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;">On a side note, the <a href="http://www.brdc.co.uk/" target="_blank">BRDC</a> were having a benefit lunch/gala thing in the same conference centre we were, and this was parked outside:</span><br />
<br />
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiI_Ieds0-YwVP8TSmkWu-t25bWu5BfLEk6w7LLfL-vjpTeg8YIaJUt5D-RKQYeIxGDdG9eOK2brbO6hEPChgAygUrYj0ndfEeTvijrpZRtoTgUgpjY_qIGyt4fBmQT4_arZGAqi_JDe9E/s1600/IMAG0819.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiI_Ieds0-YwVP8TSmkWu-t25bWu5BfLEk6w7LLfL-vjpTeg8YIaJUt5D-RKQYeIxGDdG9eOK2brbO6hEPChgAygUrYj0ndfEeTvijrpZRtoTgUgpjY_qIGyt4fBmQT4_arZGAqi_JDe9E/s320/IMAG0819.jpg" width="181" /></a></div>
<br />
<span style="font-family: Arial,Helvetica,sans-serif;">It's an impressive machine in the flesh. And I saw <a href="http://nigelmansell.co.uk/" target="_blank">Nigel Mansell</a> in the corridor, which was pretty cool. He looks exactly the same as he did when he won the F1 championship 24 years ago </span><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-family: Arial,Helvetica,sans-serif;">(except for the 'tashe, which went a few years back.)</span>. <i>Exactly</i> the same. Either he's aged very well or he looked a lot older than his years when he was an F1 driver.</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;">Anyway, Agile the Docs. Really enjoyed it and looking forward to attending the next one. If you've got questions or thoughts on the presentation use the comments below or tweet me @agiledoc.</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-45698412292692044472016-10-30T08:29:00.000+00:002016-10-30T08:30:18.839+00:00Some Notes on Moving Content to Confluence<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><a href="https://www.atlassian.com/software/confluence">Confluence</a> is a super-charged wiki from Atlassian, the same company that makes the popular issue tracker, <a href="https://www.atlassian.com/software/jira">JIRA</a>. As you'd expect with a normal wiki, its most popular function is as a knowledge base, documentation hub and FAQ location, but due to it's tight links to JIRA (and other Atlassian products) it's also used for showing sprint reports, burn downs, burn ups, work in progress, and lots of other reports using data taken straight from JIRA.<br /><br />In this post we're going to focus on the traditional wiki usage: documentation and knowledge management, and specifically some do's and don'ts when moving existing documentation and knowledge assets into Confluence. Some of the points below are specific to Confluence, some are best practise whenever you're moving knowledge from one place to another, but they're all born of experience and hopefully they'll help you avoid some of the pitfalls.<br /><br />The most important points first:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">If you're a technical person, get a content person in before you move anything. They'll spot issues you won't. </span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">If you're a content person, get a technical person in before you move anything. They'll spot issues you won't.</span></span><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></span><br /><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">I'm more of a content person, and having some technical people (i.e. developers) around helps immensely. A developer's first thought is <i>always</i> "How can I do this through code?", which means they're much better at spotting situations where a batch file or a regex or some CSS will make everything a lot quicker and less manual. When I was looking at moving documentation from some internal wikis, it was developers who helped me find the appropriate export functionality and worked out whether I could take that format and import it into Confluence, potentially saving me weeks of work.<br /><br />Which brings me neatly on to: </span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Automate as much as you can. </span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">This means using export tools in your current location (e.g. wikis, CMS, document repositories, etc), and also Confluence's excellent built-in Word import functionality. There is a <a href="https://migrations.atlassian.net/wiki">Universal Wiki Converter</a> which is not supported by Atlassian because it's a 3rd party tool, but the fact that the link for it takes you to a place on the Atlassian domain should tell you they think it's useful. It doesn't work on every wiki, but if it does work for your wiki it will save you a lot of time. If instead of, or as well as, wikis you've got lots of Word documents to import, the <a href="https://confluence.atlassian.com/doc/import-a-word-document-into-confluence-170493136.html">Confluence Word importer</a> is brilliant. It's really good at importing formatting and layout, as well as features like tables, images, links, headers, footers and diagrams, and it's really quick to boot. Oh, and it will create new pages every time there's a heading in your document, if you want it to, even down to being able to set the level at which new pages are created (e.g. it will create new pages every time it finds a Level 1 or Level 2 heading, but ignore any other heading levels). The Word importer has saved me huge amounts of time. <br /><br />Before you start importing things:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Plan your space structure before you move things in. </span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">It's pretty annoying having a structure set up and working only to find it doesn't scale to accommodate what you're transferring and you have to move things around again. This is where a content person is really helpful if you're a technical person. Content people are good at the structure and layout of large bodies of information, and we'll help you analyse the user needs and get it right. Confluence's space and page structure is deceptively simple because this simplicity means it's very easy to create monolithic spaces with one massive list of alphabetically ordered pages. But people don't connect information alphabetically, so creating a space directory, page trees and label taxonomy using the guiding principles of good information architecture will make it much easier for people to navigate.</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">If multiple people are bringing stuff in, agree on common naming conventions, page structure, and labels.</span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">There's no getting away from the fact that if a team of technical communicators will all have <b>slightly</b> different ideas about conventions and structures, then a motley crew of various resources will all have <b>very</b> different ideas about conventions and structures. Even if all the people importing are technical communicators, and especially if they're not, set agreed standards for page naming conventions, page structure and labels BEFORE anyone imports anything. Otherwise it'll require a massive remedial exercise later on to standardise everything, or if this isn't done, your Confluence instance will be a mess.</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">On the subject of labels, use them to say where a Confluence page came from, e.g. wiki name, shared drive, SharePoint, or wherever.</span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">If you've never gone through this kind of process before this might seem superfluous, but believe me, it's not. No matter how careful you are when you're importing, you or someone else will want to check the original source because "it doesn't look right" or "I'm sure we used to have more information on this in the old system".<br /><br />And while we're talking about it:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Keep your old repositories for at least 6 months, just in case. </span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Transfer them to a portable hard drive that an admin locks in a secure cupboard if necessary, but don't "move and delete" because you'll regret it (even if no-one needs the back up you'll always be fretting that someone will need the back up). If after 6 months (or whatever time frame you're comfortable with) you haven't needed the back up, get rid of it. But in the meantime, keep them so that you can answer queries about "it doesn't look right" or "I'm sure we used to have more information on this in the old system" (see above) and so that you can do "idiot checks" to make sure you've got everything. Pro tip: Every time you import something, move the original to a new location that mirrors the structure of the original location. That way you can be sure everything's been imported. If you can't realistically move it, mark it with (something like) an underscore at the beginning of the title. This is also helpful when multiple people are importing things as it stops people importing the same thing twice.<br /><br />Despite the fact that you're keeping your old repositories for a while:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Bring as much metadata over as possible, especially who last edited [whatever you're importing] and when.</span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">When you create a page in Confluence, your name is sat under the title as the creator. This isn't useful for people who want to ask questions of whoever created the original content. Pull the metadata from wikis or documents (manually if necessary) and add it to the page, preferably in a default location such as just under the title. <br /><br />Having said that:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Consider adding smaller documents as attachments rather than extracting the contents. </span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">This will greatly reduce your import time and allow you to turn off your old system much quicker. You can then turn the attachments into actually pages over time if you want to. I wouldn't advocate using Confluence as a document library because really it's very poor at that. But in terms of speed, you can drag and drop multiple documents at once into the Attachments page (or the Attachments macro) and if you're pushed for time to remove things from the old system this will work as a temporary measure.<br /><br />Finally, a couple of "human" issues:</span></span><br />
<ul>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">Manually porting things over can be boring and a lot of people won't do it right because of this. Only get people who really enjoy doing this kind of repetitive, finicky work, otherwise you'll spend huge amounts of time correcting the work of people who got bored 10 minutes after they started.</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">As soon as you can turn off the old systems, do it. Or at least restrict access to them. People are creatures of habit and lots of them will keep using the old systems until it's literally not possible,</span></span></li>
<li><span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;">It's going to take longer than you thought. Take a deep breath, settle in for the long haul and don't get downhearted. You can and will do this, and it can and will be a success.</span></span></li>
</ul>
<span style="font-size: small;"><span style="font-family: "arial" , "helvetica" , sans-serif;"><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-49414233693073708132016-10-23T10:24:00.000+01:002016-10-23T10:26:34.994+01:00The 5 Reasons Developers Don't Like Writing Documentation<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A popular gripe amongst technical writers is that a lot of developers don't like writing documentation. In fact, a small cottage industry of tool makers has sprung up specifically to help companies get developers to provide some form of documentation by making the process as easy and coding-like as possible. If you've used tools like <a href="http://swagger.io/">OpenAPI</a> (formally Swagger), <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html">JavaDocs</a> or <a href="https://jekyllrb.com/">Jekyll</a> then you'll be familiar with this kind of tool. The aim of this cottage industry is to make writing documentation as much like writing code as possible, which means allowing users to focus as much as possible on the syntax and not the semantics.<br /><br />These tools are all very useful, but whilst they may be efficient ways of creating certain types of documentation, they treat the symptom and not the cause. A lot of (most?) developers don't like writing documentation. Why not?<br /><br />Having worked with my fair share of developers over the years, I've seen and heard many answers to that question, but they all reduce down to one of the 5 following reasons:</span></span><br />
<ol>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">It's boring</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">It's difficult</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">It's messy</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">It's dangerous</span></span></li>
<li><span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">It's unmanly</span></span><span style="font-family: "arial" , "helvetica" , sans-serif;"></span><br /><span style="font-family: "arial" , "helvetica" , sans-serif;"></span></li>
</ol>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Let's unpack these a bit. I'm going to refer to "developers" below, and by that I mean "the developers who would say that this is one of the reasons they don't like writing documentation".</span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">1. It's boring</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Of all the reasons, this is the most obvious and overarching. <i>Developers find writing documentation to be a boring task.</i> Perhaps a more accurate word would be <i>uninteresting</i>, because writing documentation is not an interesting task. If you don't find explaining and teaching interesting, if you have no interest in understanding the mental perspective of a target audience, if you think formatting and writing styles are dull or unimportant, then writing documentation is not going to grab your attention.</span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">2. It's difficult</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">This is equally as obvious, but a lot less admitted because people don't like to admit they can't do something. This is especially true for that sub-set of developers who think that documentation is unmanly (see below) or who generally pity and/or mock non-developers as being somehow less intelligent than developers. If you've worked in software for any length of time you'll know exactly the type of developer I mean. The fact remains that many developers simply lack the writing skills to write documentation well, or if they have the basic skills they don't have the confidence to use them for fear of looking stupid. In fairness that's not an attitude specific to developers; lots of people don't try to do things because they're scared of looking stupid, but if you've ever mocked someone, even gently, for being "just" a technical writer, you're probably not looking forward to a chance to demonstrate that you can't even remotely do their job. Better to sneer than look dumb.</span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">3. It's messy</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">A big part of the reason that documentation is difficult is that natural language is organic and messy and often follows illogical rules. Developers have spent their careers, and often many years before, learning how to use languages that are clean, designed and above all logical. Developers only have to worry about syntax, but semantics? No. No, no no. Semantics can often seem to preclude right and wrong, so for a developer who's used to the binary test of "compile/doesn't compile" or "passes unit test/doesn't pass unit test", writing in natural language <i>for others to critique</i> without having any real sense of what's correct and what's incorrect is a deeply terrifying thought. The fact that only the very best and brightest end up working on natural language processing at the companies that are any good at it just solidifies the notion that writing in natural language is a one-way ticket to looking stupid unless you're brilliant at it.</span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">4. It's dangerous</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Not in the sense of physical danger (especially since everything's electronic now and you no longer have to worry about paper cuts or dropping a heavy manual on your foot - shout out to my old-school veterans!), but more in the sense that once you've written documentation people will a) associate you with that documentation and possibly product, and b) people might actually want you to write <i>more</i> documentation, possibly even on <i>other</i> bits of code. Worse case scenario: People see you as someone who can write documentation so you'll have to do a lot more of it. There are plenty of developers who would genuinely consider jumping out of the window rather than be the developer that people go to for documentation. Writing documentation can lead to writing more documentation, and very soon that can lead to having a reputation for writing documentation. This is not good, so it's best to be very bad at it or very awkward to get any documentation from.</span></span><br />
<h3>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">5. It's unmanly</span></span></h3>
<h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"></span></h4>
<span style="font-family: "arial" , "helvetica" , sans-serif;"><span style="font-size: small;">Correctly or incorrectly there is an attitude amongst some developers that writing documentation is not a manly occupation. For those people that aren't developers this might seem at first sight to be a completely bizarre attitude, but whilst I think it's wrong, it's also not an attitude that comes out of nowhere. For a start, men are vastly overrepresented in development (I don't need to link to the stats on this; Google will find you a large number very quickly) and women are vastly overrepresented in technical writing (refer to <a href="http://quichemoraine.com/2009/03/gender-trends-in-science-and-medical-writing/">this article</a> as an example of the trends in writing). Whether this is cause or effect can be debated ad nauseam, but the point is that developers are much more likely to have worked with female technical writers and male developers. The second reason is that technical writing requires a person to collaborate, think about the needs of others, step into the user's shoes and above all display empathy. This sounds similar to what are known as the "caring professions" such as nursing, and as such stereotypically seen as being more appealing to women then men. It's the equivalent for some people of doctors and nurses; why be a nurse who has to change bandages, empty colostomy bags and give bed baths when you could be a doctor who gets to analyse, diagnose and fix people, maybe even save a life. And notice that a nurse "has to" whereas a doctor "gets to". There is an alpha-male competitiveness to many developers, and that doesn't fit well with putting the needs of other people first. <br /><br />Entirely anecdotally, I've found that the female developers I've worked with over the years generally have no problem writing documentation, and the ones that do only have a problem because other (male) developers sometimes see writing documentation almost as a sign of weakness. In some development teams writing the documentation can have almost as much of a gender bias as the old school "women make the tea" attitude, so female developers in that scenario would rather not write documentation as it will pander to the idea that they're not "technical" enough like a "real" developer. Conversely, if I think of the 20 most vociferously anti-documentation developers I've met, they've all been alpha-male types. Correlation is not causation, and all that, but I do find it a very interesting concurrency. <br /><br /><br />Every reason I've ever seen or heard for developers not writing documentation can be reduced to one of these 5 reasons. I don't want to tar all developers with the same brush; many developers write documentation happily, and many of those do a great job. Equally, I don't want to accuse all developers who don't like writing documentation as thinking that it's unmanly; I suspect this is a minority view that will only become rarer in the years to come. If you think I've missed a principle reason or you've got an opinion on which reason is the biggest prevent of developers writing documentation, add something to the comment below.<br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-67136557456411300992016-10-16T09:17:00.003+01:002016-10-16T09:17:51.624+01:005 Ways to Measure Technical Writers<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">In the past I've talked about how measuring documentation is one of <a href="http://www.agiledocumentation.co.uk/2015/05/4-hard-problems-in-technical-writing.html">the hard problems of documentation</a> and to assist in that I wrote a list of <a href="http://www.agiledocumentation.co.uk/2016/04/measuring-technical-documentation.html">things you can measure about technical documentation</a>, but now it's time to talk about measuring technical writers.<br /><br />Obviously there are a huge number of contexts and situations a technical writer could be working in, so I'm going to focus on what this blog is about - agile documentation - and therefore look at a writer working in a scrum team. Hopefully the general concepts and ideas will give you something to think about even if this doesn't describe the situation you're in.<br /><br />An obvious problem for testing a writer is that you can't use some of the simple development measures such as percentage of unit test or automated test coverage. Developers can be measured by whether they've got the appropriate test coverage for their code, thus ensuring that at the very least, their new code doesn't break the existing code. But the concept of testing documentation at anything other than the syntactical level is (currently) too complicated for a computer to perform, by which I mean a computer is not able to ascertain whether new documentation semantically "breaks" the old documentation. (There is quite a lot to be said about the difference in semantic load between natural and artificial language, but I'll leave that for another time.) So computer-driven test coverage isn't really going to tell you much, other than that the writer has written something. We're not really interested in that, because it's a trivial measure that is only a small degree away from the reviled "how many words has the writer written" measuring mentality. (If you don't know why being measured by number of words is a bad thing, Tom Johnson has an <a href="http://idratherbewriting.com/2012/03/02/technical-communication-metrics-what-should-you-track/">excellent post on the subject</a>, in which he explains why it leads to bad outcomes.) <br /><br />This brings us to an important secondary question: If we're not interested in measuring absolute output, what <i>are</i> we interested in measuring?<br /><br />Generally, we're interested in measuring <b>productivity</b> and <b>quality</b>.<br /><br />There's an interesting <a href="http://www.writingassist.com/newsroom/measuring-technical-writer-productivity/">article on measuring productivity</a> where the authors talk about using an algorithm to calculate a normalized productivity score for each writer. I really like this approach and there's a lot of useful ideas there that are worth investigating. However, it's an approach that works best when writers are working on the same kind of things in the same kind of situations (although to an extent you can weight scores to balance this out a bit) and the algorithm is - naturally - specific to their situation. So let's look at some generic ways you can measure writers that are more useful than "how many words they've written". Not all of these will be right for your situation, but at least they should give you some ideas.<br /></span></span><br />
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">1. Lead time </span></span></h3>
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">A classic operations measurement, lead time is the time it takes a set of inputs to move through a process. This can be weighted against the complexity of the task as measured in story points, although it does require documentation tasks to be measured against each other which might be difficult if each writer is working in scrum teams with significantly different types of work. An obvious objection to this is that teams should not be compared by story points; you can't say that a team that does 40 points of work in a sprint is less productive than a team that does 80 points, because <a href="http://www.agiledocumentation.co.uk/2015/06/story-points-estimation-confusion.html">estimation is a matter of comparison</a> to other items in the sprint, not an absolute measure. Nonetheless, if your writers are generally working on the same things - e.g. topics for a help file that covers work from all teams - you should be able to weight appropriately based on historical averages. This will also help you spot information pipeline problems if a writer regularly has to take additional time to get information that other writers get as standard from their teams.<br /></span></span><br />
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">2. Peer review scores</span></span></h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">People make mistakes and documentation has a high semantic load, so this isn't a "100% or fail" measurement. But if a writer regularly fails peer review for things which you would expect them to get right, such as proscribed terminology or incorrect formatting styles, this is a sign that there is a legitimate problem. More concerning than these kind of errors (because the writer just needs to learn the rules and follow them) will be errors of comprehension or explanation. If the peer reviews reveal that a writer regularly writes unclearly or doesn't appear to understand the topic, you've got a problem that needs to be resolved.<br /></span></span><br />
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">3. Support tickets</span></span></h3>
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Related to peer review scores, the number of support tickets that could have been dealt with in the documentation indicates how much the writer understands the user story that they're documenting. There are a myriad reasons that you could have increased support tickets around an area a writer was working on, so be very careful here. Perhaps the subject matter is extremely difficult, perhaps 1 or 2 customers haven't read the documentation and are flooding support with tickets that they shouldn't, perhaps the user story didn't capture the user pain correctly, and so on. However, if the support tickets simply indicate incorrect, incomplete or poorly written documentation then there is a de facto problem to be addressed.<br /></span></span><br />
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">4. Technical debt</span></span></h3>
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Take a measure of the existing technical debt, to cover known missing, incomplete or out of date documentation that the writer is responsible for. Measure this on a regular schedule that is short enough to catch a problem but long enough to allow for short term fluctuations such as holidays or sickness, such as once a quarter or every release. You're looking for a trend that <i>at a minimum</i> doesn't go up. This means that the writer is not making the technical debt worse. Whenever a writer is working in a topic with known technical debt they should be able to improve it (as a general rule of thumb, not a cast-iron certainty) and the trend should go down over time. If the trend stays level, the writer is either very busy or adding as much debt as they're paying; if the trend is upwards then the writer is adding debt and you've got a serious issue to deal with before it gets any worse.<br /></span></span><br />
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">5. Commitment vs complete </span></span></h3>
<h3>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></h3>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Does the writer complete the documentation they've committed to at the beginning of the sprint? There's an assumption here that your company's culture is such that the writer feels comfortable refusing to commit to a sprint if there's too much documentation, or not enough information about the documentation requirements, to commit, although most writers I know work in a <a href="http://www.agiledocumentation.co.uk/2015/03/99-dirty-agile.html">dirty agile</a> scenario, so maybe this is unrealistic. However, if you can use this measurement, it will tell you about the writer's ability to estimate and their willingness to push through to get things done. Of course, it might also tell you that the whole team struggles to complete, which is a different issue. But it's important for a writer to be a "completer", so make sure you know whether your writer is getting things finished.<br /><br /><br />All 5 of these measures could be expanded on, but every situation is different and these are intended to be generic measurement points for agile writers. All of them allow you to measure trends over time, which is essential for performance management. But they're not the only things you can measure, so what other measurements do you find useful? Share them in the comments.<br /><br /><br /><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-46649141397010099022016-10-02T09:11:00.000+01:002016-10-02T09:11:25.176+01:00TCUK16 Awards<span style="font-family: Arial,Helvetica,sans-serif;">The <a href="http://www.istc.org.uk/">ISTC</a> held their annual <a href="http://technicalcommunicationuk.com/">Technical Communication UK Conference</a> at the <a href="http://www.wybostonlakes.co.uk/">Wyboston Lakes Executive Centre</a>, Cambridgeshire, from September 13 - 15 this year. I attended the gala dinner on the evening of the 14th, and whilst I was there the UK Technical Communication Awards winners for 2016 were announced.</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;">I'm honoured and (genuinely) humbled to say that the ISTC have seen fit to award me the 2016 Best Procedural Communication award for the <a href="http://www.agiledocumentation.co.uk/2016/05/how-to-scale-documentation.html">How to Scale Documentation</a> series that I recently wrote on this very blog:</span><br />
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
</div>
<div class="separator" style="clear: both; text-align: center;">
<br /></div>
<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjDwGVXihbGJR7otMKycpL9AEe4lzeg_DvPJChuj3c78YmrrQWSmGeJ4KJ3GRwvAdaCXqLEc0dDoSDo6PKIbnTRlqf_U0q6vGOr4kpKuO_Ymoo-_mbs-9w_XxOpwYMQyaOr8p1Pp6uGKec/s1600/Award+Photo.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" height="328" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjDwGVXihbGJR7otMKycpL9AEe4lzeg_DvPJChuj3c78YmrrQWSmGeJ4KJ3GRwvAdaCXqLEc0dDoSDo6PKIbnTRlqf_U0q6vGOr4kpKuO_Ymoo-_mbs-9w_XxOpwYMQyaOr8p1Pp6uGKec/s400/Award+Photo.jpg" width="400" /></a></div>
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;">The judges remarks were:</span><br />
<br />
<div style="text-align: center;">
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-family: Georgia,"Times New Roman",serif;">"Really well organised with appropriate and consistent details. The structure aids readability. Great typography choices, used to enhance the content, and to visually chunk information. Great use of space and colour in titles. The entry’s distinct conversational style works extremely well with the chosen subject and audience.<br /><br />This entry is so effective because it makes everything seem so manageable. The user is guided through the series of articles and can be confident of finding explanations and at the right level." </span></span></div>
<br />
<span style="font-family: Arial,Helvetica,sans-serif;">To say that I was surprised when the ISTC told me I'd won would be a huge understatement. Up until that point my entire trophy collection consisted of a bronze medal in a judo competition when I was 16 and a plastic cup as a member of a league and cup double winning <a href="http://www.bicyclecards.com/how-to-play/cribbage/">cribbage</a> team when I was 18. I didn't need a trophy cabinet so much as a trophy shoebox. Now I've got a very handsome (and heavy) glass trophy that's got pride of place on the bookshelf in my office. To say I'm happy doesn't begin to describe it.</span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;">Congratulations to all of the winners, especially <a href="https://twitter.com/anghelides">Peter Anghelides</a> as the winner of the <a href="http://www.istc.org.uk/professional-development-and-recognition/istc-awards/horace-hockley-award/">Horace Hockley Award</a> for Outstanding Contribution to the Profession. You'll be able to see a list of all the winners and read the winning entries in December's issue of <a href="https://www.istc.org.uk/publications-and-resources/communicator/">Communicator</a>. Also, my personal thanks go, in no particular order, to:</span><br />
<ul>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="https://uk.linkedin.com/in/elaine-cole-a5163212">Elaine Cole</a>, for guiding me through the evening with courtesy and commendable patience, as well as for putting me at ease before I had to go on stage in front of a room full of more or less sober peers to collect my award;</span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="https://uk.linkedin.com/in/clearlystated">Alison Peck</a>, for making a conference debutant feel so welcome by chatting to me all through dinner, despite everyone in the room wanting to talk to her;</span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><a href="https://uk.linkedin.com/in/galynakey">Galyna Key</a>, who couldn't attend the conference this year, but does such a wonderful job organising, promoting and running the UKTC awards.</span></li>
</ul>
<span style="font-family: Arial,Helvetica,sans-serif;">And to everyone else I met at the Conference this year, thank you for making me feel so welcome. It was a pleasure to meet so many dedicated, passionate and skilled technical communicators. I hope to see you all next year!</span><span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>
<span style="font-family: Arial,Helvetica,sans-serif;"><br /></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-69850830945323472212016-08-30T11:47:00.003+01:002016-08-30T11:47:42.728+01:00Are Technical Writers Becoming Obsolete?<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">When I started working in the software industry just after the turn of the century, there were Technical Writers, Document Authors and occasionally - just to spice things up a bit - Technical Authors. All 3 of these roles did the same thing: write end user documentation that would either be printed or displayed on screen in a help format like CHM. This documentation was aimed either at people who installed, configured and administered the software, or at users who had to navigate the UI on a daily basis to do their job.<br /><br />Nowadays, every part of that has changed. We have Information Architects, Knowledge Engineers, Content Strategists, UX Writers and "<a href="http://idm.net.au/blog/00241document-wrangler">Document Wranglers</a>" (no, me neither). All of these roles seem to do different things, and none of them seem to have writing good old-fashioned help documentation as their primary role. End user documentation seems to have become very passée, with little love left for a large body of writing that explains how something works. The notion of putting documentation into a .chm is scoffed at; the notion of providing a <i>printed</i> copy is as old-fashioned as the idea of burning your DevOps maven because she might be a witch.<br /><br />Some of these changes are driven by technology. With many applications being solely or largely online, it makes no sense to provide a .chm when a .chm is essentially just HTML, CSS and JavaScript. There's a better, faster, more open delivery mechanism for that, and it's called a web page. On that note, as dial-up has gone the way of the phone box, there's no need to send customers the help file on a CD or on actual paper through the post. People can download a 500 page 10mb document in a couple of seconds, although the irony is that as the documentation is delivered online using topic-based authoring, they can pick and choose what they want to see so they'd never need the whole documentation stack anyway. <br /><br />Likewise, the explosion of mobile apps and the sudden realisation that yes, good UX design IS ACTUALLY IMPORTANT (a fact that many, many companies seem to have been oblivious to pre-smart phone) has meant that a lot of small companies are letting their design do the communication for them, and the absolute minimal documentation required is in the form of prompts, labels and warnings. These are done, if anyone does them formally, by the UX designer or a dev who's more interested or more junior than the other devs. The mobile apps created by big companies have also forced them to realise the importance and value of good UX design, but unfortunately the completely expected has then happened: "Ooh, we didn't need a technical writer for our new mobile app because of the great design. Let's apply that principle to our enterprise application and we can save on writers!" (This is despite the fact that their 20-million-lines-of-code enterprise application is lugging around years of technical debt and is so poorly designed that the idea of making it lightweight enough to go online is a running joke amongst the devs. But sure, get rid of your writers, that's the problem you need to solve.)<br /><br />And some of these changes have come about because it's now easier to automate some of the writer's job. If you set up <a href="http://swagger.io/">Swagger</a> with the right templates and show a little care, your API documentation, or at least the core of it, can be provided at the press of a button. Provide your <a href="https://www.atlassian.com/software/confluence">Confluence</a> users with well-thought out templates with mandatory fields and macros linked to <a href="https://www.atlassian.com/software/jira">JIRA</a>, and your release documentation can be written by anyone in your team. I would never say that these thing are enough (and I'll believe that to my dying day) but the cost-benefit ratio of hiring a dedicated writer changes with each new automation technology that chips away at the periphery of what the writer does.<br /><br />However, some of these changes to the writer function are driven by methodology. In an agile world - and if you're not agile you're very out-of-step with modernity, no matter what you think about it - the specialist is a dying and unwanted breed. No-one can be "just" a writer any more, because what we do often doesn't exist in any meaningful way now. Sure, there are plenty of massive enterprise level applications out there that need equally massive help files, but these are becoming the exception rather than the rule. This is not helped by disruption on a grand scale from start-ups that value doing one thing really well, and a clientele of millennials who are starting to reach an age where they an have an input into buying decisions, and who are not bothered in the slightest by the idea of buying 10 different apps and using <a href="https://ifttt.com/">IFTTT</a> to fit them together, rather than spending 20x as much on a behemoth from a 50 years old blue chip. <br /><br />With everyone moving to agile, the expectation is that the specialist writer can no longer be siloed into "just" writing documentation. Hence a role like Knowledge Engineer, where you conduct the fragmentary topics to the right place to form a coherent orchestra for your audience, or Content Strategist, where you act as a lode stone to keep all of the disparate documents from different experts pointing in the same direction. In many cases it is no longer enough to be able to write; you must be able to plan, build, guide, persuade, manage. Writing in and of itself is almost secondary.<br /><br />If you look at the coalescing of the following trends:</span></span><br />
<ul>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Mobile apps;</span></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Better UX investment;</span></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">More documentation automation tools;</span></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Fragmented market of smaller providers;</span></span></li>
<li><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Move to "specialised generalists" in agile.</span></span><span style="font-family: Arial,Helvetica,sans-serif;"></span><br /><span style="font-family: Arial,Helvetica,sans-serif;"></span></li>
</ul>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Then you'll see that none of them are positive for the working prospects of a "pure" technical writer. It may seem that the pure skill of a technical writer - writing - is less valued than it was before, but the companies that valued this before will still value it now. It's the changing of the technologies and methodologies that are allowing companies that never really valued documentation to do away with technical writers, and new companies that join the fray don't see the cost-benefit ratio of having a technical writer in the first place. They hire a Content Strategist to provide a guiding strategy and write some templates, add documentation (using Swagger and other tools) to the Definition of Done, and have a Knowledge Manager to look after the internal wiki and provide light editing of the docs. </span></span><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">They release updates several times a week so there's plenty of scope to iteratively improve the docs as they go.</span></span> And that's it. Where does the technical writer fit into that? Answer: They don't. </span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"></span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br />So where do you go if you're a technical writer? Do you transition to analysis, QA, testing, product management, training, support, or move to a different industry altogether? Do you keep chasing the ever-decreasing number of "pure" technical writing jobs? Do you specialise in API and/or SDK documentation on the basis that it's one of the few areas where there aren't enough qualified writers to fill the all the vacancies? All of these are valid and sensible options. In the long run though, you're best off learning how to do all of the things that have been chipped away. Learn how to use Swagger and other documentation automation tools. Learn how text is displayed in your application and become its writer, editor and proofreader. Learn at least the basics of UX design and join the discussions about how best to show - rather than tell - the user what to do next (because no-one is better than you at understanding that). Become a moderator for forums that discuss your company and its products. Learn how to manage the knowledge assets your company has. Learn what a content strategy is and create one. </span></span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">Because being a Technical Writer is no longer enough in a lot of companies. Eventually it won't be enough in any company. <br /><br /><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-77973875062537008112016-08-21T12:38:00.000+01:002016-08-21T12:39:27.116+01:00To Be a Good Agilist, You Need To Be a Modern Renaissance Man<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">During <a href="https://simple.wikipedia.org/wiki/Renaissance">the Renaissance</a> in Western Europe, a certain type of man came to the fore as the exemplar of what a person should be. Whereas in the Middle Ages preceding the Renaissance a man might be a craftsman, an artist, a priest or a soldier, the Renaissance saw the birth of men who could be all these things, and more. It was not enough to be an orator, a soldier, a poet, a scholar. A man - and it was always men - had to speak several languages fluently, be a fine horseman, write epic poetry, lead soldiers, demonstrate athletic prowess and, of course, be able to woo a lady. Nowadays the requirements might be different (and women are no longer excluded from the education needed to be a polymath), but the intent remains the same:</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<div style="text-align: center;">
<div style="text-align: center;">
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><span style="font-family: Georgia,"Times New Roman",serif;">"A human being should be able to change a diaper, plan an invasion, butcher a hog, conn a ship, design a building, write a sonnet, balance accounts, build a wall, set a bone, comfort the dying, take orders, give orders, cooperate, act alone, solve equations, analyze a new problem, pitch manure, program a computer, cook a tasty meal, fight efficiently, and die gallantly. Specialization is for insects."</span> (Robert Heinlein)</span></span></div>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></div>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br />Or to put it more bluntly:</span></span><br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br /></span></span>
<div style="text-align: center;">
<div style="text-align: center;">
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><span style="font-family: Georgia,"Times New Roman",serif;">"Single-mindedness is all very well in cows or baboons; in an animal claiming to belong to the same species as Shakespeare it is simply disgraceful."</span> (Aldous Huxley)</span></span></div>
<span style="font-family: Arial,Helvetica,sans-serif;"></span></div>
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;"><br />What was it about the Renaissance that created men such as da Vinci, Michelangelo and Galileo? The printing press created a relative explosion in the availability of the printed word, and with it the lifeblood of learning: knowledge. The influx of Islamic learning (which also reintroduced a lot of Ancient Greek and Roman scholarship that had been preserved by Arabic scholars whilst the Europeans were busily destroying anything "heretical" during the Dark Ages) gave new ideas and avenues of exploration. The Church, which over the preceding centuries had become dogmatic and corrupt, was (slowly) losing its authority both spiritual and temporal; in the middle of the Renaissance <a href="https://simple.wikipedia.org/wiki/Martin_Luther">Martin Luther</a> wrote his <a href="http://www.christianitytoday.com/history/issues/issue-28/1517-luther-posts-95-theses.html">95 theses</a> about the corruption of Church indulgences and began a process that would <a href="http://www.history.com/topics/reformation">cleave the Roman Catholic Church in two</a>. These events came together to provide an environment where not only was it becoming easier to find knowledge to learn from, but the overwhelming authority of the day was losing it's ability and authority to prevent people challenging the prevailing dogma. People could start to challenge the orthodoxy of how the world worked rather than having to be content with a religious explanation that had undertones of disapproval for your temerity in even asking the question.<br /><br />It's said that da Vinci was the last man to know everything that could be known (although <a href="http://www.eoht.info/page/Last+person+to+know+everything">many others</a> have jostled for this title), partly as a sign of his brilliance, but also as a sign of how much more there is to know nowadays. And that body of knowledge is expanding exponentially; whilst for da Vinci there was philosophy (the "natural sciences"), mathematics and art to master, for the modern human it would take a lifetime to become merely conversant with every branch of engineering, let alone a master of them. And then there is mathematics, physics, chemistry, biology, astronomy, psychology and so on and so on, and knowledge and understanding in all of these fields is increasing every day. <br /><br />But the spirit of intense curiosity that drove the Renaissance men is no more abated today than it was then. And like the Renaissance men we are living in a time when knowledge and learning is undergoing an explosion of democratisation and availability, except this time it's the electronically printed word delivered through the internet rather than ink on a pig skin or dried wood pulp. We may no longer have the capacity to know the full corpus of human knowledge, but we can choose to learn anything that we wish, largely for free, from the comfort of our homes.<br /><br />I've made the point before that <a href="http://www.agiledocumentation.co.uk/2015/02/the-unicorn-at-heart-of-scrum.html">the unicorn at the heart of scrum</a> is the multi-functional team: very desirable but largely mythical. It's <a href="http://www.agiledocumentation.co.uk/2015/02/why-arent-there-more-cross-functional.html">largely mythical</a> for the simple reason that it's too difficult for a person to become a master of analysis and development and testing and documentation. It's not difficult because each of the individual elements is too difficult, but because they are all different skills with different pre-requisites and ever-increasing bodies of knowledge that you need to stay on top of to maintain your mastery. There simply aren't enough hours in the day, assuming you have some form of personal life (and would like, in no particular order, food, recreation, relationships and sleep). I stand by this, whilst accepting that there are a few people who can master 2 of these concurrently, and very, very occasionally 3 or more. For us mere mortals though, it's unrealistic to expect to be a 10x or full-stack developer whilst also having an encyclopedic knowledge of <a href="http://www.iiba.org/babok-guide.aspx">BABOK</a>. <br /><br />Nonetheless, that insatiable curiosity and thirst for learning that drove the Renaissance men to heights of mastery can and should be an inspiration to show that it is possible to have great knowledge in diverse areas. There is much overlap between the functions of each profession that makes up a scrum team; if da Vinci can be both <a href="https://www.royalcollection.org.uk/collection/themes/exhibitions/leonardo-da-vinci-the-mechanics-of-mann/the-queens-gallery-palace-of">a master anatomist</a> and <a href="http://www.da-vinci-inventions.com/aerial-screw.aspx">the inventor of the helicopter</a>, is it beyond the bounds of reason that a single person could be both a master of documentation AND a competent tester, or a mistress of development AND a competent analyst, or any other combination of professions in your team? At the very least a database developer should also know the basics of web development; a technical writer should be able to write both API documentation and a Beginner's Guide and so on.<br /><br />The march of the specialist has <a href="http://www.agiledocumentation.co.uk/2015/02/scrum-works-better-in-startups.html">benefits for efficiency and productivity</a>, but only the generalists can create things in a non-linear (non-conveyor belt) fashion, only generalists can see the bigger picture, anticipate how their work will affect others in their team and <a href="http://www.agiledocumentation.co.uk/2015/04/why-are-multi-functional-teams-desirable.html">create and innovate within that team</a>. Without expecting people to master multiple professions, there is still scope for learning things that other professions do every day, even if mastery is beyond you. </span></span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">As with the Renaissance men it is no longer acceptable to say "I don't do that, I'm a developer/tester/analyst/technical writer." You can, should and must be more.<br /><br /><br /><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0tag:blogger.com,1999:blog-6420442642189584921.post-40878063777647288922016-08-02T09:53:00.002+01:002016-08-02T09:53:41.281+01:00You Need an Agile Attitude, Not Just Agile Behaviours<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">In one sense it's easy to move to an agile way of doing things. You send your people on some training, start using sprints, change your Product Managers to Product Owners, maybe hire a consultant to spend some time advising your staff, and you're agile, right?<br /><br />Wrong.<br /><br />There are 2 big issues with that description:<br /><br />1. You can't force long-term behavioural change;<br />2. There is no "agile way of doing things".<br /><br />And yet that description of how companies change to agile is accurate in a large number of organisations. Sure, the details may be slightly different and there are differing levels of commitment and intent, but in general the notion of changing procedures to "do things in an agile way" is a very common way of moving from [whatever went before] to "agile". The key error in this situation is that what needs to be changed is not behaviours as such, but attitudes.<br /><br />It's true that behaviours do need to change when you move to an agile methodology, because, for example in the case of Scrum, you've got new roles of Product Owner and Scrum Master, new ceremonies for planning, review, retrospective, grooming and daily scrums, and new artefacts to interact with like a backlog and user stories. The daily and weekly routines that people are used to will change, as will the release cadence, and different behaviours are needed to deal with these. But these behaviours cannot be forced onto people as an act of managerial diktat.<br /><br />Everyone involved in an agile transformation must understand that the paradigm you used to work in is not the paradigm you'll be working in from now on. The biggest intellectual challenge when moving to a new paradigm is not a new way of doing things, it's a new way of thinking. Moving to an agile methodology is exactly the kind of paradigm shift that requires a new way of thinking, and make no mistake: it's hard. <br /><br />The classic example of a paradigm shift is the the switch from the Ptolemaic (Earth-centric) model of the planets to the heliocentric (Sun-central) model, also known as the <a href="https://en.wikipedia.org/wiki/Copernican_Revolution">Copernican Revolution</a>. Without wishing to stretch a point too much (because the move from [whatever you were doing before] to an agile methodology is not on the same level as a true paradigm shift like the Copernican Revolution) one of the key problems with a paradigm shift is that you can't compare things between 2 paradigms because they are incommensurable, that is "not-comparable". Now, there is significant debate on how much this <a href="https://www.jstor.org/stable/3129898?seq=1#page_scan_tab_contents">incommensurability is true</a>, but in at least some senses you can't compare the claims of one paradigm with those of another because assumptions and boundaries are used to make judgements within a paradigm, and the assumptions and boundaries of 2 paradigms can be radically different.<br /><br />Therefore it's not the case that you can simply map agile things on to what you did before. The new roles are not "more management". The new ceremonies are not "more meetings". The new artefacts are not "more bureaucracy". They are not these things because in an agile methodology the roles, ceremonies and artefacts are there for the very purpose of removing unnecessary management, meetings and bureaucracy. You use these roles, ceremonies and artefacts to keep management, meetings and bureaucracy to the bare minimum needed to make the vital decisions - prioritisation, estimation, commitment - and convey the vital information between the team members, and between the team and the business.<br /><br />Telling people to engage in these behaviours - to "do things in an agile way" - will only lead to a begrudging change of process, not a change to an agile paradigm. To achieve that paradigm shift you need to change people's attitudes, because behaviours only become routine and accepted if they flow naturally from an attitude. Think of agile not as a series of actions, but as a <a href="https://en.wikipedia.org/wiki/Field_(physics)">field</a> in which those actions take place. Place an object of mass in a gravitational field, and it will act in accordance with the laws that govern that field. This is an analogy that can't be stretched too far for all sorts of reasons, but the general point holds: People act in accordance with the (cultural) field in which they find themselves, which has the practical effect of instilling an attitude in them. They will continue to act in that way until they are placed in another (cultural) field that forces them to modify their attitude. <br /><br />There is a plethora of information available about how people's behaviours are influenced by the cultural and social attitudes in which they find themselves, so we won't cover any of that here. But trust me when I say that a person's behaviour is determined far more by the behaviour of the people around them, especially people in a position of influence or power, than a lot of those people would like to admit. This means that the most effective way for an organisation to successfully transition to an agile methodology is for leaders and influential people to display the attitudes that will cause others to follow them. It is a top-down process, but through example, not through mandate. If you consider the nature of virtue, it's easy to perform virtuous acts but difficult to be virtuous. Anyone can perform a virtuous act, such as giving to charity, but that is not the same thing as being virtuous. It is the same with agile. Anyone can perform an agile action, such as holding a sprint retrospective, but that is not the same thing as being agile. </span></span><br />
<br />
<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-size: small;">It's not about an "agile way of doing things", it's about an agile way of seeing what's in front of you and acting accordingly. <br /><br /><br /><br /><br /><br /></span></span>Rob Woodgatehttp://www.blogger.com/profile/10946127393621249071noreply@blogger.com0