Monday 25 November 2019

Launching TheGoodDocsProject

Discussing templates
What is TheGoodDocsProject?

“Best practice templates and writing instructions for documenting open-source software, 
collated from the best ideas within the documentarian community.”

Incidentally, the templates will be directly applicable for other domains too. So far, we have draft templates for:
  • Overviews
  • Quickstarts
  • References
  • Discussions
  • How-tos
  • Logging
  • References
  • Tutorials
We officially launched our first 0.1 release at the recent WriteTheDocs - Australia conference and were honoured to have ~ 50 documentarians review our templates in a two-hour "fix-it" session.

What next?

  • Over the next few weeks, we will be copying suggestions into our issue tracker.
  • By ~ March 2020, we plan to publish a 0.2 release, incorporating suggestions to date.
  • We hope many documentarians will join us to help improve these templates.
  • And then, with a bit of luck, people will start using the templates.

Highlights from WriteTheDocs - Australia

A bunch of ideas were presented at the WriteTheDocs conference which I'd love to see captured in our templates and shared with others. These included:

Inclusivity

Dave presented an amusing and informative lightning talk using sign language, presented through his (female) interpreter. He started, "You are probably wondering why I sound like a woman? I was born deaf ..." He has since volunteered to add best practice inclusivity into our templates. 
Dave Parker

Including international communities

Alec discussed cross-cultural and cross-language inclusivity, along with challenges and potential solutions. It will be good to see these ideas woven into our templates.
Alec Clews

Empowering writers

Leticia talked in inspiring terms about practical techniques to empower technical writers. I've seen many dis-empowered technical writers and I'd love to see techniques to address this captured and disseminated.
Leticia Mooney

Psychological safety

Riona challenged conventional thinking about open source communities. She discussed technical and social barriers to technical fields, and linked psychological safety, knowledge sharing and good documentation to building more egalitarian societies.
Riona MacNamara

Information architecture

Elle discussed building information architectures, and avoiding social and technical biases. We have only scratched the surface of this topic in TheGoodDocsProject and more expertise is required.
Elle Geraghty

Storytelling

Jon and Tim wove a compelling tag-team story about narrative in game design. If we can get technical writing to be as interesting as this, readers will absorb information more effectively.
Jon Manning and Tim Nugent

Tech Writing Workshop

Sarah presented Google's internal Tech Writing 101 workshop for Developers, which Google plan to share publicly. It will be great to harmonise this with TheGoodDocsProject.
Sarah Maddox

Release Notes

Alex drew inspiration from horror stories when explaining best practices for release notes. This is worth watching, just for entertainment value - but we should also be capturing these insights into our templates.

Alex Koren

The pitch

Mat recorded a post-conference talk about harnessing the post-conference arfterglow (password: WTD2019). At the conference, he was leading conversations about building a business case for us all to take back to organisations explaining the value we all gain by collaboratively sharing and maintaining templates, including:
  • Training users to become familiar with standard documentation patterns.
  • Reducing ramp-up time for documentarians.
  • Supporting cross-domain expertise.
Mat Walker

What next for you?

Are you inspired? Want to help writers become more effective, and by extension, help share the world's knowledge? Come introduce yourself to the rest of us at TheGoodDocsProject.


Saturday 23 November 2019

Starting an OSGeo Lexicon Committee


Related image

Disparate glossaries of geospatial terms are spread across OSGeo projects, OSGeo communities, the OGC and ISO TC211 standards organisations. Making sense of and managing these terms is messy. So this week we have initiated an OSGeo Lexicon Committee with goals of:
  • Managing OSGeo related terminology, 
  • Setting up and applying best practices, 
  • Providing glossaries for publishing to various OSGeo projects and communities, 
  • Facilitating translations between terms,
  • Coordinating with OGC and ISO TC 211 standards communities.
Does this interest you? Check out our wiki page or contribute to discussions on our email list.

Monday 11 November 2019

TheGoodDocsProject Fixit workshop

Are you coming to the Write the Docs conference in Sydney, Australia, 14 and 15 November? If so, I hope you will feel inspired to join our GoodDocsProject FixIt workshop.

We started TheGoodDocsProject to create best-practice templates and writing instructions for documenting open-source software. With our alpha release, we’ve created some common templates which we’d love people to test, break and improve.

Topics:
Diverse contributions encourage. We hope to cover:

  • As a user or developer or writer: Try writing instructions for your favourite application based on one of our templates. Give us feedback.
  • As a technical writer or information architect: Review one of our templates, try and find limitations, suggest modifications, offer sections to add, debate improvements.
  • You have another idea: Let’s hear it.

Schedule:

  • 5 min: Introduction.
  • 30 min: Break out into groups brainstorming topic.
  • 15 min: groups present back to everyone.
  • 30 min: Break out2.
  • 15 min: Groups present2.
  • 5 min: wrapup and thanks

