Thursday, 4 April 2019

Amplifying Google's Season of Docs

Google has initiated a Season of Docs collaborative program aimed at improving open source documentation. It provides a great opportunity for us involved in open source and documentation to focus on big communication challenges.

Challenges

  • Vision: Does everyone know the characteristics of good open source documentation? Does anyone know? Let’s collate research and best practices into accessible guides and templates.
  • Targetted: Projects have a range of audiences with differing technical backgrounds, attention spans and information needs. A range of documentation types are needed. Each requires different levels of depth, specificity, currency, narrative, personalisation, examples, and more.
  • Empower everyone to contribute: Good documentation benefits from cross-disciplinary contributions: from developers, users, domain experts, teachers, technical writers, graphic artists, and translators. Ramp-up time is high for any group attempting to learn another’s skill-set. Open source documentation processes are typically set up by developers, for developers, and have a significant barrier-to-entry for others. How can we fix that?
  • Attract volunteers: How can we apply our knowledge of collaborative and volunteer communities to attract documentation teams? How can we help volunteers maximise the impact and effectiveness of their contributions?
  • Current and Sustainable: How can we sustainably keep documentation synchronised with rapidly evolving software? How do we help users find current material and archive outdated docs? How do we minimise maintenance?

What to focus on?

To maximise value, I suggest promoting initiatives which:
  • Use and contribute to documentation best practices.
  • Use templates and guides for key documentation types to help cross-domain collaboration.
  • Attracts volunteers, from multiple user profiles.
  • Applies multi-directional mentoring.
  • Refines workflows and tools to reduce barriers-to-entry.
  • Focuses on a specific initiative which tests the bounds of these ideas for a specific project and captures lessons learned.
This might involve:
  • Auditing existing documentation.
  • Defining a writing strategy.
  • Developing or refining a specific documentation type for a project.
  • Mentoring a project’s community, increasing the initiative's sustainability.
  • Contributing to best practices.
If we can achieve this:
  • Writer contribution impact will be maximised,
  • Community writing will become more effective,
  • And documentation maintenance will become more sustainable.

Further Reading

General:
Documentation Strategy:
Research into building open source communities:
Geospatial open source:

Tuesday, 12 March 2019

Google Season of Docs Announced

Google has just launched a Season of Docs program, designed to bring open source and technical writer communities together, to the benefit of both. Awesome! I reckon our OSGeo projects should get involved, and I'm personally keen to be part of it. Anyone else want to join me?

Sunday, 3 March 2019

Starting build cycle for OSGeoLive 13.0

Are you interested in joining our Open Source GIS experience? The build cycle for the next OSGeoLive release 13.0, is going to start. The final version is planned to be ready on 30th July 2019 in time for FOSS4G 2019 in Bucharest. Have a look at our schedule for the detailed steps.
Till then we have many challenges - from simple to challenging, to help describe and train people in the value of Open Source GIS.
For this release, we hope to help OSGeo Community projects join OSGeoLive, and work out how we can keep within our size constraints.
We'd love to build a cloud version of OSGeoLive for this release. It would make OSGeoLive, and OSGeo software much more accessible. It seems elusively achievable, but we haven't worked it out yet. If you think you could help, we'd love to hear from you.

Get involved

Are you a programmer or packager with experience in one of the Open Source GIS applications. Are you a technical writer interested in making FOSS4G accessible to all? Are you interested in helping update translations to latest documents on Transifex.

Contact us

If you would like to add a new project, help us to get in the cloud or have another goal you would like to work on and get involved you are very welcome.

Please join the OSGeoLive mailing list or meet us on IRC at our weekly meeting.

About OSGeoLive

OSGeoLive is a ​Lubuntu based distribution of Geospatial Open Source Software, available via a Live DVD, Virtual Machine and USB. You can use OSGeoLive to try a wide variety of open source geospatial software without installing anything.


Friday, 22 February 2019

Inspiring techies to become great writers

How to attract writers into Open Source communities, have them amplify developers' written impact, reduce tech ramp-up, facilitate growth, while having fun improving the world.

Reading time: 8 minutes

Presented at Write The Docs - Sydney [slides]

My story starts at the international conference for Free and Open Source Software for Geospatial when it was held here in Sydney, ten years ago. We wanted to build a distribution of the software to hand out to conference attendees. Back then when software was expensive to download, it was a useful handout, and it provided an attractive marketing pipeline for these free software projects.

