tag:blogger.com,1999:blog-246235042024-03-14T23:14:11.811+11:00Cameron ShorterThoughts on docs, open source, & geospatial, sometimes with an Australian accent.Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.comBlogger259125tag:blogger.com,1999:blog-24623504.post-59944332078585305432023-09-25T17:26:00.001+10:002023-09-25T17:26:38.481+10:00Electrifying friends<p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh3WRZuRCPmoUD6575XeTMgy16TYUljgG3utxW1UTREZWLA1rbLH30W5kktkU4K5MtPBoxBCmnRP0kaVUlJtiCXFDsF9kzBeDaF88uXVEu_9w8HvJ1EPWa64OXFUUJysjjY4sKUxu8luzs4FOqntjHPJM86I9f7W68qAa4lSn1_jYSK_iXZMSKS/s911/TrustEquation.png" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" data-original-height="443" data-original-width="911" height="156" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEh3WRZuRCPmoUD6575XeTMgy16TYUljgG3utxW1UTREZWLA1rbLH30W5kktkU4K5MtPBoxBCmnRP0kaVUlJtiCXFDsF9kzBeDaF88uXVEu_9w8HvJ1EPWa64OXFUUJysjjY4sKUxu8luzs4FOqntjHPJM86I9f7W68qAa4lSn1_jYSK_iXZMSKS/s320/TrustEquation.png" width="320" /></a></div><br />It’s surprising to discover the knock-on impact each of us has when we become that trusted friend who helps people or communities with their electrification journey.<p></p><p>This <a href="https://docs.google.com/presentation/d/142k0ES8KuGF2vJjzO0f0eeQ2OuWz-Af4EJ47rGgqXLI/edit#slide=id.p">Electrifying Friends presentation</a> covers:</p><p></p><ul style="text-align: left;"><li>Why electrifying homes is a major solution to our climate challenges.</li><li>Why trusted friends are a key enabler.</li><li>Why lessons us Australians work will be rolled out to the world.</li><li>How to become a good electrification champion.</li></ul><p></p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-84358651828158291072023-06-06T07:19:00.000+10:002023-06-06T07:19:34.073+10:00Gitlab's conversation with The Good Docs Project<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/Bek7vLmNmME" width="320" youtube-src-id="Bek7vLmNmME"></iframe></div><br /><div class="separator" style="clear: both; text-align: center;"><span style="text-align: left;"><a href="https://thegooddocsproject.dev">The Good Docs Project</a> has been inducted as a </span><a href="https://about.gitlab.com/solutions/open-source/partners/" style="text-align: left;" target="_blank">GitLab open source project partner</a><span style="text-align: left;">, and Bryan Behrenshausen from GitLab interviewed us about our project.</span></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-52607514845666176262023-05-27T07:44:00.001+10:002023-05-27T07:44:00.272+10:00Time to retire Contributor License Agreements<div class="separator" style="clear: both; text-align: center;"><em><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjpKXJrV49ENszbrxgsD2XeF7pgqFp0-DU4bEU2_RLyfQWOxmu6MR7TJ0fd9YBj0QAuB87nCFlLn5ZrvmQKY8Wwta-_J7T8lveDLRmxUZSnyHAqcNSIsw8VGhO74bIM_IKZtlxA4Iir5NNrTQ9MPzkNtCHwh8zxiF8gAy_NY30zWrUXQB0z4A/s1024/OldLawyerAndScroll.jpeg" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" data-original-height="1024" data-original-width="1024" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjpKXJrV49ENszbrxgsD2XeF7pgqFp0-DU4bEU2_RLyfQWOxmu6MR7TJ0fd9YBj0QAuB87nCFlLn5ZrvmQKY8Wwta-_J7T8lveDLRmxUZSnyHAqcNSIsw8VGhO74bIM_IKZtlxA4Iir5NNrTQ9MPzkNtCHwh8zxiF8gAy_NY30zWrUXQB0z4A/s320/OldLawyerAndScroll.jpeg" width="320" /></a></em></div>
<em><br />Imposing Contributor License Agreements (CLAs) on open source contributors inadvertently imposes unnecessary legal risk on the people gifting software to humankind. It’s time to:</em>
<p></p>
<ul>
<li><em>Update the legal advice from foundations,</em>
</li><li><em>Update license terms of hosting platforms,</em>
</li><li><em>And help open source communities avoid wasting energy on CLAs.</em>
</li>
</ul>
<p>
Reading time: 6 mins
</p>
<h3 style="text-align: left;">What are CLAs?</h3>
<p>
Contributor License Agreements (CLAs) are “inbound licenses” - providing a license from a contributor into a project. This contrasts to “outbound” open source licenses such as the GPL or Apache licenses, which provide a license from a project to users. There are multiple individually crafted CLAs (which is a problem in itself), which typically consist of a combination of:
</p>
<ul>
<li><strong>Individual Contributor License Agreements (ICLA):</strong> An individual asserts that they license their contributions to the project, and they have the right to do so.
</li><li><strong>Corporate Contributor License Agreements (CCLA):</strong> A corporation asserts their employees may contribute to the project.
</li><li><strong>Copyright Assignments (CA):</strong> Contributors assign copyright to the project’s owners (typically a not-for-profit organization).
</li>
</ul>
<h3 style="text-align: left;">What are the arguments for CLAs?</h3>
<p>
Proponents for CLAs often argue that CLAs add licensing rigor and help protect a project and its end users from being sued by bad actors. For instance, the <a href="https://ubuntu.com/legal/contributors/faq">Ubuntu/Canonical FAQ</a> notes:
</p>
<p>
<em>Q: Why do you ask contributors to send in the [contributor license] agreement?</em>
</p>
<p>
<em>A: We need to make sure that we ‐ and the users of our software ‐ are legally entitled to distribute your contributed code, anywhere in the world.</em>
</p>
<p>
<a href="https://www.gnu.org/licenses/why-assign.en.html">Why the Free Software Foundation gets copyright assignments from contributors</a>:
</p>
<p>
<em>In order to make sure that all of our copyrights can meet the recordkeeping and other requirements of registration, and in order to be able to enforce the GPL most effectively, FSF requires that each author of code incorporated in FSF projects provide a copyright assignment, and, where appropriate, a disclaimer of any work-for-hire ownership claims by the programmer's employer. That way we can be sure that all the code in FSF projects is free code, whose freedom we can most effectively protect, and therefore on which other developers can completely rely.</em>
</p>
<h3 style="text-align: left;">What’s wrong with CLAs?</h3>
<p>
The problem with Contributor License Agreements (CLAs) are that they:
</p>
<ul>
<li><a href="https://www.linuxjournal.com/content/contributor-agreements-considered-harmful">Are at best legal voodoo</a>. In the current unformed state of intellectual property law, CLAs don’t provide a water-tight defense against the legal attack they are theoretically supposed to prevent.
</li><li>Are arguably unnecessary, now that “inbound=outboud license terms” have started being woven into some <a href="https://help.github.com/en/github/site-policy/github-terms-of-service#6-contributions-under-repository-license">hosting platform Terms of Service</a>.
</li><li><a href="https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/#clas-shifts-legal-blame-to-the-party-least-equipped-to-defend-against-it">Shift legal risk to contributors</a>.
<ul>
<li>CLAs shift the legal risk for copyright infringement, patent infringement or other bad acts,
<ul>
<li>From the project and end users (the entities best positioned to defend a legal claim, and often the ones most directly benefiting financially),
</li><li>To the contributor (the one in at the least advantaged negotiation position, often volunteering their time for the project’s benefit).
</li>
</ul>
</li>
</ul>
</li><li><a href="https://sfconservancy.org/blog/2014/jun/09/do-not-need-cla/">Rely on our Don't Read & Click ‘Agree’ culture</a> — tricking contributors into bearing legal risk.
</li><li>Create a <a href="https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/#clas-create-a-contribution-hostile-developer-experience">contribution-hostile environment</a>. CLAs require that the first interaction between an open source project and a potential contributor involves a formal and complex legal agreement which signs away their legal rights — not exactly a warm welcome.
</li><li>Require <a href="https://ben.balter.com/2018/01/02/why-you-probably-shouldnt-add-a-cla-to-your-open-source-project/#clas-create-a-contribution-hostile-developer-experience">significant administrative overhead</a>. The project needs to stand up a system to track every potential contributor that has signed the agreement.
</li>
</ul>
<h3 style="text-align: left;">Alternative 1: Do nothing</h3>
<p>
If your project has selected an open source license, and you are using a platform like Github, which includes an <a href="https://docs.github.com/en/site-policy/github-terms/github-terms-of-service#6-contributions-under-repository-license">“inbound=outbound” clause</a> in its terms of service, then your project is likely covered to the same extent as you get from a CLA.
</p>
<h3 style="text-align: left;">Alternative 2: Simple statement</h3>
<p>
You can add a simple statement to your project’s contributor guidelines. Erik S. Raymond <a href="https://www.linuxjournal.com/content/contributor-agreements-considered-harmful">suggests</a>:
</p>
<p>
<em>By submitting patches to this project you agree to allow them to be redistributed under the project's license, according to the normal forms and usages of the open-source community.</em>
</p>
<h3 style="text-align: left;">Alternative 3: Developer Certificate of Origin</h3>
<p>
You can reference the <a href="https://developercertificate.org/">Developer Certificate of Origin</a> (DCO) in your project’s contributor guidelines:
</p>
<p>
<em>By contributing to this project we expect you to agree to the <a href="https://developercertificate.org/">Developer Certificate of Origin</a> (DCO). </em>
</p>
<p>
The (DCO) provides a simpler alternative to CLAs. It is a simple statement that a contributor agrees to share their contribution under the project’s license terms, and has the rights to do so. It’s advantages are:
</p>
<ul>
<li>It is short, simple and easy to understand.
</li><li>It can be referenced by any project without customisation.
</li><li>It can be set up without engaging a lawyer.
</li><li>It is used by trusted open source foundations, giving it credibility within open source communities.
</li><li>It has negligible project management overhead. Tracking of agreements is managed by the code versioning system.
</li><li>It doesn’t introduce a copyright assignment, which is a barrier for some contributors.
</li>
</ul>
<p>
Possible disadvantages are:
</p>
<ul>
<li>Like CLAs, DCOs don’t provide a water-tight defense against the legal attack.
</li><li>It could be argued that a simpler statement of “inbound licenses = outbound licenses” provides the same purpose as the DCO, but does so more elegantly.
</li><li>While the DCO can be applied without explicit signatures for each commit, some projects, such as the Linux Foundation, require each commit to be electronically signed. The electronic signature adds a technical overhead which can deter some contributors.
</li><li>Some entities (such as not-for-profit organizations) might be concerned that copyright is not assigned to their entity.
</li>
</ul>
<h3 style="text-align: left;">What should projects do?</h3>
<p>
Adopt one of the three alternatives above.
</p>
<h3 style="text-align: left;">What should open source foundations do?</h3>
<p>
Open source foundations have earned a position of trust, respect and influence within software communities.
</p>
<p>
It is important for these foundations to:
</p>
<ol>
<li>Research and understand the problems associated with CLAs.
</li><li>Revisit and ideally migrate off CLAs for projects within their foundation.
</li><li>Collaborate and adopt common language around the replacement to CLAs.
</li><li>Provide prominent advice to communities against the use of CLAs.
</li>
</ol>
<h3 style="text-align: left;">What should software hosting platforms do?</h3>
<p>
Software hosting platforms should <a href="https://help.github.com/en/github/site-policy/github-terms-of-service#6-contributions-under-repository-license">follow the lead of Github</a> and legally protect the projects they host. Add “inbound=outbound” to their license terms of service.
</p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-16699745079986642522023-05-25T07:00:00.002+10:002023-05-26T22:23:03.158+10:00Open Source awards for Good Docs contributors<div class="separator"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/s512/OSS+BLOG+Peer+Bonus.png" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/w320-h165/OSS+BLOG+Peer+Bonus.png" /></a></div><br /><br />Congratulations to Google's <a href="https://opensource.googleblog.com/2023/05/google-open-source-peer-bonus-program-announces-first-group-of-winners-2023.html">Open Source Peer Bonus award</a> winners. Winners from <a href="https://thegooddocsproject.dev">The Good Docs Project</a> include:<br /><h3 style="text-align: left;">Ophy Ampoh</h3><div>Ophy Ampoh is an impactful open source techie and writer, across multiple projects.</div><div><ul style="text-align: left;"><li>She co-developed a <a href="https://gitlab.com/tgdp/templates/-/tree/main/how-to">howto documentation template</a> for The Good Docs Project. </li><li>She actively contributes to, and supports other writers in Good Docs weekly meetings</li><li>She writes <a href="https://www.freecodecamp.org/news/author/ophelia/">training material for freeCodeCamp</a>.</li><li>She <a href="https://www.womenwhocode.com/frontend">teaches women to code in Ghana</a>. </li></ul></div><h3 style="text-align: left;">Joseph Kato</h3><div>Joseph is the founding creator of <a href="https://vale.sh/">vale.sh</a>, an open source grammar checker, used to check the quality of documentation against a project’s documentation style guide. The tool is well written, in a modular fashion that supports extensions.</div><h3 style="text-align: left;">Mengmeng Tang</h3><div>Mengmeng Tang is an experienced technical writer who has been playing a lead role developing templates and writing best practices within The Good Docs Project.</div><div><ul style="text-align: left;"><li>Most notably, Mengmeng has led the development of a <a href="https://gitlab.com/tgdp/templates/-/tree/main/api-reference">API Reference template</a>, researching multiple source reference documentation processes, coordinated community contributions from multiple people, and drawing it together into an authoritative source.</li><li>She has been mentoring others.</li><li>She has been an active contributor to other Good Docs forums and initiatives, such as our cross-template style discussion forum.</li><li>She is regularly stepping in and helping others out.</li></ul></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-46052015523282453922023-05-24T09:05:00.003+10:002023-05-24T09:05:36.335+10:00Keystone Project - The Good Docs Project<div class="separator" style="clear: both; text-align: center;"><em><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhQcwGMZGsOGL6G8QJLUmXi2w5g2oW0TkPf1uVjI_w5-U-MeBu3dplnYbgQdzdkxqlCJvqdSpDMRq8gebSHhQ9l5j85NGgjLxnp8V7WKv2DUazh3nvfIdsYi-gP3L22GPOCPTO-Xy9eACuNwIaHMsIzU_9QrrNI-h7hC_6u5ozFPKQo71Ev1A/s432/Keystone.png" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" data-original-height="1024" data-original-width="1024" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhQcwGMZGsOGL6G8QJLUmXi2w5g2oW0TkPf1uVjI_w5-U-MeBu3dplnYbgQdzdkxqlCJvqdSpDMRq8gebSHhQ9l5j85NGgjLxnp8V7WKv2DUazh3nvfIdsYi-gP3L22GPOCPTO-Xy9eACuNwIaHMsIzU_9QrrNI-h7hC_6u5ozFPKQo71Ev1A/s320/Keystone.png" width="320" /></a></em></div>
The Good Docs Project is growing into a <em>keystone project</em> for software ecosystems.<div><h3 style="text-align: left;">What’s a Keystone Project?</h3>
<p>
In architecture, a masonry arch cannot be self-supporting until the <a href="https://en.wikipedia.org/wiki/Keystone_(architecture)">keystone</a> is placed. This stone locks together the whole structure.
</p>
<p>
The concept is also found in ecology. A <a href="https://education.nationalgeographic.org/resource/role-keystone-species-ecosystem/">keystone species</a> is an organism that helps define an entire ecosystem - and it has a disproportionate influence on the ecosystem around it. Bees are a <em>keystone species</em>. Without bees, flowers don’t get pollinated, plants don’t reproduce, animals starve, and the ecosystem collapses.
</p>
<p>
In the technology domain, <a href="https://git-scm.com/">Git</a> can be thought of as a <em>keystone project</em>. Its version control underpins many software projects, meaning it has a disproportionate positive impact on the software ecosystem.
</p>
<h3 style="text-align: left;">Is documentation disproportionately impactful?</h3>
<p>
Yes. Time and again, surveys call out documentation quality as a key criteria to:
</p><ul style="text-align: left;"><li>
Ensure developer productivity,</li><li>Ensure product quality, and</li><li>Attract a user base.</li></ul>
<p>
For instance:
</p>
<p>
<em>Developers see about a 50% productivity boost when documentation is up-to-date, detailed, reliable, and comes in different formats.—<a href="https://octoverse.github.com/2021/creating-documentation/">The 2021 State of the Octoverse, Github</a></em>
</p>
<p>
… Find more stats in the <a href="https://docs.google.com/presentation/d/1fZqNm7WH1hYgmjuq2lkltbfTZYDZeclpuaoLabjihJ8/">Docs Fact Pack</a>.
</p>
<h3 style="text-align: left;">What is good documentation?</h3>
<p>
Good documentation provides:
</p>
<p>
<em>Just enough info,<br />When it is needed,<br />To support a specific action,<br />At the quality required.</em>
</p>
<p>
Getting this balance right is both an art and a science. The Good Docs Project explains how, by providing best practice templates and writing instructions for documenting open source software.
</p>
<h3 style="text-align: left;">Are we there yet?</h3>
<p>
Not quite. We will be a <em>keystone project</em> when:</p><p></p><ul style="text-align: left;"><li>Open source surveys stop <a href="https://docs.google.com/presentation/d/1fZqNm7WH1hYgmjuq2lkltbfTZYDZeclpuaoLabjihJ8/edit#slide=id.gfc7ec19147_1_38">reporting poor documentation</a> as a key developer gripe, and</li><li>People attribute documentation improvements to <a href="https://thegooddocsproject.dev/">The Good Docs Project</a> templates and processes.</li></ul><br /></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-85858984280441887932023-03-04T07:14:00.004+11:002023-03-04T13:30:21.162+11:00Signing off from Google<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg5pngt13vwrXFZid9zjGWgNWK0qpytt2A3x3jyruVlrEto5s-Lg9ObCNzI-dgaUPhDEWAcEjnh2fh_frhSNQh1VickJjbFsy6C8pru4uof_VEdUxWxgHHQzZGEB4ilpTEHbkDao7KN6lh0uXnLED6j1gXzHeWAPzrCF78aK5Z1AnDGqnbEGA/s2179/GSnookerCue.jpg" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img alt="Cameron at Google" border="0" data-original-height="1370" data-original-width="2179" height="201" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg5pngt13vwrXFZid9zjGWgNWK0qpytt2A3x3jyruVlrEto5s-Lg9ObCNzI-dgaUPhDEWAcEjnh2fh_frhSNQh1VickJjbFsy6C8pru4uof_VEdUxWxgHHQzZGEB4ilpTEHbkDao7KN6lh0uXnLED6j1gXzHeWAPzrCF78aK5Z1AnDGqnbEGA/w320-h201/GSnookerCue.jpg" title="Cameron at Google" width="320" /></a></div><br />It's been a great three years at Google. So many opportunities to do something meaningful, to learn, to be impactful.<br /><h3 style="text-align: left;">Chromebook requirements team</h3>It's been an exciting journey maturing requirements management, traceability, testing. It's enabling chromebooks to scale. We have a talented team - I'm looking forward to hearing continued great things from you.<br /><h3 style="text-align: left;">Cross-Google requirements engineering folks</h3>It's been wonderful to see the cross-pollination of ideas between projects. We have learned from your collective wisdom. Will be great to see this continue.<br /><h3 style="text-align: left;">ChromeOS in general</h3>I've worked 1:1 with many hundreds of you, polishing requirements and documentation, and have been very proud of what we have achieved together. Keep up the good work.<br /><h3 style="text-align: left;">Chromebook Docs & Training team</h3>How far we've come in lifting our processes and tools and documentation quality. Still plenty to do. Great to have your expertise to realize the future challenges.<div><h3>Sydney Chromebook team</h3>Thanks for your encouragement, for your personal face-to-face friendships, for being my lunch buddies, for your collaboration in developing requirements.<br /><h3 style="text-align: left;">Google Tech Writing community</h3>I'm going to really miss tapping into such a depth of wisdom embodied within Google's tech writing community. I'm particularly disappointed to be leaving just as a cross-Google tech writing initiative is kicking off. It will be great fun and has great goals. I'm now extra-hopeful that some of you will collaborate externally, so us Ex-Googlers can join in. I hang out in <a href="https://thegooddocsproject.dev" target="_blank">The Good Docs Project</a>.<br /><h3 style="text-align: left;">Green AU team</h3>We have such a great opportunity to amplify Green ideas through Google, and to bring international Googler Green ideas and technology to Australia.<br />And Australia is ideally positioned to become an international leader in Green energy, something we can tap into and amplify within Google.<br />I’m hopeful my future employment is in this green space, and I get to work with you again from the outside.<br /><h3 style="text-align: left;">Geo folks</h3>Great to see folks embracing that:<br /><ol style="text-align: left;"><li>We have a <a href="https://docs.google.com/presentation/d/1CN4dgoftV0wwN7hkbORt6v2AXrAQY_F7KnjP2Zg0sUc/edit#slide=id.g1edcbb7b7e3_0_1648" target="_blank">misaligned mapping problem</a> due to hacks which ignore tectonic plate motion.</li><li>The problem is solvable, with easy quick wins, starting with storing coordinates in a static datum.</li></ol>I look forward to hearing progress in this area.<br /><h3 style="text-align: left;">Why leave?</h3><a href="https://blog.google/inside-google/message-ceo/january-update/" target="_blank">Google’s been forced to realign priorities and is cutting 12,000 roles</a> “across Alphabet, product areas, functions, levels and regions”. My Sydney team is one of those targeted.<br /><h3 style="text-align: left;">Would I come back?</h3><ul style="text-align: left;"><li>Yes. I've met so many interesting, genuine and passionate people in Google, thinking bigger than just their day jobs.</li><li>Yes. Google provides great opportunities to amplify personal contributions to the world.</li><li>Yes. It's hard to beat Google's great lunches.</li></ul><h3 style="text-align: left;">What's left for Google to get better at?</h3><ul style="text-align: left;"><li>We're good, but sometimes we should remind ourselves that awesomeness exists outside of Google too. It's worth looking.</li><li>Maybe collaborate more. Yes, it costs more in the short term, but it's usually worth it for the long term play.</li><li>Maybe ask if our internal initiatives can help the world, as well as just Googlers. There's usually a good business case.</li><li>And if really brave, read Praveen Seshadri’s essay <a href="https://medium.com/@pravse/the-maze-is-in-the-mouse-980c57cfd61a" target="_blank">The maze is in the mouse</a>.</li></ul><h3 style="text-align: left;">What's next for me?</h3><div><ul style="text-align: left;"><li>There are some wicked challenges in the Green space, and Australia has the opportunity to become a green energy leader. I'd love to apply my skills here.</li><li>We've been maturing the tech writing disciple within <a href="https://thegooddocsproject.dev" target="_blank">The Good Docs Project</a>. It would be nice to continue this.</li><li>And I'm open to picking up in the Geospatial Business Analysis, or Systems Engineering spaces again too.</li></ul></div><div>This <a href="https://www.linkedin.com/pulse/signing-off-from-google-cameron-shorter" target="_blank">article is also published on LinkedIn</a>.</div><div>--</div><div>Cameron Shorter,</div><div>Senior Technical Writer, Google's ChromeOS Platforms</div></div><div><br /></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-43663418460513605612022-12-02T15:30:00.002+11:002023-03-01T21:42:38.166+11:00Meet a Google Tech Writer<p>Yep, I'm one of the <a href="https://developers.google.com/tech-writing/becoming/meet">profiled Google tech writers</a>:</p><h2 style="text-align: left;">Cameron's story</h2><p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiRA1dbXmORfWgh4yXONH0VY99miQsmQMdIZxrJt1odUggcXfHbEJLU_h2SyJGmD087R78gpVz9P0VD0OQWSj4YS8qZzdf2Xs23sfANPoUakEdJ1fP_sDRTiZjZ927PebRVcuaPlsq5wf7mkksXP6iUUgGXdRKUtXn0RxKIatV-yGMh7zPapg/s480/CameronPhoto_480.jpg" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" data-original-height="480" data-original-width="480" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiRA1dbXmORfWgh4yXONH0VY99miQsmQMdIZxrJt1odUggcXfHbEJLU_h2SyJGmD087R78gpVz9P0VD0OQWSj4YS8qZzdf2Xs23sfANPoUakEdJ1fP_sDRTiZjZ927PebRVcuaPlsq5wf7mkksXP6iUUgGXdRKUtXn0RxKIatV-yGMh7zPapg/s320/CameronPhoto_480.jpg" width="320" /></a></div>I was surprised to wake one morning and realize I’d become a writer.<p></p><p>My good science and sub-optimal English school marks led me to pursue a software engineering career. (Who needs to write when you’re a good programmer? Right?)</p><p>Outside of work, I leaned into my greenie ideals and helped build a bicycle activist movement: Thousands of yahooing cyclists riding through city peak hour traffic, publicity stunts, chats with the police, media interviews... Of course, my software career wasn’t being advanced by these extra-curricular activities.</p><p>Over time, my day job gradually moved from engineer to business analysis to sales support, to technical communicator, and oops, … I’d become a technical writer. How did that happen?</p><p>Well, it turns out that in knowledge economies, businesses value people who can explain technical concepts clearly, efficiently, and effectively. The activist communication skills I’d learned, merged with my engineering background, were useful after all.</p><p>And as an added bonus, I really enjoy the communication challenges, the breadth of work, and the impact I can offer teams. You might, too?</p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-57817933916965568872022-10-21T15:27:00.013+11:002023-03-30T15:21:37.065+11:00Requirement writing<p></p><div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/9g9IvAe6-ss" width="320" youtube-src-id="9g9IvAe6-ss"></iframe></div><br /><ul style="text-align: left;"><li><i> <span face="Roboto, Noto, sans-serif" style="background-color: white; color: #0d0d0d; font-size: 15px; white-space: pre-wrap;">"When [condition] the [device] MUST [do something]."</span></i></li></ul><p></p><span face="Roboto, Noto, sans-serif" style="background-color: white; color: #0d0d0d; font-size: 15px; white-space: pre-wrap;">It's surprising how many ways we can get this pattern wrong.
This presentation walks through the requirement-writing-guide used by Google Chromebook engineers, and open sourced into The Good Docs Project. It covers:
<ul style="text-align: left;"><li><span face="Roboto, Noto, sans-serif" style="background-color: white; color: #0d0d0d; font-size: 15px; white-space: pre-wrap;">Business drivers behind requirements management.</span></li><li><span face="Roboto, Noto, sans-serif" style="background-color: white; color: #0d0d0d; font-size: 15px; white-space: pre-wrap;">Writing rules to follow.</span></li><li><span face="Roboto, Noto, sans-serif" style="background-color: white; color: #0d0d0d; font-size: 15px; white-space: pre-wrap;">Broader systemic challenges to be faced.</span></li></ul>It draws upon engineering standards and best practices.</span><div><ul style="text-align: left;"><li><a href="https://docs.google.com/presentation/d/1To4jmtSvOEdG5lcP5MAGG2Ez3fhkLxqiokURKUGU8is/edit#slide=id.g2014b0d8dce_3_605" style="font-size: 15px; white-space: pre-wrap;" target="_blank">Slides (cleaned for public release)</a><span style="color: #0d0d0d; font-size: 15px; white-space: pre-wrap;">.</span></li><li><span style="color: #0d0d0d; font-size: 15px; white-space: pre-wrap;"><a href="https://www.youtube.com/watch?v=9g9IvAe6-ss&t=1s" target="_blank">Video</a> (23 mins).</span></li></ul><span style="color: #0d0d0d; font-size: 15px; white-space: pre-wrap;"></span><div><div><br /></div></div></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-44148319037599900772022-10-04T07:14:00.066+11:002022-12-18T08:26:14.822+11:00Open Source awards for Good Docs contributors<div class="separator"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/s512/OSS+BLOG+Peer+Bonus.png" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/w320-h165/OSS+BLOG+Peer+Bonus.png" /></a></div><br /><br />Congratulations to Google's <a href="https://opensource.googleblog.com/2022/09/announcing-the-second-group-of-open-source-peer-bonus-winners-in-2022.html">Open Source Peer Bonus award</a> winners. Winners from <a href="https://thegooddocsproject.dev">The Good Docs Project</a> include:<br /><h3 style="text-align: left;">Felicity Brand</h3>Felicity Brand has been an incredibly impactful contributor within The Good Docs Project.<br /><ul style="text-align: left;"><li>She is one of the project’s founding members, and an active contributor to the Project Steering Committee.</li><li>She regularly comes up with innovative and practical ideas, usually backed by deep background knowledge.</li><li>She is regularly supporting others, focusing on key areas that need help. Most recently she has been playing a lead role developing a Content Strategy, Website Architecture, and development of project blogs.</li><li>When boring but important things need to get done, Felicity is regularly stepping in to help out.</li><li>And her fun, supportive and encouraging style is contagious. It makes those around her want to help.</li></ul>In Felicity's words:<br /><blockquote>“I’m very pleased and proud to receive a Google Open Source Peer Bonus award. I was nominated for my contributions to The Good Docs Project where we are creating technical writing templates to help other projects create high-quality documentation. I’m passionate about the work we’re doing there, and have been hanging around the project since its inception in 2019. This is a friendly, inclusive community creating a safe space for folk to dip their toe into open source. We are global, and new folk are always welcome.”</blockquote><h3 style="text-align: left;">Bryan Klein</h3>Bryan Klein is a technical wizard when it comes to setting up documentation based infrastructure. He has been setting up or advising on much of the infrastructure behind The Good Docs Project, a project developing templates, processes and tools to help developers write great documentation.<br /><ul style="text-align: left;"><li>He is one of the main drivers behind a “Doc tools easy button”, a bold initiative to build the toolchain a for a docs website based on templates from The Good Docs Project.</li><li>He is an active contributor to the Project Steering Committee.</li><li>He is fun, supportive, encouraging, is quick to jump in and help others when they get stuck. He is one of the key people behind our unofficial tech-help channel</li></ul>In Bryan's words:<br /><blockquote>“I've been actively working on open source projects since my time at NIST with the FDS project starting in 2006. More recently with The Good Docs Project (TGDP) since 2020. It's been a very rewarding experience to contribute to TGDP, with such an amazing diversity of participants, perspectives and interests involved. To be given recognition through the OSPB program was a pleasant and unexpected surprise. While it's not at all what I am participating in the project for, it feels great to have someone else in the project bring my name up for this award. Thank you to TGDP and to Google for this honor.”</blockquote><h3 style="text-align: left;">Aaron Peters</h3>Aaron Peters has been bringing his project management expertise to The Good Docs Project.<br /><ul style="text-align: left;"><li>Aaron has been a long term contributor to the project, and is an active member of our Project Steering Committee (PSC).</li><li>He coordinates our Request of Comment (RFC) update process.</li><li>He has led the development of our baseline development and release process.</li><li>And he has been researching and setting up the supporting tool chains.</li></ul>All his foundational work is setting up our project to achieve quality at scale.<br /><h3 style="text-align: left;">Serena Jolley</h3>Serena Jolley deserves recognition for generously sharing her deep experience as a User Experience (UX) designer with The Good Docs Project.<br /><ul style="text-align: left;"><li>She established a heartbeat in our previously dormant “Chronologue” working group – a group creating a fake project which our documentation templates will create examples for.</li><li>She’s played a vital role creating well-thought out wireframes for the fake project.</li><li>She shares her knowledge with her teammates by being transparent and explaining her methodology, and has specifically mentored a junior UX designer along the way.</li></ul>Without Serena, this working group wouldn’t have achieved its current momentum.<br /><h3 style="text-align: left;">Ian Nguyen</h3>Ian's been working within our Chronologue working group, which is creating a fake project which our documentation templates will create examples for.<br /><ul style="text-align: left;"><li>Ian is the craftsman who has been building the fake product our group wants to document.</li><li>He has been designing and implementing an API to retrieve data for events.</li><li>He has turned wireframes into code, and he has been building a tangible web experience for the Chronologue project.</li><li>Without his creativity and technical aptitude, we would not have a “fake” product to document.</li></ul><h3 style="text-align: left;">Tina Lüdtke</h3>Tina was ineligible for the Open Source Peer Bonus, as she was hired by Google as an employee. Instead she was awarded a Google Peer Bonus.<br /><div>Tina has led our “fake example project” makes excellent contributions to the Content Strategy, Blog, and Book Club groups, and is an active contributor to the Project Steering Committee.<br />Check her post <a href="https://thegooddocsproject.dev/blog/6-resources-for-starting-your-journey-into-docs/">6 Resources for Starting Your Journey Into Docs</a>.</div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-26980396712680341442022-09-30T23:11:00.026+10:002023-05-11T07:16:31.782+10:00When to call in us tech writers<div style="text-align: left;"><div style="text-align: center;"><a href="https://docs.google.com/presentation/d/1qE0tYgkFffS5fxjS-06INQ7ovGcV6vhXNrhIRO3KLG4/" style="margin-left: 1em; margin-right: 1em;"><img alt="Children talking through sonic playground pipes" border="0" data-original-height="778" data-original-width="969" height="257" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhQW2E3AtPnKvrdZOZ_MD9dSmCXa5MosVM_zvj_emuCWPrVmEwFzSKXoJwGFgFUgbrfWnmIvXzm7HQIg1GSdGf5O-Oy3fPsV8s8L5WhKz1dE8kFDgMf41e9Gi8TPpBrBbtlcU2SBWq7ckScB-op96LpWdUqMg-8RuViSfIpwIuyLXFweTExVA/w320-h257/Sonic-Playground.jpg" title="Talking through pipes. Image: https://www.charcoalblue.com/news/view/visit-the-sonic-playground-this-summer" width="320" /></a></div></div><div style="text-align: left;"><div><br /></div><div><div style="text-align: center;"><i>In a knowledge economy, effectiveness depends upon transferring ideas between people.</i></div><i><div style="text-align: center;"><i>Technical writing is the art of optimizing the communication pipes.</i></div></i></div><div><br /></div><div>Good documentation provides:</div><div><i></i></div><blockquote><div><i>Just enough info,</i></div><div><i>When it is needed,</i></div><div><i>To support a specific action,</i></div><div><i>At the quality required.</i></div></blockquote><div><i></i></div><div>This presentation highlights the key principles of technical writing, and when to call in us technical writers.</div><div><ul><li><a href="https://docs.google.com/presentation/d/1qE0tYgkFffS5fxjS-06INQ7ovGcV6vhXNrhIRO3KLG4" target="_blank">Slides</a>.</li><li><a href="https://www.youtube.com/watch?v=l00Lq3xCWcg" target="_blank">Video</a> (6 mins).</li></ul></div></div><div><div><div><div style="font-weight: bold;"><br /></div></div><div><br /></div></div></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-63325923199747854622022-04-18T14:20:00.003+10:002022-08-04T10:07:29.667+10:00Open Source Peer Bonuses for Good Doc Templateers<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/s512/OSS+BLOG+Peer+Bonus.png" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img alt="open source peer bonus logo" border="0" data-original-height="264" data-original-width="512" height="165" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/w320-h165/OSS+BLOG+Peer+Bonus.png" width="320" /></a></div><br /><p> Congratulations to five templatateers from <a href="https://thegooddocsproject.dev">The Good Docs Project</a> for your <a href="https://opensource.googleblog.com/2022/03/Announcing-First-Group-of-Google-Open-Source-Peer-Bonus-Winners-in-2022.html">Open Source Peer Bonus award</a> from Google. This cool award enables Google employees to recognize and thank a few valued open source contributors. It includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.</p><h3 style="text-align: left;">Gayathri Krishnaswamy, Chris Ganta and Nelson Guya</h3><p>Gayathri, Chris and Nelson have been peer-writing open source documentation templates within our EMEA-APAC working group. This includes:</p><p></p><ul style="text-align: left;"><li>Deep research into “What is a good quickstart document”.</li><li>Established a quickstart template and associated guide for documenting open source projects.</li><li>Projecting their writing expertise into the external <a href="https://live.osgeo.org">OSGeo-Live</a> open source project.</li><li>Establishing and describing "peer writing". Look out for their talk about their experience at the upcoming Write the Docs conference: <a href="https://www.writethedocs.org/conf/portland/2022/speakers/#speaker-chris-ganta">Peer writing and beyond - An experimental approach to a sustainable open-source projects</a>.</li></ul>Notably call outs:<div><ul style="text-align: left;"><li>As well as doing a lot of the research, Gayathri has managed the copying of docs from Google Docs into the github repository.</li><li>Nelson initially worked out the OSGeo-Live documentation pipeline, and then mentored Chris and Gayathri in getting started.</li><li>Chris did a lot of the group coordination, and has delivered an excellent presentation on the peer writing strategy that the group developed, laying foundations for how it can be replicated.</li></ul><h3 style="text-align: left;">Carrie Crowe</h3><p>Carrie has grown into a key role in within The Good Docs Project:</p><p></p><ul style="text-align: left;"><li>She’s head of the content strategy team, driving the project contributors to frame their work in terms of understanding our user bases, accounting for where individual elements of our project need to live.</li><li>Specifically, in the last year she’s helped the project clarify its scope and focus, with the ideals of providing education to developers needing to write docs, templates for different types of docs, systems for deploying docs, and related doc subjects. That’s all thanks to her stepping in as a product manager to organize a big group of volunteers, alongside her technical writing skills used in article and template contributions.</li><li>In recognition of her work, she's recently accepted a co-chair role of The Good Docs project.</li></ul><h3 style="text-align: left;">Deanna Thompson</h3><p>Deanna Thompson is an experienced technical writer who plays an impactful role within The Good Docs Project.</p><p></p><ul style="text-align: left;"><li>She done extensive research and community consultation to build a template for writing tutorials that developers can use.</li><li>She continually provides insightful feedback to templates others develop, showing leadership and mentorship our team greatly benefits from.</li><li>She's been playing a lead role in establishing training for using git for tech writers within our project.</li><li>And in recognition of her work, she has recently accepted a role on the Project Steering Committee.</li><li>She’s certainly raised the bar on what we hope to get out of contributors!</li></ul><p></p><div><br /></div><div><br /></div><p></p></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-11813353142282882102022-04-18T11:39:00.000+10:002022-04-18T11:39:01.730+10:00Curly Beach to Forestway by bicycle<p>Cycle from Curl Curl beach back to Forestway via bike paths, back streets, and a short stretch of dirt trail.</p><p></p><div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/bESXdC3X3C8" width="320" youtube-src-id="bESXdC3X3C8"></iframe></div><br /><div style="text-align: center;"><i>10 kms. 30 mins.</i></div><div><div style="text-align: center;"><i>Enjoy the journey!</i></div><p></p><p><br /></p><p> </p></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-49911544911653957582022-01-26T10:10:00.009+11:002022-12-17T21:44:26.482+11:00My Open Source Docs addiction<p> </p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiZF16in2e-Ab_RADMkZ8SPIjddp7ex4JHID0bJMl4F52z7dgcX9JlDJjoud0zJldO_jy-djcVS0cJQnUzSGIW6LTJsxvUhhb46SyMq4FWubkKk__dLdncxg6o7wItsUMpV32xf/" style="margin-left: 1em; margin-right: 1em;"><img alt="My Open Source Docs Addiction" data-original-height="1030" data-original-width="1873" height="352" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiZF16in2e-Ab_RADMkZ8SPIjddp7ex4JHID0bJMl4F52z7dgcX9JlDJjoud0zJldO_jy-djcVS0cJQnUzSGIW6LTJsxvUhhb46SyMq4FWubkKk__dLdncxg6o7wItsUMpV32xf/w640-h352/OpenSourceAddict.png" title="My Open Source Docs Addiction" width="640" /></a></div><p>Why am I addicted to open source docs?</p><p></p><ul style="text-align: left;"><li>"Giving back" adds extra meaning and purpose to my life.</li><li>It's impactful.</li><li>I can tackle wild moon-shot ideas.</li><li>I can choose to do-it-right over short-termism.</li><li>I am often working on the cutting edge.</li><li>I can choose morals over profits.</li><li>I get to collaborate with a community of like-minded souls.</li><li>It’s a fun, safe and engaging way to learn, and looks great on a resume.</li><li>The world desperately needs doc heros, and as a tech writer I'm uniquely qualified to help.</li><li>I've uncovered my alter-ego:</li></ul><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgjHABAY3V8emhY-AG9y06exDXN0KSoSZg5yBoQ_qGDhZlAEZJjXxbjhWyDroE-YLyKyGzHYztyVlpncx4SE1bOl2gV6RLmi6siTmSGH6EIJqoMi-88m92V8rLalR7l7p-dtaxx/" style="margin-left: 1em; margin-right: 1em;"><img alt="I'm an open source technical writer. What's your super power?" data-original-height="1289" data-original-width="1700" height="485" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgjHABAY3V8emhY-AG9y06exDXN0KSoSZg5yBoQ_qGDhZlAEZJjXxbjhWyDroE-YLyKyGzHYztyVlpncx4SE1bOl2gV6RLmi6siTmSGH6EIJqoMi-88m92V8rLalR7l7p-dtaxx/w640-h485/superwriter.png" title="I'm an open source technical writer. What's your super power?" width="640" /></a></div><br />Version 1.0 of this lightning of this talk was presented at an internal tech writers event in January 2022, and a tweaked 2.0 was presented at Write the Docs Australia, December 2022.<div><ul style="text-align: left;"><li><a href="https://www.youtube.com/watch?v=S-6NxPUorgU" target="_blank">Video</a></li><li><a href="https://docs.google.com/presentation/d/1GG6LoSbN9zuMZTMDUXP88YBwR94RRFZwf3OFjou_e6Y/edit?resourcekey=0-TVG_qeh3wAqRU7MswJt7Pw" target="_blank">Slides</a></li></ul><div><p></p></div></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-69388682518723613612022-01-15T20:11:00.005+11:002022-04-07T17:04:18.372+10:00Frenchs Forest to Warringah Mall by bicycle<p>Want a quick, 20 minute, pleasant and safe bicycle route from Frenchs Forest down to Warringah Mall? Try this: </p><div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/wc_QkR7rtoQ" width="320" youtube-src-id="wc_QkR7rtoQ"></iframe></div><p style="text-align: center;"><i>Cycle from Frenchs Forest down to Warringah Mall via bike paths, back streets, and a short stretch of dirt trail.</i></p><p style="text-align: center;"><i>Enjoy the journey!</i></p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-81782453736813528522021-12-17T09:09:00.003+11:002023-06-18T07:05:27.055+10:00Defining good
<p>Within non-trivial technical projects, it helps to have a common language to describe "good":</p><ul style="text-align: left;"><li>It enables cross-feature comparisons and prioritization.</li><li>It facilitates conversations between stakeholders, business and developers.</li></ul><p>This page suggests a feature quality scale, along with how it can be applied.</p>
<h2>Quality scale</h2>
<p>A quality scale can be applied to:</p><ul style="text-align: left;"><li>Business goals, stakeholder needs, features, quality, schedule, maintenance, and more ...
</li></ul><p></p>
<table style="border: 1px solid black;">
<tbody><tr>
<td>
</td>
<td><strong>User experience</strong>
</td>
<td><strong>Description</strong>
</td>
<td><strong>Requires</strong>
</td>
</tr>
<tr>
<td style="background-color: #b4a7d6;"><strong>Qx</strong>
</td>
<td style="background-color: #b4a7d6;"><strong>Over-deliver</strong>
</td>
<td style="background-color: #b4a7d6;">* Functionality cannot be noticed or used by the user.
</td>
<td style="background-color: #b4a7d6;">
</td>
</tr>
<tr>
<td style="background-color: #a4c2f4;"><strong>Q5</strong>
</td>
<td style="background-color: #a4c2f4;"><strong>Delight</strong>
</td>
<td style="background-color: #a4c2f4;">* Anticipate user desires, and provide it.
</td>
<td style="background-color: #a4c2f4;">* Understand the user’s desires and passions.
</td>
</tr>
<tr>
<td style="background-color: #6aa84f;"><strong>Q4</strong>
</td>
<td style="background-color: #6aa84f;"><strong>Impress</strong>
</td>
<td style="background-color: #6aa84f;">* Anticipate user unanticipated needs, and provide it.
</td>
<td style="background-color: #6aa84f;">* Analyze the user behaviors and needs.<br />* Understand the product capabilities.<br />* Establish critical user journeys.</td>
</tr>
<tr>
<td style="background-color: #b6d7a8;"><strong>Q3</strong>
</td>
<td style="background-color: #b6d7a8;"><strong>Satisfy</strong>
</td>
<td style="background-color: #b6d7a8;">* Meet user’s known wants.
</td>
<td style="background-color: #b6d7a8;">* Listen to the user’s asks.
</td>
</tr>
<tr>
<td style="background-color: #ffe599;"><strong>Q2</strong>
</td>
<td style="background-color: #ffe599;"><strong>Underperform</strong>
</td>
<td style="background-color: #ffe599;">* Under specified or poorly implemented.<br />* User experience includes many micro-frustrations.</td>
<td style="background-color: #ffe599;">* Meet purchasing authority’s specification.<br />* Cost saving implementation.<br />* Minimal testing.<p></p></td>
</tr>
<tr>
<td style="background-color: #f6b26b;"><strong>Q1</strong>
</td>
<td style="background-color: #f6b26b;"><strong>Not practically functional</strong>
</td>
<td style="background-color: #f6b26b;">* While the product “works” the experience is so poor that the user chooses to use something else if available.
</td>
<td style="background-color: #f6b26b;">
</td>
</tr>
<tr>
<td style="background-color: #e06666;"><strong>Q0</strong>
</td>
<td style="background-color: #e06666;"><strong>Broken</strong>
</td>
<td style="background-color: #e06666;">* Functionality doesn’t work at all.
</td>
<td style="background-color: #e06666;">
</td>
</tr>
</tbody></table>
<p style="text-align: center;">
<em>Possible quality scale</em>
</p>
<h2>Quality categories for each feature</h2>
<p>
For each feature, a project can define quality categories.</p>
<table style="border: 1px solid black;">
<tbody><tr>
<td><strong>Feature</strong>
</td>
<td><strong>Delight</strong>
</td>
<td><strong>Impress</strong>
</td>
<td><strong>Satisfy</strong>
</td>
<td><strong>Underperform</strong>
</td>
<td><strong>Not practically functional</strong>
</td>
<td><strong>Broken</strong>
</td>
</tr>
<tr>
<td>On/off button
</td>
<td style="background-color: #a4c2f4;">
</td>
<td style="background-color: #6aa84f;">
</td>
<td style="background-color: #b6d7a8;">Works
</td>
<td style="background-color: #ffe599;">
</td>
<td style="background-color: #f6b26b;">
</td>
<td style="background-color: #e06666;">Fails
</td>
</tr>
<tr>
<td>Waterproof to
</td>
<td style="background-color: #a4c2f4;">
</td>
<td style="background-color: #6aa84f;">> 100m
</td>
<td style="background-color: #b6d7a8;">> 10m
</td>
<td style="background-color: #ffe599;">> 1m
</td>
<td style="background-color: #f6b26b;">
</td>
<td style="background-color: #e06666;">< 1m
</td>
</tr>
<tr>
<td>Uptime
</td>
<td style="background-color: #a4c2f4;">> 99.999%
</td>
<td style="background-color: #6aa84f;">> 99.99%
</td>
<td style="background-color: #b6d7a8;">> 99.9%
</td>
<td style="background-color: #ffe599;">> 99%
</td>
<td style="background-color: #f6b26b;">> 90%
</td>
<td style="background-color: #e06666;">< 90%
</td>
</tr>
</tbody></table>
<p style="text-align: center;">
<em>Example quality criteria</em></p><p><b>Note:</b> Many features won't need the full scale.</p>
<h2>Phase exit criteria</h2>
<p>
The importance of each quality criteria will vary depending upon:
</p><ul>
<li>Different products.
</li><li>Different features.
</li><li>Different development phases: alpha, staging for test, production/stable release.</li></ul>
<p>
<strong>Phase: Alpha release</strong>
</p>
<table style="border: 1px solid black;">
<tbody><tr>
<td><strong>Feature</strong>
</td>
<td><strong>Priority</strong>
</td>
<td><strong>Should</strong>
</td>
<td><strong>Must</strong>
</td>
<td><strong>Error tolerance</strong>
</td>
</tr>
<tr>
<td>On/off button
</td>
<td>P1
</td>
<td style="background-color: #b6d7a8;">Satisfy
</td>
<td style="background-color: #b6d7a8;">Satisfy
</td>
<td style="background-color: #b6d7a8;">Satisfy
</td>
</tr>
<tr>
<td>Waterproof
</td>
<td>P3
</td>
<td style="background-color: #6aa84f;">Impress
</td>
<td style="background-color: #ffe599;">Underperform
</td>
<td style="background-color: #e06666;">Broken
</td>
</tr>
<tr>
<td>Uptime
</td>
<td>P2
</td>
<td style="background-color: #6aa84f;">Impress
</td>
<td style="background-color: #b6d7a8;">Satisfy
</td>
<td style="background-color: #ffe599;">Underperform
</td>
</tr>
</tbody></table>
<p style="text-align: center;">
<em>Example phase exit criteria</em>
</p>
<h2>As requirements</h2>
<p>
The criteria can be converted into traditional requirements:
</p>
<table style="border: 1px solid black;">
<tbody><tr>
<td>The device
</td>
<td>should
</td>
<td style="background-color: #6aa84f;">be waterproof to 100m.
</td>
</tr>
<tr>
<td>The device
</td>
<td>must
</td>
<td style="background-color: #ffe599;">be waterproof to 1m.
</td>
</tr>
</tbody></table><em style="text-align: center;"><div style="text-align: center;"><em>Example requirements</em></div></em>
<h2>Bug severity levels</h2>
<p>
Terminology from the quality scale can be aligned with bug severity levels. Severity can be driven by impact to the user, or impact to the business.</p>
<table style="border: 1px solid black;">
<tbody><tr>
<td><strong>Severity</strong>
</td>
<td><strong>User Impact</strong>
</td>
<td><strong>Business Impact</strong>
</td>
</tr>
<tr>
<td style="background-color: #fff2cc;">S4 Trivial
</td>
<td style="background-color: #fff2cc;">* P3 feature <i>underperforms
</i></td>
<td style="background-color: #fff2cc;">* Person days to fix.
</td>
</tr>
<tr>
<td style="background-color: #ffe599;">S3 Minor
</td>
<td style="background-color: #ffe599;">* P3 feature is <i>broken<br /></i>* P2 feature <i>underperforms</i></td>
<td style="background-color: #ffe599;">* Person weeks to fix.
</td>
</tr>
<tr>
<td style="background-color: #f6b26b;">S2 Major
</td>
<td style="background-color: #f6b26b;">* P1 feature is <i>broken</i>, with work-around<br />* P2 feature is <i>broken</i>, no work-around</td>
<td style="background-color: #f6b26b;">* Person months to fix.
</td>
</tr>
<tr>
<td style="background-color: #e06666;">S1 Critical
</td>
<td style="background-color: #e06666;">* P1 feature is <i>broken</i>. No work-around.
</td>
<td style="background-color: #e06666;">* Upcoming releases blocked until fix provided.
</td>
</tr>
</tbody></table>
<p style="text-align: center;">
<em>Example severity scale</em>
</p><p style="text-align: left;"></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi_s2IrlsGA1TQ-hwIbTgy42xw1ZQ2ONR7SX7-oWA-XsfNBHyouFIB99d_vp0CEUshQ-I6ik4OIk3HX2i-DAQr1ZbJLJ_jZ6uv5gT2OJrz8u9Vc-hWBwNPJIFNbyOv1nvw1jXqke6RS0G5RT6QAYGbuhCApLkND6rfwrLG8nqtOjfJVFM-EMA/s627/QualityAtScale.png" style="margin-left: 1em; margin-right: 1em;"><img alt="Quality Scale" border="0" data-original-height="530" data-original-width="627" height="5" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEi_s2IrlsGA1TQ-hwIbTgy42xw1ZQ2ONR7SX7-oWA-XsfNBHyouFIB99d_vp0CEUshQ-I6ik4OIk3HX2i-DAQr1ZbJLJ_jZ6uv5gT2OJrz8u9Vc-hWBwNPJIFNbyOv1nvw1jXqke6RS0G5RT6QAYGbuhCApLkND6rfwrLG8nqtOjfJVFM-EMA/w200-h169/QualityAtScale.png" width="5" /></a></div><br /><em><br /></em><p></p><p></p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-35482256575806895522021-09-19T07:35:00.005+10:002022-08-04T10:08:28.460+10:00Open source peer bonuses<p> </p><p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/s512/OSS+BLOG+Peer+Bonus.png" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img alt="open source peer bonus logo" border="0" data-original-height="264" data-original-width="512" height="165" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiTRjnHI18Ovvji8wItJl9wpv5gum4ZgMJxuSpHnT3UzGgkZhQd-8HU35m74JWyJYwSOzNaLSgq1s9Gv2-FObINT8cmqPbovKqickDM7O0z-JVaLmeV2g81W_SjELC4fPtlp59I/w320-h165/OSS+BLOG+Peer+Bonus.png" width="320" /></a></div><br />Congratulations Alyssa, Angelos and Aiden for your <a href="https://www.googblogs.com/announcing-the-latest-open-source-peer-bonus-winners/">Google's Open Source Peer Bonus award</a>. This cool award enables Google employees to recognize and thank a few valued open source contributors. It includes a token financial contribution - enough to take the family out for dinner at a nice restaurant.<p></p><h3 style="text-align: left;">Alyssa Rock</h3><p>Alyssa has played a pivotal role in growing and expanding, <a href="https://thegooddocsproject.dev">The Good Docs Project</a>. She has been doing this by:</p><p></p><ol style="text-align: left;"><li>Being an excellent technical writer, prolifically writing quality material for the project.</li><li>Reaching out at conferences and related events, advocating for the project, and attracting scores of new contributors.</li><li>Pro-actively helping establish a very supportive and inclusive culture, leading by example, being incredibly warm and encouraging in helping to onboard people, and writing our code-of-conduct.</li><li>Stepping up to do much of the grunt work to establish community processes.</li><li>Doing the many other small things that help make an open source project successful.</li></ol><p></p><h3 style="text-align: left;">Angelos Tzotsos</h3><p>Angelos has been a lynch pin contributor to many of the geospatial open source projects. Most notably, he is one of the primary coordinators of the <a href="https://live.osgeo.org">OSGeo-Live</a> linux distribution of open source geospatial software, supporting the 50+ projects represented to get the software up to scratch and compiling on the distribution. He is very competent, always humble, very wise, always supportive of others, and very effective at building open source communities. Notably, he has been voted onto the board of the <a href="https://www.osgeo.org/">Open Source Geospatial Foundation</a>.</p><h3 style="text-align: left;">Aidan Doherty </h3><p>Aidan has been a steady and reliable contributor to <a href="https://thegooddocsproject.dev">The Good Docs Project</a>, taking on core background tasks, like community building (kicking off an unofficial welcoming committee for new members), and setting up a base template working group (from which all of the rest of our project templates will depend.) He takes on the unglamorous but important work which makes an open source project successful.</p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-49963984678044912022021-09-19T05:33:00.001+10:002021-10-24T06:35:01.695+11:00Timeless documentation<p><table cellpadding="0" cellspacing="0" class="tr-caption-container" style="float: right;"><tbody><tr><td style="text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgyq98RbaiwqDFZLUnrdlmBCy7Jq6wzJHl_dNI3Hc6IIdU67HdnorbgHvMhTkG49_Yui4Li9zbyAI8g1cdIX-6x8UDy3grkQnsCFmtgqrbRvKJ8zrPOQnsU0B_5Ht3uLKq6321k/s800/big-ben.jpg" imageanchor="1" style="clear: right; margin-bottom: 1em; margin-left: auto; margin-right: auto;"><img border="0" data-original-height="800" data-original-width="600" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgyq98RbaiwqDFZLUnrdlmBCy7Jq6wzJHl_dNI3Hc6IIdU67HdnorbgHvMhTkG49_Yui4Li9zbyAI8g1cdIX-6x8UDy3grkQnsCFmtgqrbRvKJ8zrPOQnsU0B_5Ht3uLKq6321k/s320/big-ben.jpg" width="240" /></a></td></tr><tr><td class="tr-caption" style="text-align: center;"><a href="https://www.flickr.com/photos/slurm/3885155304/in/photolist-6Vjrjh-ZsKmXz-EbTd4a-caXmuy-27QcUdj-8gA8AQ-NJnhYq-71jap-a4EhJ1-6goMKZ-D5brZh-9eBdQE-25Q7Mq8-G57D1U-AXv58e-23ACR2A-WGKQpT-a4Bs7B-a4EioU-21ZSEit-aVtRHB-9STPDJ-21E8E5r-4ybLgr-b7vHHi-dzaMtL-JsDz7V-Zftu9n-NAdyYs-82YJRV-Rc8Hg5-aWUCTk-7EkcrR-6LV5ht-oGDFyE-uefEd6-6R4Q1y-4wX1u8-f2ojjL-knoUC-221D2ph-29i7CTn-2egHavP-cCHJQN-62xk1s-y7Mh7-ZQDbPt-zdjsy-qWVSU-D7Vvbe">Big Ben clock</a></td></tr></tbody></table><br />Maintaining docs for an evolving software baseline is a constant pain for us technical writers. I'm often helping developers remove time based language from docs, and was surprised that I couldn't find best practices on how to apply this.</p><p>So we've added a <i>timeless documentation</i> section to the Google developer documentation style guide. Timeless documentation is documentation that avoids words and phrases that anchor the documentation to a point in time or assume knowledge of prior or future products and features. So while it is okay to reference "a new feature" in news article; "latest" or "new" shouldn't be used in reference docs. The content becomes outdated soon after publication.</p><p>You can read more about it in the <a href="https://developers.google.com/style/timeless-documentation">Google developer documentation style guide</a>.</p><p><br /></p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-80297792244900987632021-04-20T07:23:00.000+10:002021-04-20T07:23:08.194+10:00Walk your bike into the car park!<p><b><i>TS;DR (Too Sarky; Don't Read)</i></b></p><p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjKvzm29PjB40KOibTyqkgEydHeG04Ub4sTlDmhZJST6VJjkkQlUIXIqwSagVQSnfXL4CO9yKRTOR-qVDG_fL_kWmSQP8bF1W73zis9_23fbFCfrwJWjd0B7rfo30R9ZjQrFmsJ/" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img alt="" data-original-height="1083" data-original-width="812" height="240" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEjKvzm29PjB40KOibTyqkgEydHeG04Ub4sTlDmhZJST6VJjkkQlUIXIqwSagVQSnfXL4CO9yKRTOR-qVDG_fL_kWmSQP8bF1W73zis9_23fbFCfrwJWjd0B7rfo30R9ZjQrFmsJ/" width="180" /></a></div>I've been riding to work for around 30 years, and every year or two you see an email such as this, and it makes me laugh every time.<p></p><p></p><blockquote><p><i>Dear cyclists,</i></p><p><i>For your health and safety, please ensure that you always dismount and walk your bicycle to the car park's bike cage.</i></p><p><i>Thank you and stay safe,</i></p><p><i>Office facilities.</i></p></blockquote><p>So here is my response:</p><p><i></i></p><blockquote><p><i>Dear facilities,</i></p><i>On my ride to work I encounter:<br /></i><ul style="text-align: left;"><li><i>Squeeze points on main roads shared with cyclist killing machines,</i></li><li><i>Stressed and agro peak hour traffic,</i></li><li><i>Super slippery road plate,</i></li><li><i>Unmaintained and destabilizing bike paths,</i></li><li><i>I could go on ...</i></li></ul><i>And in the last 50 metres of my ride, travelling at walking speed into a quiet car park, where the worst that could happen is I might slip on polished concrete and bruise a hip; at that point my employer becomes concerned about my safety and encourages me to walk my bike?<p>(This is not a complaint, or an ask for action. Just an opportunity to share in the humour of the situation.)</p><p>One of your friendly cyclists.</p></i></blockquote><br /><p><i></i></p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-35317664360187514212021-03-08T07:40:00.005+11:002021-03-09T15:29:07.266+11:00Doc templates workshop
<div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhCHJR8jhID9Emu_GlixS0ROL_3gkFTUvAb0iBUWtG3BaqGbqyF3OP0BbYhoC7nC7mtKP0hVhAdLsa7XitXRP1-oWZxsNLF_lEKvvVkjtJbhtocyUwl8XvGrr7vjGWOJn4K4ytr/s5014/boardroom.JPG" style="margin-left: 1em; margin-right: 1em;"><img alt="Team work shopping around a whiteboard" border="0" data-original-height="1563" data-original-width="5014" height="125" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEg7xB_LghPBrf7K5IXai1Xg21GnsZUnkOi0_NZIKWV0EORLA6Oyr5oQT2NsG_5eku8Q0RgS6ZInEyD5v4jeNR-qwqLpjTSygY7C2imWmwFS6dJ41FSbWhZXlDs2S2oi1mJrON1Y/s640/CameronToGroup800x200.jpg" title="Team work shopping" width="400" /></a></div>
<p>
The Good Docs Project is about to run a series of one hour workshops to brainstorm:
</p>
<ul>
<li>What constitutes a good doctype template?
</li><li>How should we capture and present best practices in our <a href="https://github.com/thegooddocsproject/templates/tree/dev/base">base template docs</a>?
</li><li>Which templates should be worked on next?
</li>
</ul>
<h2>When</h2>
<p>We'll start around March 17, 2021. If you’d like to contribute, please vote for your preferred time slot and help us understand how many people will attend: <a href="https://doodle.com/poll/qdy3icnpem5gbme3">Doodle poll</a>.</p>
<p>
Feedback will be used to update our base template, and set the direction for future template development.</p>
<h2>Sessions</h2>
<p>
Pre-reading:
</p>
<ul>
<li>To contribute meaningfully you should read our <a href="https://github.com/thegooddocsproject/templates/tree/dev/base">base template docs</a>, and be ready with questions or suggestions.
</li>
</ul>
<p>
Session 1: Overview
</p>
<ul>
<li>Walk through of our current base doctype template
</li><li>Explain logic behind each section
</li><li>Field questions
</li><li>Identify topics to discuss in future sessions
</li>
</ul>
<p>
Session 2,3: Topic discussions
</p>
<ul>
<li>Deep dive into topics identified in session 1
</li><li>Absorb actions to update the base template
</li><li>Volunteers to test theories by starting to write a template</li></ul>
<h2>Why participate</h2>
<p>
Participate if:
</p>
<ul>
<li>You are keen to help shape best practices in doctype templates.
</li><li>You’d like to adopt a basetype template.
</li><li>You have expertise, bandwidth and commitment.
</li>
</ul>
<h2>Background</h2>
<p>
<strong>To date:</strong>
</p>
<p>
Within The Good Docs Project we are creating best practice templates and writing instructions for documenting open source software.
</p>
<p>
In our first release in 2019, we’ve created <a href="https://github.com/thegooddocsproject/templates/releases/tag/v0.1">0.1 core templates</a>, based on insights from multiple senior tech writers. These are quite good, but in the interim we’ve been improving these templates, building up processes, and refining our thinking about what makes a good template.
</p>
<p>
This has accumulated into our current <a href="https://github.com/thegooddocsproject/templates/tree/dev/base">base template docs</a>. As of March 2021, these docs are draft ready, but untested.
</p>
<p>
<strong>This phase (first half of 2021):</strong>
</p>
<p>
Next we are inviting tech writers to adopt and create a template from our <a href="https://docs.google.com/document/d/1qCqNIdSz_EM37LjNBfLiVdaNCkEuyTfF_RNahA2aLik/edit#heading=h.xq9ybm5gtwu9">prioritized wish-list of templates to write</a>. We will be testing our base template by using it - and we will collect feedback into the base template.
</p>
<p>
Adopting a template is a reasonable commitment, but is achievable for one person to tackle. It involves:
</p>
<ul>
<li>Learning the base template.
</li><li>Researching and documenting best practices in use for your doctype.
<ul>
<li>This typically involves researching business processes and communication theory.
</li>
</ul>
</li><li>Collaboratively refine the template with others.
</li>
</ul>
<p>
We’ll move through stages of:
</p>
<ul>
<li>Nothing -> Something -> Better -> Best
</li>
</ul>
<p>
At the end of this push, we expect to have a more consistent, core set of templates, along with a bunch of lessons to roll into future phases.
</p>
<p>
<strong>Future:</strong>
</p>
<p>
In future:
</p>
<ul>
<li>We’ll refine our templates drawing upon the lessons we’ve learned.
</li><li>We’ll expand the range of templates we cover.</li></ul>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-15287953896238950342021-03-04T23:00:00.039+11:002021-03-19T23:55:49.043+11:00Open Source Documentation Panel - Contributing.today<p> </p><div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/IKoyuPp4fL0" width="320" youtube-src-id="IKoyuPp4fL0"></iframe></div><p><br /></p>I joined a panel at <a href="https://www.contributing.today/march-3-open-source-docs-tools/docs-panel/">Contributing Today</a> talking about open source documentation with:<p></p><ul style="text-align: left;"><li>Scott Riley, product designer <a href="https://www.gitbook.com/">Gitbook</a>, author of <a href="https://mindfuldesign.xyz/">Mindful Design</a></li><li>Lorna Mitchell, developer advocate <a href="https://aiven.io/">Aiven</a>, maintainer <a href="https://pypi.org/project/rst2pdf/">rst2pdf</a></li><li>Jen Weber, web developer and writer at <a href="https://emberjs.com">Ember.js</a></li></ul>Some of the topics we covered:<div><ul style="text-align: left;"><li>What are good docs and exemplars?</li><li>Should different specializations be used for different doc types?</li><li>Where to start learning about being a tech writer?</li><li>How to improve docs for your project?</li><li>Making your open source project attractive for tech writers to join.</li><li>Accessibility.</li><li>Doc strategy, information architecture, processes.</li><li>Gitbook, The Good Docs Project, Season of Docs, rst2pdf.</li></ul><div><br /></div></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-60449141355792419812021-02-06T10:39:00.016+11:002023-03-06T07:31:40.331+11:00Tweak Google's mission?<p>Google has an awesome mission statement:</p><p style="text-align: center;"><i>"To organize the world's information and make it universally accessible and useful."</i></p><p style="text-align: left;"></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhMd5kESA3c7VzBasXx1sIaOvHaFV9q2v7H8DvbwCwxt4Zo26CUCiyUFjBFTBApQkRVlJXB3si2AIkiOxsLz_XBbayL9iBsoLfiY_11vkPp9K4IJE-oKOR3mRXuJujZcNNfpDhQ/" style="margin-left: 1em; margin-right: 1em;"><img alt="Organizing information and making it accessible" data-original-height="790" data-original-width="2377" height="133" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhMd5kESA3c7VzBasXx1sIaOvHaFV9q2v7H8DvbwCwxt4Zo26CUCiyUFjBFTBApQkRVlJXB3si2AIkiOxsLz_XBbayL9iBsoLfiY_11vkPp9K4IJE-oKOR3mRXuJujZcNNfpDhQ/w400-h133/Screenshot+2021-02-06+10.24.25+AM.png" width="400" /></a></div><p></p><p style="text-align: left;">Its hard not to feel inspired by this. What a valuable gift to the world! But I think it could be even better. Because this mission statement only kicks in <b>after</b> ideas have been written down, as “information”.</p><p style="text-align: center;"></p><div class="separator" style="clear: both; text-align: center;"><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiIzx6WWBUCR54uB5oGXoCyiN17fdI6VmPNOWgs5xy5hc6PfN9sZ-nqaUgIsvTclwYyv0VHi2_KZPobB_iAE4sP4hotPd6aT9E9DbgiFjQiEPiY4CMS8WdXbrIkgoTN6fz2Nlbo/" style="margin-left: 1em; margin-right: 1em;"><img alt="Capturing ideas, organizing information and making it accessible" data-original-height="782" data-original-width="2377" height="131" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEiIzx6WWBUCR54uB5oGXoCyiN17fdI6VmPNOWgs5xy5hc6PfN9sZ-nqaUgIsvTclwYyv0VHi2_KZPobB_iAE4sP4hotPd6aT9E9DbgiFjQiEPiY4CMS8WdXbrIkgoTN6fz2Nlbo/w400-h131/Screenshot+2021-02-06+10.24.01+AM.png" width="400" /></a></div></div><div class="separator" style="clear: both; text-align: center;"><br /></div><div class="separator" style="clear: both; text-align: center;"><div class="separator" style="clear: both; text-align: left;"><ul style="text-align: left;"><li>What if we could help capture <b>all</b> good ideas?</li><li>What if we could help everyone to explain their best ideas clearly and concisely, in a form that can be easily shared and understood?</li></ul>This is the mission of <a href="https://thegooddocsproject.dev">The Good Docs Project</a>: </div></div><blockquote style="border: none; margin: 0px 0px 0px 40px; padding: 0px;"><div class="separator" style="clear: both; text-align: center;"><div class="separator" style="clear: both; text-align: left;"><i style="text-align: center;">"Create best practice templates and process for open source software."</i></div></div></blockquote><div class="separator" style="clear: both; text-align: center;"><div class="separator" style="clear: both; text-align: left;"><br /></div><div class="separator" style="clear: both; text-align: left;">If combined, Google’s mission could become even better:</div><div class="separator" style="clear: both; text-align: center;"><i>"Organize all the world's <strike>information</strike> <b><span style="color: red;">ideas</span></b> and make them universally accessible and useful." </i></div></div><blockquote style="border: none; margin: 0px 0px 0px 40px; padding: 0px;"><div style="text-align: right;"><br /></div></blockquote>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-47778943771641180452021-01-01T06:00:00.010+11:002022-01-15T20:29:24.041+11:00Cycle Manly to Frenchs Forest<p>Here is a beautiful ride from Manly to Frenchs Forest using only quiet backstreets, cycle paths, tracks and fire-trails.</p><div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/zEDD2myeUN0" width="320" youtube-src-id="zEDD2myeUN0"></iframe></div><div class="separator" style="clear: both; text-align: center;"><i>Cycle Manly to Frenchs Forest.</i></div><div class="separator" style="clear: both; text-align: center;"><i>Enjoy the journey!</i></div><div style="text-align: left;"><br /></div><p></p>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0Manly Wharf, East Esplanade, Stand C, Manly NSW 2095, Australia-33.799427 151.284561-33.800318555127063 151.28348811631218 -33.79853544487294 151.28563388368781tag:blogger.com,1999:blog-24623504.post-35534632215073993592020-12-03T15:00:00.014+11:002021-01-09T17:01:31.597+11:00State of The Good Docs Project<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/SzScm8W1Ys4" width="320" youtube-src-id="SzScm8W1Ys4"></iframe></div><br /><div><br /></div><div style="text-align: center;"><i>Lightning talk summarizing the status of initiatives within <a href="https://thegooddocsproject.dev">The Good Docs Project</a>.</i></div><div style="text-align: center;"><i>Presented at Write The Docs - Australia and India.</i></div>Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-61068608869115711782020-12-02T21:46:00.007+11:002021-09-25T05:11:09.277+10:00Halfway status - glossary pilot<p><i>
This interim status report outlines achievements, early findings and outstanding tasks for our <a href="http://cameronshorter.blogspot.com/2020/08/cross-domain-management-of-glossaries.html">cross-organizational glossary pilot project</a>.</i></p>
<h2>Pilot Overview</h2>
<p>
Glossaries are easy to set up for simple examples but extremely hard to scale - especially when a project wants to inherit terms from other organizations. This pilot has been set up to test cross-domain management of glossaries. We started in August 2020, and plan to have tested pilot goals by March 2021.
</p>
<p>
We are testing glossary software, standards, and processes, and applying them to cross-organizational use cases within the geospatial mapping domain.
</p>
<p>
For more details, refer to our <a href="http://cameronshorter.blogspot.com/2020/08/cross-domain-management-of-glossaries.html">manifesto</a>.
</p><p><strong>Pilot contributors: </strong>Cameron Shorter, Alyssa Rock, Ankita Tripathi, Naini Khajanchi, Ronald Tse, Reese Plews, Rob Atkinson, Nikos Lambrinos, Erik Stubkjær, Brandon Whitehead, Ilie Codrina Maria, Vaclav Petras</p>
<h2>Current status</h2>
<p>
Our interim status as the start of December 2020 is as follows:
</p>
<table>
<tbody><tr>
<td><strong>Task</strong>
</td>
<td><strong>% Complete</strong>
</td>
</tr>
<tr>
<td><span style="color: #38761d;">Define glossary goals
</span></td>
<td><span style="color: #38761d;">90%
</span></td>
</tr>
<tr>
<td><span style="color: #38761d;">Establish implementation Plan
</span></td>
<td><span style="color: #38761d;">80%
</span></td>
</tr>
<tr>
<td><span style="color: #38761d;">Establish a healthy community
</span></td>
<td><span style="color: #38761d;">70%
</span></td>
</tr>
<tr>
<td><span style="color: #ffa400;">Implement/adopt software platform
</span></td>
<td><span style="color: #ffa400;">70%
</span></td>
</tr>
<tr>
<td><span style="color: #ffa400;">Establish schemas for terms
</span></td>
<td><span style="color: #ffa400;">70%
</span></td>
</tr>
<tr>
<td><span style="color: #ffa400;">Define sentence structure for terms
</span></td>
<td><span style="color: #ffa400;">70%
</span></td>
</tr>
<tr>
<td><span style="color: red;">Connect external glossaries
</span></td>
<td><span style="color: red;">10%
</span></td>
</tr>
<tr>
<td><span style="color: #ffa400;">Collate and clean Open Source Geospatial (OSGeo) terminology
</span></td>
<td><span style="color: #ffa400;">60%
</span></td>
</tr>
<tr>
<td><span style="color: red;">Document template governance processes
</span></td>
<td><span style="color: red;">10%
</span></td>
</tr>
</tbody></table>
<h3>Goals</h3>
<p>
<strong>Task:</strong> Define glossary goals.
</p>
<p>
<em>Understanding the problem is the first step needed to then address it.</em></p><p><em></em></p><div class="separator" style="clear: both; text-align: center;"><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEihj_WbxTW3j1AVLjY-PQk3-6MPVjHrRLvAmu3mnBq1Qq3ZogWYbeIPT5hyeJCBzuZVx9WMJ1pbaoGCHWgxq4i1Mfwy2DxjlqiUmxiNprOCd-sowQh0Qf2w7Xi5dBhCutzBh2NA/" style="margin-left: 1em; margin-right: 1em;"></a><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEihj_WbxTW3j1AVLjY-PQk3-6MPVjHrRLvAmu3mnBq1Qq3ZogWYbeIPT5hyeJCBzuZVx9WMJ1pbaoGCHWgxq4i1Mfwy2DxjlqiUmxiNprOCd-sowQh0Qf2w7Xi5dBhCutzBh2NA/" style="margin-left: 1em; margin-right: 1em;"></a><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgfVMzv870FC8HPz48VIDHIKWYuWyOKv_lizN4Ba9E0vNnCpTQtDn1OCC_SEGSWYti0zo2XrfC-UX1rfBhqBv-0D7LjYkGcQRIobzjsVe650aKC30OYpuRbk_ozDjpBTC-I4HMn/" style="margin-left: 1em; margin-right: 1em;"><img alt="Connected Glossaries" data-original-height="571" data-original-width="860" height="265" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgfVMzv870FC8HPz48VIDHIKWYuWyOKv_lizN4Ba9E0vNnCpTQtDn1OCC_SEGSWYti0zo2XrfC-UX1rfBhqBv-0D7LjYkGcQRIobzjsVe650aKC30OYpuRbk_ozDjpBTC-I4HMn/w400-h265/connected_glossaries.png" width="400" /></a></div></div></div><p></p>
<p></p>
<p style="text-align: center;">
<em>Figure: Connected glossaries, <a href="https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit?pli=1#slide=id.g98573dba11_0_0">source</a></em>
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
We feel we have articulated the problem and associated use cases reasonably well. Refer to the <a href="https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit#heading=h.at9zg5zj7g7">Glossary Pilot Manifesto</a> and accompanying <a href="https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit#slide=id.ga1ec31f923_0_3">presentations</a>.
</li></ul><p></p>
<h3>Implementation plan</h3>
<p>
<strong>Task: </strong>Establish implementation Plan
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
Within the <a href="https://docs.google.com/document/d/1Fjrl34ErnYammel9WmvXJ3rMWFANjoSiiGyyNSYOXUg/edit#heading=h.at9zg5zj7g7">Glossary Pilot Manifesto</a> we articulated steps for standing up a cross-organizational glossary pilot. We have been steadily working against this plan.
</li></ul><p></p>
<h3>Community</h3>
<p>
<strong>Task: </strong>Establish a healthy community:
</p>
<p>
<em>Apache, one of the leading open source foundations <a href="http://theapacheway.com/community-over-code/">prioritizes “community over code”</a>. A strong community will solve any technical challenges faced.</em>
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
We have attracted a motivated, competent, and cross-functional team of 5 to 10 people (depending on how you count), who are steadily working through our backlog of tasks. Collectively we have decades of experience with glossaries, tech writing, standards, software, and the geospatial domain we are initially focusing on.
</li><li>
We have a weekly status meeting, sometimes complemented by additional meetings, along with a slack channel, and email list.
</li></ul><p></p>
<p>
Outstanding:
</p>
<p></p><ul style="text-align: left;"><li>
We have only attracted one of the many OSGeo open source projects to sign up as a pilot. This is likely because we haven’t made the signup process easy enough yet, and our tools and processes need improving.
</li><li>
After completing the pilot and releasing an alpha version, we’d want to scale our community into other domains (beyond our current spatial domain focus).
</li></ul><p></p>
<h3>Glossarist platform</h3>
<p>
<strong>Task:</strong> Implement/adopt software platform
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
We’ve adopted the <a href="https://www.glossarist.org/">glossarist open source software</a> to manage terminology. This provides terminology management of terms, and publishing of terms via a standards based web service.
</li><li>
Ribrose, who develop this software, has been working with us to update the software to address use cases and feedback we are finding during testing.
</li><li>
Extra functionality is expected to be included during the remainder of this pilot.
</li></ul><p></p>
<h3>Schema</h3>
<p>
<strong>Task:</strong> Establish schemas for terms</p><p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgNs4w9NY-6d1PLmE5QBx7cBf20IcZICkHL0ngIstDdzJ7z6I2knhpUf9f2oBLXPaRQkcmvpG1FLZafIA81bWhbQI0dFTRuuUDBlHZL3YMGj1hfjTODK7NvSBQT-PWcQhx61qOZ/" style="margin-left: 1em; margin-right: 1em;"><img alt="Cross Organizational Glossary Schema" data-original-height="664" data-original-width="1062" height="250" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEgNs4w9NY-6d1PLmE5QBx7cBf20IcZICkHL0ngIstDdzJ7z6I2knhpUf9f2oBLXPaRQkcmvpG1FLZafIA81bWhbQI0dFTRuuUDBlHZL3YMGj1hfjTODK7NvSBQT-PWcQhx61qOZ/w400-h250/x_organization_glossary_schema.png" width="400" /></a></div><p></p>
<p></p>
<p style="text-align: center;">
<em>Figure: Glossary schema, sourcing from upstream glossaries, <a href="https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit?pli=1#slide=id.gadd034a666_0_0">source</a></em>
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
We’ve adopted the <a href="https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/">Simple Knowledge Organisation System (SKOS) standard</a> for selecting the fields to use when describing terminology.
</li></ul><p></p>
<h3>Sentence structure</h3>
<p>
<strong>Task:</strong> Define sentence structure for terms.
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
For sentence structure, we’ve adopted <a href="https://www.iso.org/sites/directives/current/part2/index.xhtml#_idTextAnchor206">16.5.6 Definitions, ISO/IEC Directives, Part 2 <br />Principles and rules for the structure and drafting of ISO and IEC documents</a></li><ul><li><em>“The definition shall be written in such a form that it can replace the term in its context. …”</em></li><li>
Example: <em>2.1.17 die: metal block with a shaped orifice through which plastic material is extruded</em></li></ul><li>
While aligning with uses in specific spatial ISO settings, many glossaries use alternative sentence structures, and this is something I’m expecting we’ll need to revisit.
</li></ul><p></p>
<h3>Connect glossaries</h3>
<p>
<strong>Task:</strong> Connect external glossaries
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
In theory, we are very close to connecting two glossaries. In practice, we still need to set this up, which is a focus for the rest of this pilot.
</li></ul><p></p>
<h3>Governance</h3>
<p>
<strong>Task:</strong> Document template governance processes
</p><p></p><div class="separator" style="clear: both; text-align: center;"><a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhbLOhSAUg-3FcrGW49DDA-u2ERxJxZ4l6Co_h-nCdL_i0OkF0K9aTbDAzk98AiIs6vPpZ17c-w_7I_oAK_heQiwyq_GyeXI_LnkPiSzfmx64Fr9HIp4ouYkeN38wY4C6JRVIP8/" style="margin-left: 1em; margin-right: 1em;"><img alt="Glossary governance" data-original-height="556" data-original-width="1319" height="169" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhbLOhSAUg-3FcrGW49DDA-u2ERxJxZ4l6Co_h-nCdL_i0OkF0K9aTbDAzk98AiIs6vPpZ17c-w_7I_oAK_heQiwyq_GyeXI_LnkPiSzfmx64Fr9HIp4ouYkeN38wY4C6JRVIP8/w400-h169/glossary_governance.png" width="400" /></a></div><p></p><p></p>
<p style="text-align: center;">
<em>Figure: Glossary governance, <a href="https://docs.google.com/presentation/d/1WZw1_iAC8uWTqFo335i5h_q8IbEYLqzNRYYWBRNtkd0/edit?pli=1#slide=id.g98573dba11_0_77">source</a></em>
</p>
<p>
<strong>Status:</strong>
</p>
<p>
While we have been discussing and making use of our own unwritten governance process, we are yet to write this down and provide it as template guidance.
</p>
<h3>Spatial use case</h3>
<p>
<strong>Task:</strong> Collate and clean Open Source Geospatial (OSGeo) terminology
</p>
<p>
<strong>Status:</strong>
</p>
<p></p><ul style="text-align: left;"><li>
We’ve collated OSGeo terminology from around ten OSGeo glossaries along with OGC and ISO terms.
</li><li>
These terms have been aligned with writing rules.
</li><li>
We’ve just started looking at terms from the GRASS project, and plan to integrate these too.
</li></ul><p></p>
Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0tag:blogger.com,1999:blog-24623504.post-45585808576445681242020-09-22T12:00:00.005+10:002021-04-14T21:50:36.866+10:00Tech Writing Patterns and Anti-patterns<div class="separator" style="clear: both; text-align: center;"><iframe allowfullscreen="" class="BLOG_video_class" height="266" src="https://www.youtube.com/embed/yiGFbXYyCr0" width="320" youtube-src-id="yiGFbXYyCr0"></iframe></div><div><br /></div>This presentation summarizes a larger <a href="https://docs.google.com/document/d/1Uo3Rcc-rRaN4kmJpqwtUaVRJmDbYI4TkwjuNWNuBu9A">essay of Patterns and Anti-patterns</a> and suggests ways to help solve the associated challenges. It is mostly based on experiences learned within volunteer open source communities. [<a href="https://docs.google.com/presentation/d/1C0yPeymfD2UAY0jmtl_A0jKOM0u26m7FM_chL14L6uQ/">Slides updated 2021-04</a>] <a href="https://docs.google.com/presentation/d/1yFJ2WL-l8O1vnNR67bFfmzHu6tyJjtkJD-cSyH3mNes/">[Original slides]</a>.Cameron Shorterhttp://www.blogger.com/profile/11881171259428356695noreply@blogger.com0