Logistics:


Post Fixit:


Who are we:

  • Cameron Shorter, Business Analyst by day, Open Source Developer and accidental Technical Writer by night.
  • Jared Morgan, Senior Technical Writer at Squiz
  • Erin McKean, Docs Advocacy Program Manager at Google
  • Felicity Brand (attending remotely), Technical Writer for Google Season of Docs
  • Sanket Totewar, Technical Writer and a few more things
  • Others from TheGoodDocsProject

    Saturday 2 November 2019

    Scrappy Collaboration

    Coordinate changes over time due to tectonic plate movement.
    Confession: We broke government conventions, worked beyond our agency’s mandate, attended an international technical committee meeting on personal time, uncovered significant negative impacts for unsuspecting users in Australia’s multi-million dollar mapping program, and retrospectively received glowing praise and thanks.

    Welcome to “scrappy collaboration”.

    $225 million has been committed to improving Australia’s GPS positioning tenfold, to 5cm accuracy. However technical shortcuts previously embedded in web-mapping software, which ignore tectonic plate movements, are causing meter level map misalignments in web-mapping! This is an international problem which is being exposed by Australia’s advanced mapping program. Needless to say, misaligned maps are confusing for users and unacceptable for Australian mapping agencies.

    When NSW Spatial Services discovered the project risks involved, and the minimal existing focus on the problem, we joined other Australian states, and worked beyond our agency’s mandate, to look for a solution.

    An interrelated problem cluster
    With investigation, we unravelled a cluster of interrelated problems:
    • Some of which had deep technical challenges;
    • With varying implications to diverse user groups and use cases;
    • Which were difficult to understand and explain;
    • With experts regularly talking past each other, each considering a different part of the problem;
    • With multiple holistic strategies possible (each strategy offering significantly different costs and benefits for each stakeholder group);
    • With high impact implications for software, data and users;
    • Requiring national and international collaboration between diverse stakeholders to resolve effectively.
    Not my responsibility
    The investigation turned out to be a significant time sink, distracting us from our core roles. If following a government playbook, we should have left the responsibility to others: Our software vendor, international standards foundations, national mapping organisations, ...

    But we knew we had a moral obligation to step up. Our team understood the overarching problem; had access to geodetic surveyors and software engineers; and had personal connections with international experts and influencers from open-source and standards communities.

    A scrappy approach
    A complex, interdependent problem cluster has a high barrier to entry. Each stakeholder only understands and can influence a subset of the issues. No one has a business case to solve the greater problem for everyone. This is difficult to solve with traditional top-down management approaches.
    Instead, we adopted a scrappy, very personal approach, trading our time, and collected knowledge with collaborators to achieve common goals.
    • We very publicly admitted the embarrassing problems we were facing in technical forums, and asked for help.
    • We shamelessly drew down favours from our friends in open source communities, government agencies, industry and standards organisations.
    • We spent extra effort coordinating contributions, answering questions, and addressing related problems relevant to our collaborators (because that is what friends do).
    • We concisely compiled descriptions of the problems, along with suggested solutions.
    • Joel Haasdyk, our datum modernisation manager and geodetic surveyor, then used personal leave to travel halfway around the world to present recommendations to the standards technical committee. 
    When collaborating, we applied many of the hallmark characteristics prevalent in open source communities:
    • Respect the time of your collaborators; be concise in messaging.
    • Lead by example; put in the hard work.
    • Reach out to people; be vulnerable and ask for help.
    • Be clear about what you need and from whom.
    • Care about your collaborators; help solve their problems too.
    Tap into your humanity - it has tangible business benefits.

    Impact
    The impact we achieved with collaborators was apparent from the reports coming from the standards community. Scott Simmons, Executive Director of the OGC Standards Program reported:
    “I don’t know if I have ever seen a better and more compelling tag-team describe and lead discussion on a topic than Joel and Roger's presentation on the time-dependent limitations inherent in most OGC spatial standards. I received many emails and face-to-face comments from attendees afterwards stating that it was so valuable to understand the problem and see that there is a solution. Resulting from the presentation, the majority of OGC Standards Working Groups now understand the necessity to update their standards to account for time-dependence of coordinates, with some already initiating updates.”
    Future standards development will consider tectonic plate movement and will start to address Australia’s map misalignment problems impacting our datum modernisation program. We are at the start of the journey, there is still plenty more to do, but we now are heading in the right direction.

    Counterintuitive solution
    So, when faced with complex problems, consider expanding scope rather than constraining it. Consider solving the problems of others as well as your own. Attract the collective wisdom and resources of collaborators and you'll likely find your solutions are more impactful, strategic and sustainable.

    About the author
    Cameron Shorter has been a Geospatial Business Analyst at NSW Spatial Services.