To build the first version of OSGeoLive we followed install instructions, configured applications, resolved dependencies and conflicts, asked questions on email lists, and finally, after much hard work, produced our first release. This was a very important first step as it showed that we had the commitment to follow through and deliver.
Install Script
However, it also highlighted many of our failings. We had followed a fully manual install process, so when the next software releases came out, we had to start the installation process again, from scratch. It was completely unsustainable. We needed to automate the install process, and we needed projects to show us how.
But our first calls for help were embarrassingly underwhelming. You see, the perceived learning curve for packaging was considered unacceptably high and volunteers were not stepping up.
To fix this, we wrote an example install script along with clear, step-by-step instructions. We then went back to developers with the message of "if you can spend a couple of hours writing a short install script which looks like this, then we will market your application through our OSGeoLive distribution". Small effort / High Value. And it worked! 28 projects packaged their applications for our version 2 release.
Using a document template
In following releases, we applied the same process to documentation. Our first docs were written by developers and as such were quite ... variable. So we created skeleton outlines for Project Overviews and Quickstarts, along with clear writing instructions. We then asked projects to write documentation in line with these outlines. We followed up with reviews, and a publishing pipeline, to produce consistent, quality material. So by applying an outline / write / review / publish process, we were able to achieve significant efficiencies by allowing experts to focus only on the bits they do best and thus reduce contribution effort.
Translators later adopted the same formula to create multiple language variants.

Unpacking the story

Ok, let’s unpack this story from the perspective of technical writers. Firstly, we should acknowledge the significant efficiencies software enables. Four out of the ten richest people in the world are self-made software entrepreneurs.
However, while proprietary businesses centralise captured wealth, open source software, like other creative commons works, is given away for free. This act of sharing has far-reaching consequences. Tools and knowledge created can be used and built upon by everyone. This democratises knowledge, wealth and power.
So if you want to positively improve our world, supporting Open Source projects is a good place to start.

The Research

So what makes a successful Open Source project; one which is sustained in the long term? Research provides some answers, An analysis of over 170,000 Open Source projects to identify success factors, and a study of the success factors of episodic volunteering in Open Source both highlight the importance of:
  • Clear utility,
  • Lean governance,
  • Clear vision and goals,
  • Marketing and a quality website,
  • Good user and developer documentation,
  • Digestible information,
  • Guided introductions,
  • Simple workspaces,
  • Task–finding dashboards,
  • Financial backing,
  • Fine-scaled task granularity, making it easier for people to contribute.
And on the social side:
  • Leaders who lead by doing, by putting in the hard work,
  • A virtuous and supportive community,
  • Attracting external contributors,
  • Advocating broadly, by all involved,
  • A sense of collective ownership,
  • Hosting of meetups,
  • Recognising all forms of contribution,
  • Personal invitations for help,
  • Showing appreciation.
Notice the prevalence of communication within these characteristics?

Communicators Needed

Communicators helping the world
Where I’m heading here is that while the Open Source story usually focuses on software developers, equally important are communicators and community builders. So for you folks who are technical writers, Open Source communities need you! Your involvement can significantly amplify a project’s impact, and by extension, your help will be:
  • Making the world more egalitarian,
  • Reducing wealth inequality,
  • And democratising knowledge and power.

Bridging the tech gap

I’d like to touch on inflection points. As a project’s technology and user base matures, community success factors move. An early inflection point with Open Source projects happens when a project attracts external contributors. These contributors increase the size of the workforce and add extra skills, but they lack the deep domain expertise of the core team.
To attract contributors, projects should reduce ramp-up time; and good documentation is key. Poetically, the documenters who are most qualified to help are typically the least technical, and face the greatest ramp-up time.
Johanna Botman
To help explain this problem, I’d like to introduce you to Johanna Botman. She started her working career as an English teacher, then moved into IT, website design, and is now a geospatial officer in local council. I met her at a spatial conference’s community day when she joined other volunteers in updating our OSGeoLive documentation. It was a humbling experience for me. I saw such an accomplished person, with oodles of commitment, struggling to use our documentation tools.
Johanna reviewed an early draft of this presentation and observed that ...
Some of the issues relating to getting started are about bridging the gap between developers and writers. Developers write code in coding tools. They collaborate, they are used to versioning and are at home with unformatted raw text and automation tools. Writers? They work on Windows machines in Word – maybe in Google Docs if they are lucky. They don’t know about running build scripts, running Linux variants, Github, chat programs, HTML, RST, Wikis and the variants of markup languages.
It’s one thing to work with the Open Source software, another to write about it, and a third thing to work out how to write it so that it fits in with the project. It seems as if the developers have created the writing system in a way that they are used to working, not necessarily in a way that works for writers.
And I think Johanna is right. I’ve found many users and writers who are keen to help but feel overwhelmed, don’t know where to start, don’t want to burden the existing community, and so are shy to ask questions.
Writers need to be sought out, welcomed, encouraged, supported and publicly appreciated if projects are to attract good documenters to help them grow.
In turn, I’d encourage writers to proactively reach out to development communities. I’d expect you’ll find them very welcoming and appreciative, especially if you are volunteering to tackle key documentation pain points. And together we need to help bridge the gap between writers and developers.

