Blog - Posts tagged communityhttps://www.writethedocs.org/blog/archive/tag/community/atom.xml2019-02-11T00:00:00ZABlogImproved Community Code of Conducthttps://www.writethedocs.org/blog/new-community-coc-2019/2019-02-11T00:00:00Z2019-02-11T00:00:00ZWrite the Docs Team<div class="section" id="improved-community-code-of-conduct">
<p>We aim to make Write the Docs an incredibly diverse, friendly, and inclusive community. As part of that effort, we have a community <a class="reference internal" href="../../../../code-of-conduct/"><span class="doc">Code of Conduct</span></a>. We have refactored and improved our existing Code of Conduct, based on improvements and lessons in our own and other communities. In this post, we list some of the more significant changes.</p>
<p>We have added:</p>
<ul class="simple">
<li>An explanation of the fundamental goals we have with a CoC.</li>
<li>Clarification on cases where the CoC can apply during conferences, even for events not on the conference agenda.</li>
<li>A short guideline on reporting. Community members are now more strongly encouraged to report incidents, even if they are unsure whether it is a violation or not. This is also reflected in the CoC in other places.</li>
<li>Clarification on who to report to in which spaces, how a report can be escalated, and which people are in which response team.</li>
<li>An explicit policy regarding venue security or law enforcement involvement. They should not be involved without consent of the affected person(s), except if there is no other reasonable option given significant safety risks.</li>
</ul>
<p>We’ve updated:</p>
<ul class="simple">
<li>The list of examples of harassment and exclusionary behaviour, to provide more clarity on what can fall under this.</li>
<li>The <a class="reference internal" href="../../../../code-of-conduct-response/"><span class="doc">Code of Conduct Response Guide</span></a> to provide better guidance to people in CoC response teams in different community spaces, how to work as a team, deal with conflicts of interest, handling public statements, and how to decide on a response.</li>
</ul>
<p>All Write the Docs meetups are now required to adopt the Write the Docs community <a class="reference internal" href="../../../../code-of-conduct/"><span class="doc">Code of Conduct</span></a>. A <a class="reference internal" href="../../../../code-of-conduct-shortform-meetups/"><span class="doc">short form CoC is available for meetups</span></a>, which needs to be included in the Meetup description in full. Organisers are the first point of contact for reports of Code of Conduct incidents at meetups, should read the <a class="reference internal" href="../../../../code-of-conduct-response/"><span class="doc">Code of Conduct Response Guide</span></a> carefully, and use it as a reference when an incident is reported.</p>
<p>Please take a moment to review the <a class="reference internal" href="../../../../code-of-conduct/"><span class="doc">Code of Conduct</span></a>. As with any of our community documentation, we welcome feedback and contributions. We’d also like to thank the <a class="reference external" href="https://2018.djangocon.eu/conduct-response/">Djangocon Europe 2018 team</a> for inspiring a large portion of our updated code of conduct.</p>
<p>If you have any questions about these changes or CoC processes in general, feel free to contact <a class="reference external" href="mailto:conduct%40writethedocs.org">conduct<span>@</span>writethedocs<span>.</span>org</a>.</p>
</div>
Write the Docs Newsletter - March 2017https://www.writethedocs.org/blog/newsletter-march-2017/2017-03-14T00:00:00Z2017-03-14T00:00:00ZWrite the Docs Team<div class="section" id="write-the-docs-newsletter-march-2017">
<div class="section" id="winter-is-coming-to-an-end">
<h2>Winter is coming – to an end!</h2>
<p>Hello, Write the Docs! Obviously, the end of the cold season depends entirely on what coast (or continent) you’re on, but here in the western US, we’re rapidly approaching springtime – which means Write the Docs North America is right around the corner!</p>
<p>This month’s newsletter is a little behind schedule (apologies!) because we were holding out so we could include details about this year’s awesome speaker lineup for North America! We’re also excited to announce ticket sales for the EU conference, as well as an updated version of our community Code of Conduct (more details on both, at the end of the newsletter). It’s been a big month for WtD events!</p>
<p>We’ve also had one of our most active months on the community Slack channel! We’ve cleared 1500 members, and we’re to the point where there’s almost always something going on, pretty much 24/7. Thanks to all of you for making this community so engaged and lively!</p>
<p>As a result, we’ve got another great issue for you, packed with distilled conversations from around the Slack-iverse. Hope you find something to intrigue or inspire!</p>
</div>
<div class="section" id="north-america-conference-speakers-announced">
<h2>North America conference speakers announced!</h2>
<p>In the last few weeks, the conference organizers have been faced with the hardest part of their jobs: selecting fewer than 20 talks from the 100+ submissions that came in. The quality of the proposals this year was incredible. To everyone who submitted a proposal – THANK YOU. We wouldn’t have a conference without your passion and hard work.</p>
<p>We’re really excited about the lineup we’ll be bringing to the Crystal Ballroom stage in May. Topics range information architecture in API documentation to injecting empathy into your error messages, from writing docs at a startup to using game design techniques to manage interpersonal conflicts in your teams. You can read more about the full talk lineup here: <a class="reference external" href="https://www.writethedocs.org/conf/na/2017/news/announcing-presentations/">https://www.writethedocs.org/conf/na/2017/news/announcing-presentations/</a></p>
</div>
<div class="section" id="know-the-rules-for-formatting-procedures-and-when-to-break-them">
<h2>Know the rules for formatting procedures – and when to break them</h2>
<p>An interesting question came up this month about how to introduce a procedure, i.e., a list of numbered steps. Some style guides (ahem, <em>IBM</em>) require writers to use a lead-in sentence, a heading that includes the word “Procedure,” or some combination of the two. The question was: Are there good reasons to disobey this rule? The community’s answer: Yes!</p>
<p>One person mentioned that adding “Procedure for” to the beginning of every heading makes documents harder for readers to scan. Another pointed out that headings and lead-in sentences are often redundant and said they’ve successfully used brief, descriptive headings with no lead-in when formatting procedures.</p>
<p>Others felt that it’s important to have a short description immediately after the heading to provide context and help readers understand the what and why of the procedure. This format eliminates redundancy between headings and lead-in sentences and avoids the sparse tone of going straight from the heading into a list of numbered steps.</p>
<p>Overall, folks agreed that the format that uses the fewest extra words and helps readers find the information they need is the best format.</p>
</div>
<div class="section" id="should-documentation-have-bylines">
<h2>Should documentation have bylines?</h2>
<p>A lively discussion about bylines in technical documentation showed up in the #watercooler channel this month, with some documentarians shuddering at the thought and others seeing it as appropriate acknowledgment. Some folks saw lack of bylines as a sign of corporate appropriation (for legal or intellectual property reasons), while others saw it as recognition that tech docs are often highly collaborative and therefore difficult to attribute to a single author. Still others saw bylines as an opportunity to encourage personal interaction with customers, while yet another group saw that same interaction as intrusive.</p>
<p>Overall it seems that attitudes toward bylines really depend on context – as any good doc issue should! Bylines can help create a sense of community in developer docs, for example, or for community-driven projects, while for enterprise-scale doc sets they can be less appropriate. And book authors are in a category of their own, authorship being something that’s far less often repudiated or denied – after all, we have at least two noted authors of software books among us, both of whom helped dispel some common assumptions about the fame and fortune that accrue to book deals in the real world.</p>
</div>
<div class="section" id="resources-and-best-practices-for-alt-text">
<h2>Resources and best practices for alt text</h2>
<p>Ensuring the accessibility of our content is at once super-important and a perennial challenge. Adding alt text for the visual aspects of our documentation is a good place to start. A request for some resources for crafting alt text arose this month, and there were some useful responses that we thought were worth sharing.</p>
<p>As a rule of thumb, this what one member of the community suggested, when considering what to put in your alt text: “Ask yourself what someone would need to know if they couldn’t see the image.” For more detailed guidance, there were a few links that floated to the surface:</p>
<ul class="simple">
<li>Run by Utah State University’s Center for Persons with Disabilities, WebAIM is a non-profit devoted to promoting accessibility on the web. Their guidelines are a great place to start: <a class="reference external" href="http://webaim.org/techniques/alttext/">http://webaim.org/techniques/alttext/</a></li>
<li>The W3C guidelines go into quite a lot of detail about how to provide alt text, and include lots of links for additional context: <a class="reference external" href="https://www.w3.org/TR/WCAG10/#gl-provide-equivalents">https://www.w3.org/TR/WCAG10/#gl-provide-equivalents</a></li>
<li>Written and periodically updated since the late ’90s, this page has a veritable treatise of thoughts and guidelines for creating alt text: <a class="reference external" href="http://www.cs.tut.fi/~jkorpela/html/alt.html">http://www.cs.tut.fi/~jkorpela/html/alt.html</a></li>
</ul>
</div>
<div class="section" id="studies-in-comparative-job-titles">
<h2>Studies in comparative job titles</h2>
<p>Every once a while, discussion in the WtD Slack turns to titles…job titles, that is. This month, some of us shared our actual job titles and some dream job titles.</p>
<p>Actual titles included:</p>
<ul class="simple">
<li>Information Coordinator</li>
<li>Self-Service Content Manager</li>
<li>Manager, Docs and Community</li>
<li>Word Writin’ Guy (yep, it was on his business card!)</li>
</ul>
<p>Dream titles ranged from meaningful to fanciful:</p>
<ul class="simple">
<li>User Docs Lead or Dev Docs Lead</li>
<li>Knowledge Management Coordinator</li>
<li>Verbiage Engineer</li>
<li>Prose Technician</li>
<li>Word Scientist</li>
<li>Lord High Admiral of User Documentation</li>
</ul>
<p>Some folks pointed out that all the variation in documentarian job titles makes it hard to figure out who does what. And the standard “Technical Writer” seems to get more hits on LinkedIn. Still, who wouldn’t want to be The White Wizard of Help? As one person pointed out, Gandalf insisted on reading the documentation!</p>
</div>
<div class="section" id="other-exciting-community-developments">
<h2>Other exciting community developments</h2>
<p>As we mentioned up top, there’s been a ton of exciting developments across the community this month. Here’s the details on a few of them:</p>
<ul class="simple">
<li><strong>EU conference announced</strong> – We’ve gone live with dates and ticket sales for the EU conference, coming up Sept 10-12, 2017, in Prague, Czech Republic: <a class="reference external" href="https://www.writethedocs.org/conf/eu/2017/news/announcing-website-tickets/">https://www.writethedocs.org/conf/eu/2017/news/announcing-website-tickets/</a></li>
<li><strong>Updated Code of Conduct</strong> – Our board of directors took some time to update and refresh our community code of conduct, which we take very seriously. It’s one of our best tools for ensuring that our community is inclusive, welcoming, and safe for all its members. Take a look, when you get a chance: <a class="reference external" href="https://www.writethedocs.org/blog/new-community-coc/">https://www.writethedocs.org/blog/new-community-coc/</a></li>
<li><strong>New episode of the Write the Docs podcast</strong> – In case you missed it, the latest episode of the Write the Docs Podcast went live last week. You can have a listen here: <a class="reference external" href="http://podcast.writethedocs.org/2017/03/05/episode-4-continuous-integration-and-docs-like-code/">http://podcast.writethedocs.org/2017/03/05/episode-4-continuous-integration-and-docs-like-code/</a></li>
<li><strong>WtD Meetup organizers are building a speaker pool</strong> – With Write the Docs Meetups now happening regularly, clear across the world, our intrepid organizers are often on the hunt for Meetup speakers. If you’re interested in putting your name in the hat (whether you’re an experienced speaker or not), head over to our google form to share your details with our Meetup organizers: <a class="reference external" href="https://goo.gl/forms/IGdEJCg227JDginY2">https://goo.gl/forms/IGdEJCg227JDginY2</a></li>
</ul>
<p>Thanks for reading, and see you again next month!</p>
</div>
</div>
New and Improved Community Code of Conducthttps://www.writethedocs.org/blog/new-community-coc/2017-02-22T00:00:00Z2017-02-22T00:00:00ZWrite the Docs Team<div class="section" id="new-and-improved-community-code-of-conduct">
<p>Greetings documentarians! As you know, Write the Docs is an incredibly diverse, friendly, and inclusive community. We continually encourage and support safe spaces in our events and online platforms.</p>
<p>To that effect, we recently refactored and expanded our <a class="reference internal" href="../../../../code-of-conduct/"><span class="doc">Code of Conduct</span></a> to accommodate for the increased interaction that our community members have with each other and with folks outside our community when communicating on behalf of Write the Docs.</p>
<p>This updated code of conduct aims not only to deliver a more accurate definition of the principles which we believe in, but also to establish which spaces are considered official community spaces, what might be considered a violation, and what to do in case you need to report a violation.</p>
<p>In addition to the expanded code of conduct, we included a reporting guide with guidelines on how to submit a report and what to expect after submitting a report.</p>
<p>And lastly, we refactored our <a class="reference internal" href="../../../../code-of-conduct-response/"><span class="doc">Code of Conduct Response Guide</span></a> to cover handling reports in all of our community spaces, and to make sure that we follow a consistent and transparent approach in handling these reports.</p>
<p>Please take a moment to review the <a class="reference internal" href="../../../../code-of-conduct/"><span class="doc">Code of Conduct</span></a>. As with any of our community documentation, we welcome feedback and contributions. We’d also like to thank the <a class="reference external" href="https://www.djangoproject.com/conduct/">Django Project Code of Conduct</a> for inspiring a large portion of our updated code of conduct.</p>
<p>And remember - Be excellent to each other!</p>
</div>