Documentation Strategy

So what should writers expect to see when joining a project. Typically, emerging projects have patchy documentation, in various stages of currency, completion, relevance, verbosity, and quality. The challenge is to consolidate it so that it becomes concise, intuitive, accurate, minimises learning and ramp up time, and sustainably maintained to match continually evolving software releases. This is non-trivial and requires good writing skills, planning, leadership, commitment and follow through to do it well.
The problems are that:
  • Software is complex. It’s hard to understand, and harder to explain.
  • Software continually evolves, meaning documentation needs to be continually maintained.
  • Projects have a range of audiences, with differing information needs, technical backgrounds, and attention spans.
Daniele Procida provides valuable advice in an article titled:  What nobody tells you about documentation.
Document structures recommended in What nobody tells you about documentation.
Daniele is an open source developer, technical writer and teacher and he explains that:
There is a secret that needs to be understood in order to write good software documentation: there isn’t one thing called documentation, there are four. They are: 
  • Tutorials, 
  • How-to guides, 
  • Explanations and 
  • Technical references. 
They represent four different purposes or functions, and require four different approaches to their creation. Understanding the implications of this will help improve most software documentation - often immensely.
Daniele is on the right track although I feel his list should be expanded to include other forums.
Placing documentation types
Raw image (in draw.io format)

Writers should identify and define the characteristics of their communication mediums.
The front web page and elevator pitch should be concise, highly polished and target first-time visitors, while community forums are good for once off questions and can be rough around the edges.
For each medium, define:
  • Target audience,
  • Document structure,
  • Technical depth,
  • Quality requirements, and
  • Maintenance strategy.
Then aim to:
  • Write timeless material to minimise maintenance.
  • Only write as much as your team has the capacity to maintain.
  • Help techies become great writers. Provide skeleton docs and writing instructions, then review, mentor and publish.
  • Work within a release cycle, which ideally synchronises with the project.
It’s worth noting that most of what I’m talking about here is relevant to all sorts of technical writing - not just for Open Source communities.

Getting Started?

Tech Writer Heros
Image source
Okay, so maybe you’d like to get involved and are wondering where to start? I’d suggest:
  • Focus on one project instead of many, as your ramp-up time will likely be high.
  • Acknowledge the value you bring. Use it as motivation because you’ll have many challenges and the inner motivation will really help.
  • Demonstrate commitment. It’s contagious.
  • Ask for help, you will need it, and you’ll likely be surprised how supportive people will be.
  • Don’t be daunted by your lack of domain knowledge. It’s actually an asset when writing to a broad audience.
  • Help developers become great writers. Great impact comes from amplifying the effectiveness of others.
  • Be part of the team; help paint the vision; be inspirational.
  • And most of all, have fun while you are doing it. Because believe you me, it is hugely rewarding to share the team camaraderie involved in building something that is much bigger and more impactful than you could possibly create by yourself.

    Sunday, 20 January 2019

    Toward a universal Style Manual

    The Australian Digital Transformation Agency plan to improve the Australia Government's writing style manual. Great. Can I help?

    Worst user, best friend

    I'll be your most demanding user. I'm technical, have no writing training and won't want to read the manual. And yet, this manual should be written for me. Why? Because people like me write policies, code, manuals, business cases, standards, designs,  requirements, tutorials. We write for government, industry, open source and international organisations.

    Writers shouldn't read your manual

    Auto-correctors fix spelling and grammar; templates help writers with headings and writing tips. The best way to reach us technical writers is to embed style guidance into these tools and templates. (Could you please also fix their formatting bugs, which seem to be in every word template I've ever used.) 

    Go universal

    Please avoid the temptation to create an Australian specific Style Manual. The inevitable inefficiencies caused by integrating local and international style variants will be painful. Draw inspiration from the Creative Commons licenses. They are internationally recognised, widely used and widely understood.  

    Collaborate

    Collaboration mitigates against being out-innovated, as in the digital economy, collaboration out competes competition. There are more smart people in the rest of the world, thinking about your problem, than can ever be mustered in your own team.
    • Use, extend, create - in that order:
      • Use existing material if it exists;
      • Otherwise extend and give back;
      • As a last resort, create your own.
    • Evangelise; encourage other nations to adopt the manual. Like language, the manual becomes more valuable as more people use it.
    • Use collaborative tools and methodologies to engage communities and evolve material.
    • Share ownership and control.

    Modularity

    Let's make the style manual extensible, to support domain specific requirements and individual flair. For instance, the international manual will need to support toggling between American and British spelling, and agencies will want to add domain specific acronyms. 

    Don't finish

    People will continue innovating. Establish a sustainable project, owned by multiple stakeholders, with periodic release cycles, which will last beyond your current funding cycle.