Tech writer patterns, anti-patterns and tasks

 This essay captures patterns, anti-patterns, and tasks needed by the tech writing community to create good docs. It aims to provide a focus point for ideas which people can collaborate around.

Reading time: 20 minutes

It has been used as founding concepts for The Good Docs Project, ideas for Season of Docs, and a few presentations and videos.

You can see the original essay, along with many review comments in a Google doc.

First draft: 28 May, 2020
Last updated: 19 March, 2023

[the dream] A vision for good docs

Open source is an amazing social success story. It creates huge technical value which is shared with the world. However incomplete, unpolished and outdated documentation is a pervasive problem suffered by most open source projects (and software projects in general).

A bunch of us technical writers have gathered under the banner of The Good Docs Project. We want to tackle these challenges. While our initial focus was on open source software documentation, we’ve realized that the same documentation patterns and anti-patterns keep repeating themselves across all sorts of domains. So by addressing systemic writing challenges, we hope to lift the effectiveness of the entire technical writing ecosystem. Would you like to join us?

Lessons so far

From our research, we’ve found pockets of awesomeness - spread across presentations, blog posts, forums, applications, and organizational specific practices. But there are holes as well, and the pockets are typically disconnected or working in silos. We’ve been building templates and writing instructions, and have been learning a lot about the challenges around creating good docs. What we discuss in this essay are highlights from what we’ve learned so far and what is left to do.

Why describe patterns?

Describing patterns helps us realize our challenges are universal, and as such, are best solved collaboratively.

It also helps us to break problems into their base components. Then different teams can solve the problems independently. For instance, the document structure used should be solved separately to the choice of markdown format.

[pattern] Modular design

The modular design pattern is often used in systems engineering. Components are defined with standard interfaces, allowing for multiple implementations, independent development, and rapid innovation, while keeping the overall system stable.

We shouldn’t try and build a mega documentation system to rule them all. Rather I see us defining a swarm of interconnected concepts, each of which is realized by multiple components, connected via standard interfaces.

This approach makes it possible for all of us to bite off a small, achievable part of the wider vision.

A component could be:

• A style guide;
• A doc storage format, such as markdown; or
• A doc audit checklist.

[pattern] Top down / bottom up

What we are talking about is a simple top-down vision of lifting the community with good docs, with an ecosystem of bottom-up implementations, each being tackled by small groups independently of others. This pattern has many names.

• In the open source world, you may know of The Cathedral and the Bazaar essays from Eric Raymond.
• The activists’ catchphrase is think globally, act locally.
• Gartner talks about bi-modal development, where stable infrastructure enables rapid innovation.
• Lieutenant Colonel Dan Ward, from the US Air Force’s acquisition branch uses Star Wars analogies to explain that governments should build droids, not death stars.

There are already many great initiatives within the documentation space. The value we can bring is by helping stitch all these initiatives together.

[pattern] External collaboration

“Collaboration out-competes competition”

Looked at through the lens of traditional management, collaboration is hard to justify. It is:

• Time consuming,
• Imprecise,
• Unreliable,
• Hard to manage,
• Rarely addresses short-term objectives, and
• Hard to quantify in a business case.

And yet, in a digital economy, collaborative communities often out-innovate and out-compete closed or centrally controlled initiatives.

For example, the collaboration found in open source communities offers a compelling alternative to capitalism.

• With capitalism, you pitch an idea, raise capital, hire staff, build, sell, and make a profit.
• With open source, you paint an inspiring vision, attract collaborators, build, and share with everyone.

The secret:

• There are more people in the rest of the world, working on your generic problem, than you can ever muster in your team.

Further information:

• The “Open Business” business case

[pattern] Multidisciplinary collaboration

“It takes a village to raise good docs”

In researching the documentation needs of projects, we’ve discovered that crafting good docs requires multiple skill sets, typically coming from different communities. The breadth of skills required makes solving documentation challenges elusively difficult.

Ideally, documenters have access to:

• A developer, with a deep understanding of the software being described.
• A product manager, who has a holistic view of the application and it’s roadmap.
• A software user, able to explain the application within the context of the application’s domain.
• An “expert newbie”. Some of the best feedback comes from new users who get stuck.
• An educator, who understands the principles of learning.
• An information architect, who understands how to structure material.
• A software support person, who learns all the pain points of users.
• A researcher, who proactively identifies pain points and market opportunities.
• A writer, who writes clearly and concisely with good grammar.
• Translators, for translating to target languages.
• A DevOps person, who can set up doc build pipelines.
• A community builder, and coordinator, who can inspire collective action, capture offers of help, and help all these different personas to collaborate together.

[anti-pattern] Short-termism

Should you prioritize management’s short term objectives, or attempt to solve the difficult and mis-understood root causes?

With documentation decisions, short-termism is rampant. And there are reasons for this:

• There is a very low barrier to entry to writing tick-box acceptable documentation.
• However, there is a very high collaboration overhead associated with writing excellent documentation.
• We find it hard to measure, explain and justify the value of good documentation.
• Tech writers typically have low political capital within organizations.

[task] Business case for good docs

This task involves writing a template business case for investing in good docs within an organization. The business case should:

• Be customizable for different use cases and organizations.
• Cover pros and cons of different strategies, described in business terms.
• Reference research.
• Cover multi-levels of involvement:
  • Why write docs?
  • Why write good docs?
  • Why adopt best practices?
  • Why share and collaborate with external doc communities?

Further information:

• Docs Business Case Working Group

[task] Docs fact pack

To support a business case for investing in documentation, it helps to be able to reference a Docs Fact Pack, with a list of compelling quotes, with links back to source research. This is especially useful when lobbying for investment in docs, especially for writers with limited access to decision makers within their organization.

I’ve seen the fact pack concept used effectively for a bicycle lobbying group back in the 1990s. News reporters would often copy a string of facts verbatim into published news articles. This added legitimacy and influence to the cause.

Further information:

• Docs Fact Pack

[pattern] Templates

Templates provide a conduit for collaboration. They facilitate the transfer and refinement of knowledge between time periods, between domains, between job types, between projects, between organizations.

Templates enable significant efficiencies by allowing experts to focus only on the bits they do best.

1. Writing professionals embed best practices into the template.
2. Domain experts write better content, more efficiently, when they have a template to work against.
3. Writers polish the expert’s content by reviewing for compliance against the template.

[task] Template for templates

Writing templates for key doc types is our initial focus. This should start with identifying common elements for all templates - consider it a template for templates.

What information and guidance should be captured in each template? What supporting information should be provided in a supporting document? Each template should identify a target audience. It should be backed up by reasoning and research, which will help an author trust the templates are based on best practices, and know if and when it would be appropriate to deviate from the template.

Further information:

• Good Docs Template Contributing Guide
• Historical Good Docs github base template directory
• Directory of base template working documents
• Template for Templates proposal proposal from Lana Brindley

[tasks] Content type templates

There are multiple templates needed for different content types. We will need to define target audiences, create the document structure, expected headings, along with writer guidance. This should be backed by evidence justifying why the template is best practice.

There is a lot of work to cover here, and can be addressed by multiple projects running in parallel.

A possible hierarchy of templates includes:

• Base template
  • Concept
    • Landing page
    • Overview
    • Explanation
  • Task
    • Quick start
    • Tutorial
    • How to
  • Reference

[pattern] Content design

“Content design is a way of thinking. It’s about using data and evidence to give the audience what they need, at the time they need it and in a way they expect.” Sarah Richards

It provides a systematic approach to structuring information.

Content design

[task] Content design guide

Community developed documentation regularly becomes disorganized and difficult to navigate. This task involves researching how readers approach your documentation, and organizing your docs so that they are easy to maintain. In technical writing terms, this is called information architecture.

It should:

• Help projects structure their documentation.
• Help projects maintain their documentation.
• Help projects move existing documentation to better information architectures.

It may include:

• Templates for different information architecture needs.

Further Reading:

• Information Architecture Guide proposal from Lana Brindley

[task] Process to define audience and messaging

To write effectively, it is important to understand who your audience is, and what information you wish to convey.

This task involves describing the steps to work out the target audience and message.

[pattern] Quality definitions, checklists and audits

During Season of Docs 2019 we discovered that we didn’t have a good definition of “good documentation”. We wanted to assess quality, currency, completeness and fitness-for-purpose of a project's documentation set.

For open source software projects, you can find comprehensive incubation processes to assess the maturity of a project’s software, its community, and the community’s processes. Likewise, businesses have defined quality management auditing processes, such as ISO:9001 and CMMI.

Similarly, we want to describe a project’s documentation maturity, and associate that with business impacts of poor maturity. Projects will then have metrics to help prioritize what, where and how docs should be maintained.

Note: Quality needs differ for each doctype:

• Reference docs should be accurate and current, but can tolerate poor grammar.
• Tutorials should be unambiguous, but can reference older software.

Further information:

• An Information Process Maturity Model, developed by Joann T. Hackos, which defines levels of process maturity for information management.
• Proposed Defining Good quality scale.

[task] Docs audit checklist

This task is about building a doc audit checklist (or set of checklists). It involves identifying, classifying and cataloging doc quality criteria. It will involve addressing from multiple perspectives, such as:

• The target audience(s).
• Each doc type's purpose.
• The maturity of the project.
• The short and long term capacity to write documentation.

Further information:

• Doc maturity levels and audit checklist, developed by Daniel Back, sponsored by Google.
  • Original Proposal to implement a docs audit framework, from Daniel Beck for Google Season of Docs.
• web.dev content quality guidelines and checklist.
• ISO/IEC/IEEE 26511:2018 Systems and software engineering — Requirements for managers of information for users of systems, software, and services:
  • Behind a paywall.
  • “Provides requirements for strategy, planning, managing, staffing, translation, production, and quality and process-maturity assessment for managers of information.”

[task] Doc quality measurement strategy

This task involves defining the practical steps required for ongoing measurement of doc quality. Insights gained can help projects refine their doc strategy.

For instance:

Goal	Signal	Measure	How?
Docs are current	Docs are up-to-date with software	Check timestamps and version variables of docs and software	Script which checks lookup table to find the correct software/docs and then checks timestamps.
		Search docs for each API name and associated parameters.	Software and doc passing script.

Consider:

• How good is the measure at showing the signal?
• If I gain insights from the signal, what business decision(s) will I be able to make, and how much business value can be realized or saved based on this?
• What is the cost of measurement? Is it worth it?
• How much lead time is required before I'll be getting meaningful business value from data collected?

[anti-pattern] Too much documentation

“Less words get read more.”

There is a balance to reach between providing your reader with enough information and overloading them with content. Large swaths of documentation is often indicative of deeper problems, such as a poor user interface.

[pattern] Reduce the need for documentation

Even better than good documentation is not needing the documentation in the first place.

• Applications with an intuitive user interface reduce documentation requirements.
• Similarly, automated tools can reduce manual steps required, which in turn reduces the amount of documentation that has to be written/read/maintained.

[anti-pattern] Outdated documentation

It is difficult to keep documentation up-to-date with the rapidly evolving software it describes. Doing so typically requires a multi-pronged strategy. It may cover:

• Integrate doc refreshes into software release checklists and processes.
• Auto-generation of docs, screenshots and other content.
• Periodic reviews.
• Minimizing the content footprint.
• Writing timeless documentation, avoiding language that anchors to a point in time.
• Tracking status.
• Categorizing the priority of content to maintain.
• Recruiting, coordinating and supporting contributors.
• Empowering users to fix and improve documentation.
• Reducing technical barriers to entry for updating docs.

[task] Strategy to keep docs current

This task involves describing options, feasibility, tools, tradeoffs and practical advice which projects can follow to implement strategies to keep documentation current.

This may extend to providing automated tools which systematically check and report on “stale” documentation.

[pattern] Content reuse

A documentation set can draw upon multiple sources. In presenting this information, there are multiple trade offs:

• Using variables helps with re-purposing similar material, and re-releasing updates. However, it introduces a technical barrier-to-entry which can be off-putting to potential contributors. And new contributors might accidentally overwrite and break the logic. So content reuse can be both a pattern and anti-pattern.
• Documentation can be customized to directly address the users’ profile. Or generic sections can be used, which are potentially ruggedized and maintained by a community.

Reuse sub-patterns include:

Find and replace:

An author applies a simple find-and-replace strategy for words like YOUR_PROJECT.

Variable substitution:

Variables are replaced at publishing time. These can be:

• Standard terms, such as <table_of_contents>, <page_number>, or <last_updated>.
• Author defined terms, such as <project_name>.

Section substitution:

For instance, a reader may be able to select the programming language used for code examples.

Cookbook sections:

A skeleton structural document specifies which subsections to include.

Inheritance:

A document inherits characteristics from a parent document. For instance:

• Task template -spawns-> Tutorial template -spawns-> Hello World tutorial
• The glossary for a document includes a subset of the glossary for the organization.

[task] Establish content reuse best practices

This task involves researching, cataloging and aligning best practices around content reuse. It might also involve:

• Developing integration standards, or
• Extending old systems, or
• Developing new systems.

[pattern] Style guide

A documentation style guide captures guidance around writing style, language choice, grammar and related concepts. It helps communities build consistent documentation which align with best practices. Communities should adopt one of the established, widely used style guides and customizing as little as possible. The Good Docs Project has adopted the Google developer documentation style guide unchanged. However, there are legitimate business reasons for deviating from an established guide.

For instance, if your project is used solely within England, you may choose British English instead of American English. Or you may have domain specific terminology which should be added into the accepted word lists.

[task] Guide for adapting a style guide

This task involves helping an organization select a style guide, and how to select customizations for it. It should also explain the business consequences of deviating from a standard style guide.

Further information:

• How to customize a style guide from Alyssa Rock (This is a still working doc on June 24, 2020)

[task] Distill a common core style guide

There are a number of established documentation style guides, and there are legitimate reasons for the differences. However, there are many core concepts which are shared by all (or most) of them.

This task involves:

1. Recognizing that writing communities would benefit from consistency in core concepts used by these guides.
2. Distilling the core concepts from these guides.
3. Adopting common language to describe these core concepts.
4. Refactoring established guides into core concepts, and extension concepts.
5. Ideally, each extension concept should be grouped and become a tick-box selection, such as “Should I use one word list or another”.
6. An existing style guide could then be described (and selected) by a tickbox selection of concepts.

This task would be made significantly easier if the owners of leading style guides play a lead role in the process.

[task] Writing tools which support style guides

The quality of a writer’s work, and their productivity, can be significantly improved if they are provided with real-time feedback on their writing style as they write. Such tools already exist, in the form of spell checkers and grammar checkers.

This task involves updating writing tools to allow users to import a documentation style guide, and then have the tool check the user’s writing against the imported style.

Further information:

• Taking a style guide from idea to implementation proposal from Chris Ward.
• Prosemirror typerighter The Guardian’s open source doc linter. Story about it (from the Guardian of course).
• Vale: “An open-source, command-line tool, that brings your editorial style guide to life.”

[task] Standard machine readable format for style guides

A machine readable format for style guides should be defined and adopted by the industry as a standard. This will facilitate interoperability between the ecosystem of documentation tools and the writers of style guides.

This task involves the development of the format, through to the industry and community adoption of it as a standard.

[task] Codify style guides into the machine readable format

In order to support style checking in writing tools, existing style guides will need to be codified into a machine readable format. Ideally, this format is one that has been widely adopted as a standard.

This task involves codifying existing style guides into a community standard machine readable format.

[anti-pattern] High technical barrier to entry

Within open source communities we have projects desperately needing docs, and grateful users keen to give back through documentation, but they are stumped by significant technical barriers to entry. The git/wiki tools used are difficult to learn, and clumsy to work with.

[anti-pattern] Compromising on doc toolchains

There are competing doc tool chains used to develop documentation, each with their pros and cons:

1. Software developers tend to store docs in git next to their code, using wiki formats, such as markdown. This offers excellent version control, ability to add variables, and integration with doc generation pipelines. However, it has a high technical barrier to entry.
2. Word processors, such as Microsoft Word and Google Docs, make it easy for reviewers, offering embedded track changes and comments. They also offer real-time syntax and grammar checkers which significantly helps writers.
3. Content management systems tend to fall somewhere between these.

Compromising on the toolchain is a universal problem for technical writers. Considering the size of the problem, (number of technical docs) x (amount pain caused and time lost), it is surprising the problem hasn't been fixed yet. If a tool were to address this challenge it could become a category-killer.

Further Information:

• Proposed project to integrate tooling from Chris Ward

[task] Integrate doc editors with git backend

A prototype integrated tech writing tool could be relatively easy - write a round trip converter which uses a WYSIWYG client like Google Docs, and git with a markdown variant for data storage.

This task involves integrating the best features from each of the tool chains and making the tool(s) accessible to all writers.

[task] Round trip conversion between formats

There are multiple doc formats and reasons to convert between these formats. It would be very valuable if tools could reliably round-trip convert from one format to another and back again, without changing the source documentation. Particularly valuable would be a tool chain for round-tripping from Google Docs to Markdown and back.

This task involves developing tools, conventions and processes which support round-tripping between documentation formats.

[anti-pattern] Multiple wiki formats

There are a multitude of wiki formats, each their own strengths and weaknesses, but the biggest weakness of all of them is the lack of standardization and resulting interoperability challenges. Even Markdown, one of the most popular variants, has multiple flavors.

[task] Standardize on markdown variant

For The Good Docs Project, we have decided to store our base documentation in Markdown, because it is widely used, and it is easier to convert docs to formats which offer more functionality rather than the other way around.

Unfortunately there are multiple variants of Markdown. We should select one variant as our standard, which will help with interoperability between implementations. CommonMark has defined an unambiguous version of markdown. Also Github Flavored Markdown (GFM) extends CommonMark with a few improvements, such as table support.

This task is to set up a git commit hook which checks for compliance with the Markdown variant we select, and then to apply compliance checks to existing documents.

[task] Markdown linting

We should make use of best practices in the formatting of Markdown documents.

This improves readability, and you avoid picking up false positive formatting changes.

This task is to select/define a format standard, provide a tool for linting, and check linting during git pull requests.

This task can be extended to other wiki formats supported in future.

[pattern] Traceability

Bi-directional traceability is a systems engineering practice, which enables systemic quality control within large, mission critical systems.

It involves tracing between business requirements, technical requirements, implementation, and various levels of testing.

Simple traceability can be managed within a spreadsheet, but traceability for complex systems requires supporting tools, processes and unique writing rules.

[task] Traceability tools and processes

This task involves identifying tools and processes that can be easily integrated with existing tools used by typical technical writers. In particular, this should address the use case of a writer working with an open source toolset.

[task] Consistency between documents

Guidance provided by documents should be aligned. For instance, recommendations within a writing template should align with the style guide.

This task involves auditing The Good Docs Project documents and bringing them into alignment. The dependencies should be traced to help future maintainers understand the impacts of proposed changes.

[pattern] Private/public division

Organisations regularly need to support mixed access restrictions to content, along with graduating content from one security domain to another. For instance, draft content might be restricted from public viewing until it has been reviewed, and the feature it is describing has been released.

This functionality is already supported by many tools.

[task] Guide for public/private management of documentation

This task involves updating tools, conventions and processes to access restrictions.

[pattern] Training

“Give a person a fish, and feed them for a day. Teach them to fish, and you feed them for a lifetime.”

Teaching others to write better is one of the most efficient ways to improve docs.

[task] Training

This task involves:

• Identifying suitable training.
• Updating or creating training material to align with best practices being adopted.
• Making training material available.
• Ensuring training material is equitable and inclusive.
• Building a community around the maintenance and delivery of training material.

Further material:

• See Google’s publicly available tech writer training course material.

[pattern] Glossary management

There is a cluster of lexicon management patterns, used with varying levels of uptake and maturity by projects. These include:

• A glossary which defines terms and acronyms.
• Preferred terms, terms to avoid, and alternative terms that writers should use.
• Lists of equivalent terms for different languages, which help translators to translate terms consistently.
• Cross domain lexicon management, determining which community gets to define a term, coordinating cross domain management of terms.

[task] Best practices for glossary management

This task involves defining the lexicon management problem space, and then starting to collate best practice processes in this space.

[task] Establish sharable glossaries

Develop standards, tools and processes to allow glossaries to share terms between organizations and projects.

Inheritance of terms between glossaries

Further information:

• The sharable glossaries project.

[pattern] Documentation publishing tools

The documentation publishing domain has received plenty of attention for the last few decades. I suggest this need not be a priority for us.

[pattern] Localization

Documentation translation, referred to as localization, helps reach a wider audience, who either don’t speak English, or don’t speak English well. Approaches to localization include:

• Adopting simplified technical English, as per the ASD STE100 standard.
• Incorporating automated machine translation using tools such as Google Translate api and Amazon translate.
• Applying tailored human translation workflows such as git localize.
• Adopting a combined approach.

According to wikipedia, only 23% of the world speaks English, and only 7% speak it as a first language.

[task] How-to for localization

This task involves writing guidance on considerations, processes and potential toolchains to consider when setting up a translation pipeline.

[pattern] Sharing knowledge promotes equity

“Vibrant communities are critical to project health, code quality, and adoption, but the lack of clear documentation about our project, its code, and the norms and processes of our community is a highly effective barrier to adoption and contribution.

If we do what we can to make sure that knowledge is accessible to everybody, regardless of disability, or language, or social capital, we promote equity.

Knowledge is power. Documentation puts that power in the hands of the people.”

Riona MacNamara at Write The Docs - Australia

[pattern] Education theory

There is a bucket load of research into learning theory:

• Different learning styles.
• What makes an idea “sticky” so that people remember it. We should reference that theory and update our templates to account for learning theory.

For instance, go listen to the Utilitarianism: Crash Course Philosophy #36 video which I think applies excellent learning strategies:

• Fun
• Engaging
• Ties complex concepts back to stories you already know. (In this episode, they use the Batman and Joker characters which we already know to explain the behaviors of them).
• Information density
• Formula for presenting information: Into concept, examples, theory, summary.
• Quick presentation pace.
• Young presenter, the age of the target audience.

Further information:

• Lana Novikova - Let's bring science into technical writing (slides)

[pattern] Reader/author ratio

Consider the cost of docs based on the reader/author ratio. The higher the ratio, the greater the importance to put on maturing the doc quality. For low ratios, as you may find for edge cases in community forums, there is typically a higher tolerance to lower quality docs.

[anti-pattern] Low political capital

According to Tom Johnson’s survey of 406 tech writers, 34% were lone writers, 31% only had 2 to 4 writers.

This low team size, along with peripheral involvement in business and engineering decisions results in tech writers typically having low political capital to lobby for improved documentation processes.

[call to action] Want to help?

While there is a barrier to entry for each of these problems, many will only require a few dedicated contributors to achieve significant benefits across the entire technical writing domain.

• Do any of these problems resonate with you?
• Are you trying to solve part of one of these problems already?
• Do you want to collaborate in solving this?

If so, why not come join us at The Good Docs Project.

Highlights from building NSW Transport's Safer Roads portal

NSW Transport has built a powerful road querying portal and the technology is worth sharing with others.

Awesome road safety data

The NSW Transport's Safer Roads Program have collated awesome metrics for hundreds of road characteristics within our state. These are used to support evidence-based decisions and help apply treatments and fix problems before accidents happen. However, this data is spread across multiple datasets and has required significant technical expertise and time to access and understand it. Our challenge has been to make this data easily accessible, queriable, and presented in meaningful reports for road planners.

Safer roads portal

So we've built a web application to query and present road data. It supports queries such as:

“Find all 80km/hr road sections, with a risk rating between 1 and 3, with roadside obstacles within 10m of the road, along two selected routes in my council area.”

Results are displayed in real-time in a map and charts. Queries can be iteratively refined and improved by the analyst, and then printed as a PDF report.

Technical challenges

The technical obstacles we've faced are worth sharing with others wanting to tackle similar use cases.

Multiple misaligned models

Our users' queries need to access road attributes from multiple sources. It might track the road's centerline in one dataset and track each lane in another. And the roads are segmented differently in each dataset. The spatial queries across multiple layers are very CPU intensive and resulted in unacceptable query times for our state-wide dataset.

We addressed this by creating a master query layer, with roads divided into 100m segments, with each road segment aggregating all attributes from the source datasets.

We think we can improve this approach even further by moving to 100m x 100m map tiles for our query layer. This will make our query layer more tolerant of mismatched source layers and will allow us to integrate point and polygon layers.

Platform hacking

We built upon ESRI's ArcGIS Portal Web App Builder. It allowed us to quickly prototype a map and charts website. However, our use case pushed past the capabilities of ArcGIS Portal (and ESRI’s newer Experience Builder). We adding extensions and pulled in additional open source libraries. Notably:

• We replaced graphs with the more powerful Chart.js.
• We needed to support the circular refinement of queries, between both spatial and attribute queries, without re-starting the query. This required switching software to using a Model/View/Controller design paradigm, which also fixed up widget communication mixups we were having.
• The size of our dataset resulted in significant performance challenges. Initial queries crashed browsers, and first-round optimisation still caused ~ 10 minute response times). However, our data is relatively static, and this has enabled us to introduce database optimisation, tiling, caching and clustering strategies to bring standard query times down to web usability norms.

Open source options

In retrospect, we've realised that we've needed more than the capabilities of Web App Builder, and that the open-source stack of software would have suited us better. It would:

• Provide the full suite of capabilities we require.
• Address limitations with our current platform that we are having to work around.
• Be relatively easy to migrate to, comparable to upgrading to ESRI's latest Javscript API.
• Align with government open source recommendations.
• Allow other agencies to deploy our application without license restrictions.
• Allowed us to scale without license restrictions.
• Still facilitate integration with our ESRI based applications by using OGC open standards.

Integrating charts into a web mapping portal is something that appears to be missing from the open-source geospatial stack, and is something we could offer up for the greater good. So moving to a fully open source solution is something we are considering for future iterations.

Reusable?

So are there others trying to solve a similar use case who want a copy of our codebase? People interested in collaboration, providing a business case for us to share our code? I suspect so. At the very least, there are our state's regional road authorities, and probably also local government authorities. But I expect our equivalents all around the world would be interested. If you are one of these people, then please reach out to us.

About the author

Cameron Shorter was the geospatial business analysis on the project.

OSGeo-Live 13.1 Doc Release

Are you wondering what OSGeo docs would look like if they were written by a senior technical writer? Then check out the latest OSGeoLive Quickstarts. All English Quickstarts have been reviewed and improved by Felicity Brand as part of ​Google Season of Docs. We've published them in a docs only point release of OSGeoLive, version 13.1. (We've also re-introduced our presentation, thanks to bug fixes from Seth.)

What else happened with OSGeo's Google Season of Docs?

• OSGeo doesn't have a definitive glossary of terms, so we've started aggregating glossaries, which led to a bunch of OSGeo folks kicking off a ​GeoLexicon project.
• There were no definitive open source doc templates, so we've created them in ​TheGoodDocsProject.
• Another tech writer was allocated to GeoNework.
• We ​reviewed QGIS's doc challenges - and found a bunch of lessons which will likely be valuable for other projects too.

For more details, check out ​Felicity's report.

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.

Insights from mixing writers with open source

Mixing experienced tech writers with open source communities revealed new approaches for creating better documentation.

OSGeoLive distribution we've been documenting

During OSGeo Foundation’s involvement in Google Season of Docs, we discovered that, like many open source projects, we knew little about:

• The state of our docs,
• What we were aiming for, 
• What our priorities were, 
• The details of the challenges we faced, or
• How to improve.

We discovered:

• How hard it is to keep tech docs current,
• Skillsets from multiple roles are needed to create good docs,
• Open source’s docs and writing processes are immature when compared to software development.

It is an exciting problem space with high-value challenges ready to be tackled. It reminds me of the early days of open source before it became trendy with business.

What should tech writers work on?

Open source communities welcomed the chance to have tech writers improve our docs, and expressed a pressing need for it, but found it hard to articulate exactly what needed fixing.

• People explained that their project docs often hadn’t been updated between doc releases.
• Some projects had noticed new features that had not been documented.
• Other projects had issue lists - collating observed deficiencies, but had no systematic review.
• Most observed that docs were created by developers with no formal tech writing training.
• Many noted that their English docs were written by non-native English speakers.

But where should we start? We needed to decide on what we wanted, and what we should work on first.

What’s the definition of good docs?

And then we realised that we didn’t have a good definition of “good documentation”. For our software projects, we have a comprehensive incubation process to assess the maturity of software and the project’s community, but we couldn’t find a similar set of metrics to define “good documentation”. So we started TheGoodDocsProject, to collate “best-practice templates and writing instructions for documenting open source software.”
This helped us define what we were aiming for, and prioritise what we can achieve with our available resources.

Documentation audit

Once we knew what good docs looked like, we were then able to audit the status of projects' docs:

• What documentation do we have?
• Does it cover all the functionality?
• Does it cover end-user needs?
• Is the documentation any good?

We discovered that the quality, currency, and completeness of our OSGeo docs were immature when compared to the quality software they described.

It takes a village to raise good docs

In researching open source projects’ documentation needs, it’s become clear that crafting good docs requires multiple skillsets. Ideally, a doc team has access to:

• A developer, with a deep understanding of the software being described.
• A user of the software, able to explain the application within the context of the application’s domain.
• An educator, who understands the principles of learning.
• An information architect, who understands how to structure material.
• A writer, who writes clearly and concisely with good grammar.
• Someone who speaks English as a first language (for English docs).
• A translator, who is good at translating into multiple languages.
• A DevOps person, who can set up doc build pipelines.
• A community builder, facilitator, and coordinator, who can inspire collective action, capture offers of help, and help all these different personas collaborate together.

Technical writers usually have a high-level understanding of most of these domains and their skills are often under-appreciated and under-utilised, especially if directed with a vague “just clean up the grammar and stuff”.
However, the best docs typically have had been influenced by multiple stakeholders. This can be partly achieved using templates to collaborate between domains, timeframes, job roles, projects and organisations.

Tools for documenting open-source projects are painful

We experienced significant pain in trying to convert between writing and software toolsets. We love the versioning of git, are frustrated by clunky markdown interfaces, and want access to editing and review workflows of Word and Google Docs, along with grammar and syntax plugin tools such as Grammarly. Translation tools such as Transifex are pretty cool too.
Could someone please write an application which addresses this use case. Maybe there is an idea in here for a future Google Summer of Code?

Achievements during OSGeo’s Season of Docs

We’re quite proud of our achievements during OSGeo’s participation in Google Season of Docs. Our allocated tech writers have amplified the effectiveness of our existing documentation communities, and our documentation communities have amplified the effectiveness of these tech writers.

• Felicity Brand worked with around 50 of OSGeo’s open source projects to update their Quickstarts as part of our OSGeoLive distribution of software.
• Swapnil Ogale worked directly with GeoNetwork’s documentation team, auditing the breadth of docs, and their quality, setting up templates for future docs to work to, and updating a number of the docs.

Further:

• We kicked off TheGoodDocsProject - “Best practice templates and writing instructions for documenting open source software.”
• In conjunction with OGC and ISO spatial standards communities, We kicked off an OSGeo Lexicon project, to coordinate official definitions for terminology used within the Open Source Geospatial (OSGeo) context. This will apply best practice definitions to prior haphazard glossaries.
• We did a deep-dive analysis of the documentation challenges faced by QGIS, one of OSGeo’s most successful projects. Surprisingly, their biggest problem isn’t a lack of tech writers or complicated tools (although they are factors). Key problems centre around:
• Poorly capturing community good-will and offers of assistance;
• A lack of direction;
• Struggling to keep up with a rapidly evolving software baseline;
• Insufficient writing expertise;
• A high technical barrier to entry;
• Documentation and training being generated outside of the core project;
• Awkward documentation tools and processes.

Thanks Google

Thank you Google for sponsoring Season of Docs. Felicity and Swapnil who you sponsored for us were great. We’ve learned plenty from them, and we hope you can take what we have collectively learned to help make future Season of Docs initiatives even better.

Postnote

This story was picked up by:

• Google's open source blog and 
• opensource.org.

Frenchs Forest to Macquarie Park by bicycle

My commute to work is awesome. A one-hour cycle through bush fire trails and leafy suburb backstreets. It is quicker than peak-hour traffic and comparable to public transport.

Enjoy the Journey - to work!

Why is the QGIS docs team struggling?

The QGIS documentation team is struggling and needs help. This has been known for a while. The much harder question is “How do we help a mostly volunteer community?”.

Reading time: 25 minutes

Summary

Many have tried to help QGIS docs, with limited success. I’ve collated insightful quotes from a bunch of their stories and then postulate solutions. Surprisingly, the biggest problem isn’t a lack of tech writers or complicated tools (although they are factors).

Problems centre around:

• Poorly capturing community good-will and offers of assistance;
• A lack of direction;
• Struggling to keep up with a rapidly evolving software baseline;
• Insufficient writing expertise;
• A high technical barrier to entry;
• Documentation and training being generated outside of the core project;
• Awkward documentation tools and processes.

This leads to an immediate case to:

• Define and evangelise a vision and roadmap.
• Prioritise funding and lobby sponsors to resource the vision.
• Implement an information architecture review.
• Sustain a community evangelist/coordinator to attract and nurture a broader doc community.
• Sustain a trained technical writer to amplify the quality and effectiveness of the community.
• Attract external docs back into the core.

Medium-term:

• Ask the greater open-source community to address the usability of documentation tools and reduce the technical barrier to entry. Adopt improvements as they are developed.
• Align with best the practices evolving within TheGoodDocsProject.

While acknowledging the great work done to date, I feel the QGIS docs team has insufficient capacity and availability to skills to drive this agenda. Targeted and sustained investment should be applied to bring the quality of QGIS docs up to the quality of the software.

Observations

The challenge

As one of OSGeo’s Season of Docs administrators, I’ve been observing the QGIS documentation community for months. The Open Source Geospatial Foundation (OSGeo) was allocated two tech writers and we probably should have allocated one to QGIS. However, I recommended they work on GeoNetwork and OSGeoLive instead. I was concerned by:

• How daunting QGIS doc challenges were,
  
• A lack of clear direction within the QGIS docs project,
  
• The brief three-month window for Season-of-Docs, and
  
• The high risk that the writers’ efforts might not achieve tangible outcomes.
  

I noted:

The big challenge for QGIS is aggregating external content into the core docs from lots of satellite communities. It would be a huge win to get it done, but also very risky as it requires coordination and collaboration from so many external volunteers.

Harrissou added:

It's unfortunate to not assign a senior writer to QGIS. I was personally envisioning [Season of Docs] as a catalyzer, an opportunity to trigger mobilisation of the writing community, and to teach us actual and best practices. And maybe that experience would confirm to us that we need the profile [of person] you propose later.

So what is lacking, and what can be improved?

Kudos to the volunteers

Firstly, I’d like to acknowledge the value provided by QGIS documentation volunteers and help they provide to newbies who reach out. QGIS has a solid baseline of docs and dedicated but under-resourced volunteers. They face a difficult job keeping up with the more active, much larger, and better-resourced developer community. I don’t think external people appreciate the difficulty of the documentation challenge.

Season of Docs

Before Season-of-Docs’ writing period officially started (September 2019) we’d already attracted plenty of latent interest:

• A spin-off GeoNetwork documentation group of 4+ volunteers was meeting fortnightly. (Swapnil, a senior tech writer supports this team, as part of Season-of-Docs.)
  
• A spin-off GoodDocsProject, with 5+ senior tech writers, are creating best-practice templates and writing instructions for documenting open-source software.
• QGIS and GeoNetwork quickstarts were updated to the latest 13.0 OSGeoLive release. (Felicity is updating 50+ quickstarts for Season-of-Docs.)
  

Over 20 people volunteered to help out with OSGeo’s Season-of-Docs. 10+ of these people were interested in QGIS - more than for any of the other OSGeo projects. However, we’ve had lack-lustre success at capturing this initial enthusiasm. Why? I collate quotes and observations below.

Piers, small company, creating training material

Piers Higgs is CEO of a Gaia Resources, a small environmental consulting company. He and his team have developed QGIS training material which they publish for free as videos, a manual and data package. Piers notes:

• The thing I find strange is how many people are using our course now - there are people from all around the world now. Most of them aren't actually enviro's either - they are just people wanting any sort of resource to help them get into QGIS.
  

Piers articulately outlined how he’d love to share his material and continue to maintain it, noting also that he is time-poor. This is a hugely valuable offer, but there wasn’t someone from the community ready to catch this offer and work with him to the extent required.
Alexandre Neto noted:

• Because we don't have many writers (we have two very active people), it's quite hard to allocate [time for] that “king of merge” into what we already have. It looks like no one has interest in it, but it's not really the case. What we would prefer is to see companies create new sections, improve and reuse what we have in the training manual.
  

Like Piers, many of the people who volunteered to help with Season-of-Docs are similarly from small consulting companies in similar situations. I see this as untapped potential. Piers commented further:

• Yep, but how to tap this potential is pretty hard. Unless you have a TARDIS, or a cloning machine?
  
• This pretty much says why I can't get into this. I don't have the bandwidth and much of my drive is taken up running the business. The personality - well, Cameron, you have spades of that ;)
  
• I did find the whole thing really hard to actually understand what was needed and who was doing what. I guess being "outside the camp" for most of the QGIS stuff these days has made me realise how hard it is to find my way back in again.
  
• So it's one thing to have a bunch of time-poor people who are interested, let's assume we don't have a TARDIS or cloning machine to fix that. I did find that trying to work out what was going on and what Season-of-Docs is, who's doing what, etc was just too big a beast to deal with. It was an effective barrier to entry for someone new, and it's one of the reasons Cameron found it so hard to engage me - I had to keep asking him for clarifications on what all the lists are, where the documents are, who's who in the zoo, etc. It's just a little bit... chaotic. I will readily admit I lean towards OCD tendencies, but being time poor, time spent trying to understand what is going on is an effective barrier to entry. It became "too hard" very quickly.
  
• [Capturing offers of assistance and supporting and encouraging new volunteers] are things as a community we do pretty badly.
  
• My interactions with the main QGIS developers etc hasn't been very frequent, but it's been reasonable.
  
• ... So I think remembering everyone is a volunteer and will have different motivations is really important. I used to run a volunteer GIS group and keeping up ways in which time poor people can be involved is key - e.g. writing a chapter is a big ask, but editing or testing it might be smaller and easier for time poor people. Food for thought.
  

Andrew, power user, starting to help with docs

Andrew Jeffrey is a power QGIS user, and a bit more. He is not a programmer and is giving to QGIS through docs, coordinating a regional user group and qgis events. (Other potential volunteers have a similar profile.) Andrew painted a practical vision about how QGIS docs can be improved and proceded to write a getting started guide for the new users he’d been helping, and followed up with a QGIS quickstart for the OSGeoLive project. Andrew is the sort of person you’d want to encourage and support.
Andrew’s comments are revealing:

• I feel this review [of QGIS docs] was started with the meetings you coordinated at the start of the Season-of-Docs process Cameron and then lost momentum because no one took the lead when you started to focus on other things. I did try to rally people for the OSGeolive quickstart amendments but quickly lost interest in continually asking for input with no response.
  
• I haven't given a whole lot - but would like to do more. Things that stop me: What’s a priority? Docs, training material, screenshots? It would be helpful if a more senior doc mentor was able to say “this is the low hanging fruit” “that is a great way to get started”.
  
• The help I have received from QGIS doc folks has been good and available when I ask for it. The support in terms of sharing contributions via participants in the Season-of-Docs has been sporadic, but I understand everyone has time constraints and other commitments. Also even before tech writers were assigned to projects I was asking the list for feedback on documentation and received nothing. So my enthusiasm for the Season-of-Docs has dropped off because I didn't feel like I was getting as much out as I was putting in.
  

So while Andrew had some support, more support would likely help him feel more welcomed and would empower him to increase his productivity. Again, I think Andrew’s anecdotes hint at lost opportunities we don’t hear about.

Jared, a tech writer

Jared Morgan is a senior tech writer, curious about open source, who volunteered to help out. He started reviewing QGIS docs and received feedback from core contributors (Harrissou and Matteo). Alexandre noted that he missed seeing Jarad’s feedback. Unfortunately, this initiative hasn’t appeared to be sustained. It appears there hasn’t been sufficient bandwidth to nurture and sustain the goodwill.

Charlie, university courses

There were a bunch of offers from GeoForAll university members, suggesting that their tertiary training material be used. For instance, we could update the comprehensive GeoAccademy courses which are still based on the old QGIS 2.8 version. Unfortunately, the initial enthusiasm didn’t translate into tangible action. From my perspective, there appeared to be a very high barrier to entry. How can we help all these disparate organisations and fragmented initiatives to collaborate on a common base of material which is brought into the core QGIS docs? How can they become less brittle, so material continues to be updated when program funding finishes?
Professor Charlie Schweik suggested developing training material and textbooks in conjunction with universities, possibly making use of OpenStax. I’d suggest that his suggestion be aligned with maintaining core QGIS material, rather than creating a parallel initiative, and that the common material can be retasked for various educational courses.

Andreas, cataloging doc team challenges

The QGIS docs team discussed many of the challenges they are facing. Andreas Neumann summarises many of these:

• I agree that the documentation task seems to be overwhelming and might also be daunting for newcomers, volunteers and even paid people. I also agree that the team is under-resourced. … We already knew this. … it would be encouraging to hear more suggestions for how to improve the situation.
  
• Should the team focus on smaller chunks/goals in order to have better progress and a better success feeling?
  
• Are the tools too complicated?
  
• Is there not enough information provided by developers or organizations who fund new features?
  
• Another observation I have is that there is an awful lot of documentation about QGIS out there on the web, spread into many personal blog websites, company blog posts and news sites, youtube movies, social media posts, etc. etc. However, all of this vast and de-centralized information doesn't end up in our central documentation.
  

Anita, Nathan, tools and process limitations

Working out how to bring the world’s QGIS documentation back into the core looks to be a core challenge for QGIS. Anita Graser’s response provides insights:

• I tried [putting my doc updates into the core] but something is keeping me from doing it regularly. Thinking about it, reasons for me include:
  
• It's not always possible to simply copy a blog post to the documentation. The expected style (as in wording) of the text is different. The text should fit into the bigger picture. This often means a significant rewrite.
  
• Maybe just me but: I'm always uncertain of how to add figures and links correctly so that they are not broken in the built documentation.
  
• Lack of immediate feedback: When I post on a blog, the content is immediately online and - as feedback comes in - it's possible to make adjustments quickly. The above Pull Request was open for a month. (There were a lot of good discussions going on but it might feel more motivating to publish more quickly and improve incrementally).
  
  So the last two points come down to the process we currently have in place. Coming from a platform (Wordpress) where I can immediately see and verify the final results, the qgis.org documentation system makes me feel less certain about the quality of my edits and it takes much longer until corrections are visible online. (I know that I could build the documentation locally on my machine. I've tried with Richard's help in the past and failed to set it up on my machine.)
  

Nathan Woodrow, one of the core QGIS techies noted:

I personally find some of the technical issues as quite a blocker for people to help.  It's what stops me most of the time and I'm conformable with the tools, last time I tried on Windows I just gave up because it was too much work and I only have limited time these days.  I'm not sure what the solution here is but I don't know if moving to something like GitHub Markdown or Google Docs is the option, mainly because of it throws away a lot of the work we have already done.  Having said that though this is a pain point that might help address some of the community involvement if we can solve it.   It's not the only problem though like Alexandre said it's just not fun work at times and it can be hard to even write good docs when that is your job and you have a good platform to do it in.

Tim Sutton, one of the QGIS founders, reported:
Our main discussion points in the [QGIS Project Steering Committee] meeting were:

1. Current documentation approach is unsustainable (a few hardcore enthusiasts but not enough to cope with the rapid pace of development)
2. Inviting contributors needs to be substantially easier - I’m talking at the level of editing a google doc or word doc here. At the very least a GitHub markdown page that is instantly published as soon as you edit it.
3. Cameron has had a chat with me about employing technical writers to make the documents more cohesive - I think this is a good initiative but Cameron I think we need to get the fundamental issue of the editing platform sorted out first
4. Translations severely hamper our ability to switch to a more agile system (e.g. GitHub markdown based wiki or Google doc) - in the PSC call we want to surface the idea of doing away with translations and leave translation initiatives to outside communities (e.g. local user groups). PostgreSQL etc don't have the overhead of this.
5. Our documentation could be easier if the format was more structured - think something like editing a changelog entry here. Again we looked at the PostGIS / PostgreSQL examples here which have a very standardised format.

There were some sentiments in the PSC call to drop the documentation effort completely and leave it to all the various community members to deal with, but I think maybe my 1-5 points above make a better compromise of reduced overhead, more accessible platform for writing while still having docs in English at least. 

Stepping back from specific comments about tools and processes, I’m seeing a high effort-to-reward ratio for the external documentation community. Options to address this include:

1. QGIS docs core team to absorb the effort, either through funding or inspiring volunteers.
   
2. Help contributors get their content back into the core, likely with hand-holding, or possibly out-sourcing paid work to them.
   
3. Improve the efficiency of tools or improve our explanation of tools. While improved tools will be helpful, I think it is a generic problem faced by the whole open-source community. As such, I feel QGIS should reach out to the greater community to help solve it.

While there is acknowledgement that docs need improving, I feel there is a general under-appreciation of the effort required to:

1. Merge disparate documentation.
   
2. Increase doc quality from “verbose and okay” to “intuitive, obvious and concise”.
   

We need to start by articulating the problem and how we propose to solve it, which should help find both sponsors and volunteers.

QGIS Community questionnaire about docs

824 people answered a questionnaire about how you learn about QGIS. Anita Graser compiled results into the following tables.

Considering changes to doc writing based on survey insights varied from "do more" to "do less".
Tom Chadwin summarised the results as:

Questions 1-4 (quantitative)

• 70%’s first-choice is Googling/StackExchange, which dwarfs the < 20% choosing official docs
• The fact that Googling came top of search methods emphasizes that we need to pay attention to SEO in the official docs
• Fewer than 50% find their answers in the official docs “often” or “always”, 45% answering “sometimes”
• Official docs are underused – over 50% only consult monthly or less frequently (including “never”)

Question 5 (qualitative)

• Many find the official docs too abstract, and would prefer examples worked in
• Perhaps unsurprisingly, there is a lot of enthusiasm for video tutorials
• There is some criticism of the confusion of QGIS versions in the documentation, especially when deep-linked from a Google result

Paolo Cavallini argued:

To me this confirms my opinion: our manuals are of limited relevance to the community of users. IMHO we have two options here:

1. Re-haul the whole documentation so to make it the real reference.
2. Shrink it down to the bare minimum (mostly a list of the commands and functions available), leaving the fancy documentation out in the Wild World of the Internet.

Quite frankly (sorry, no offense for the huge and excellent work done until now), I do not see a realistic way of implementing (and, more importantly, to keep always up to date) the first option, so I tend to prefer the second one.

Summarising Alexandre Neto's longer analysis:

• It's clear that people often search for help a lot.
• In terms of QGIS Docs quality, ... [it] seems that definitely needs improving.
• As a documentation person myself, I naturally have to disagree with the idea that the project should ... simply resign to a shrunk version of the documentation and let the outside world provide the fancy answers to the users. ... IMHO, Good, precise, and updated documentation leads to more adoption and better user experience.
• An interesting fact: in two weeks open to answers, ... this questionnaire gathered more than 800 responses! To me, this alone says a bit about the importance that documentation has for our users.

Documentation best practices

I'm concerned people are searching for one approach to documentation when there should be multiple. In a highly regarded article in Tech Writing circles, Daniele Procida argues:

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:

1. Tutorials, 
2. How-to guides, 
3. Explanations, and 
4. 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. ...

I expand on this in Inspiring techies to become great writers.

The audience for different doc-types have different needs:

• API References need to be accurate, unambiguous and up-to-date. Polish is a nice-to-have.
• Community forums are great for niche topics. Incorrect or dated information is tolerated.
• Quickstarts need to be accurate and polished, but need not reference the latest Bleeding Edge release. Aligning with the Long Term Release is acceptable.

This approach should be defined in an information architecture and an implementation strategy (which is yet to be created for QGIS). These should take inspiration from TheGoodDocsProject, an emerging community of technical writers building “best-practice templates and writing instructions for documenting open-source software.”

Matteo, what to focus on

Matteo from the core QGIS documentation team who volunteered to mentor QGIS Season Of Docs writers suggested:

• I really think that currently, we need to define precise roles (issue manager, reviewer, English reviewer, etc). IMHO the growing complexity of the last years made it difficult for us to convince other people to contribute (at least, I'm not able to convince people during training and other activities)
  
• +1 for the "community" evangelist (could be another role of above)
• -1 to change the framework (even if complex is too important)
• -1 to create other dedicated repositories with additional training material: just add another chapter to the existing manual
  
  Summary: without boring everyone that already knows the current situation, I really think we have to set up a clear workflow (for us [the QGIS documentation team] and newcomers) or else we will lose volunteers and other people that want to contribute to the project.

Andreas, Paulo and Tim, considering funding

Andreas Neumann, Paolo Cavallini and Tim Sutton weighed in on funding tech writers:

• Andreas: It is not primarily a problem of finding financial resources. Every year we assigned funds for documentation and in most years those funds haven't been used. Even if we would make more funds available to the team, I feel this wouldn't solve the problems the team is facing.
  
• Paulo: While I agree that we should keep on using our funds, and additional resources, as an incentive for documenters, I think this should be done with a clear plan in mind. If not done carefully, this move could discourage volunteers, not only in this area ("why should I volunteer, when another one is doing the same thing and is paid for this?"). Volunteer communities are hard to build, and easy to destroy. Replacing volunteers with employees can quickly become very expensive, and we should be sure we'll be able to raise enough money both in the short and in the long term to fully support the effort. I suggest working out a budget for this, to check how feasible this solution can be, before taking further steps.
  
• Tim: I have a different opinion on this. Based on our experience of paying developers I don’t think it has in any way reduced the volunteer contributions to the code base - on the contrary, it probably has incentivised those that we paid to donate lots more of their time. I am pretty sure that we will have similar experience in other areas of the project. I am more bullish on documentation and think that we should work enthusiastically to get one or more dedicated, full-time document writers in the QGIS project….over and over we here it is the most wanting part of the project. 

2019 QGIS Budgeted expenses

Highlights for me after discussing the 2019 QGIS budget with Tim Sutton were:

• The QGIS team run on an incredibly small and efficient budget. Strategic investment from external stakeholders should yield a significant return-on-investment.
• Programmers' daily rates were higher than tech-writers'. This concerns me as I question whether tech-writers' employed are suitably experienced. Typically, a good tech-writer is a programmer who has learned to write, or a writer who has learned to program.
• The €12,000 allocated to documentation won't go far if paid at standard tech-writer rates.
• Bug fixing (for programmers) was allocated five times more than docs (for writers).

Clarence, finding writers

To find writers, Clarence Cromwell, a tech writer, suggested:

Why don’t you reach out to the WriteTheDocs community. It has a slack group which includes a #job-posts-only channel. I’ve seen many budding tech writers asking how to break into tech writing. You could offer to mentor writers in git and software processes, in return for a review of documentation.

This is worth pursuing in order to bolster our existing tech writing team. However, for holistic documentation leadership, I feel we need more than individuals can provide on volunteer time alone. We could consider Google’s SeasonOfDocs model of paying a stipend (for a lead tech writer). Note: I feel this role needs sustained sponsorship; Google’s sponsorship is limited to three months.

Anne and Charlie’s research into open source success factors

There are insights from open-source research we can draw upon. Pertinent to this conversation is Charlie Schweik’s research into open source success factors and Anne Barcomb’s research into episodic volunteers. Their research highlights:
Factors which lead to a project’s success are:

• Leadership by doing.
  
• Clear vision.
  
• Well-articulated goals.
  
• Task granularity: Projects have small tasks ready for people who only can contribute small bits of time.
  
• Financial backing.
  

Successful strategies for working with episodic volunteers:

• Although Open Source episodic volunteers were unlikely to see their participation as influenced by social norms, personal invitation was a common form of recruitment, especially among non-code contributors.
  
• Episodic volunteers with intrinsic motives are more likely to intend to remain, compared to episodic volunteers with extrinsic motives.
  
• Episodic volunteers derive satisfaction from knowing that their work is used, enjoying the work itself, and feeling appreciated.
  
• Lower barriers to entry.
  
• Provide opportunities for social interactions.
  

I suspect the QGIS project has become so successful, and the community so large, that it appears daunting for someone on the fringe who might want to join. They don’t feel worthy, are not sure how to break into the inner circle, or feel someone else will do the work if they don’t. It will likely be worth rekindling a supportive and personal culture within our community.

Learning from the OSGeoLive experience

I think it is worth considering the formula used in the OSGeoLive project to attract hundreds of episodal contributors, many of whom have been working on docs. It is summarised here:

• Start with a clear and compelling vision; inspiring enough that others want to adopt it and work to make it happen.
  
• This should be followed by a practical and believable commitment to deliver on the vision. Typically this is demonstrated by delivering a “Minimum Viable Product”.
  
• Be in need of help, preferably accepting small modular tasks with a low barrier to entry, and ideally something which each person is uniquely qualified to provide. If anyone could fix a widget, then maybe someone else will do it. But if you are one of a few people with the skills to do the fixing, then your gift of fixing is so much more valuable, and there is a stronger moral obligation for you to step up.
  
• Ensure that every participant gets more out of the project than they put in.
  
• Avoid giving away free rides. If you are giving away something uniquely valuable; and it costs you time to provide that value for your volunteers; then it is ok to expect something of your volunteers if they wish to get something in return.
  
• Use templates and processes to facilitate domain experts working together.
  
• Reduce all barriers that may prevent people from contributing, in particular, by providing step-by-step instructions.
  
• Set a schedule and work to it.
  
• Talk with your community regularly, and promptly answer queries.
  
• 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 better than you could possibly create by yourself.
  

My assessment

The QGIS documentation community appears overwhelmed and seems to need help with:

• Articulating doc challenges to the community, potential contributors, and potential sponsors;
• Defining a clear vision and roadmap;
  
• Coordination and project maintenance;
  
• Breaking large daunting challenges into small tasks that can be tackled easily by volunteers;
  
• Capturing community good-will and offers of assistance,
  
• Inviting people to get involved one-on-one and then mentoring them;
  
• Periodic catchups;
  
• Outreach and evangelising;
  
• Attracting satellite initiatives into the core;
  
• Keeping up with a rapidly innovating software baseline;
  
• Documentation tooling and processes;
• Sustaining initiatives, and orphaning unmaintained documentation.
  

Most importantly, I think the QGIS docs team is missing sufficient people with the bandwidth, drive and personality to drive this agenda. I feel there is likely to be quite a bit of inertia required to ramp-up such a team, but I think it is worth investing in, as I think QGIS will benefit greatly once it is set up.

Suggestions

These suggestions are presented in my proposed order of priority.

1. Community evangelist / coordinator

I believe QGIS should engage a “community evangelist and coordinator”, tasked with:

• Inspiring others.
  
• Capturing untapped goodwill from within the QGIS community and potential business sponsors.
  
• Embracing and extending QGIS’s supportive culture.
  
• Reaching out one-on-one and personally inviting people to join, then pro-actively supporting them during their onboarding experience.
  
• Helping to reduce barriers to entry.
  
• Defining and managing a roadmap, with milestones and schedules.
  
• Coordinating community collaboration.
  
• Supporting documentation development, deployment and reviews, as required.
  

We should look for someone who:

• Is friendly, approachable, and community-minded.
  
• Is likely a notable and experienced member of an open-source community, whose opinions are respected and hold weight within the community.
  
• Is technical enough that they can help a newbie with git and doc tools.
  
• Is business savvy and able to persuade business people about the value of collaboration.
  
• Presents competently at conferences.
  

Getting the right person for this role will be very important, as they will influence the culture of the rest of the team.
Sustained funding should be sourced for this role as it will be difficult to resource on volunteer labour alone.

2. Vision and roadmap

Common feedback from volunteers was not knowing how to give back. We appear to be lacking the vision and roadmap which open-source research suggests is important. Alexandre Neto noted:

• Unfortunately, this issue list is the only thing we have [re roadmap].
  

I suggest defining a vision and roadmap, which can then be referenced to help prioritise direction.

3. Information architecture review

I get the impression that QGIS documentation is quite good, but it hasn’t been audited by a senior technical writer/information architect. I suggest a senior information architect be engaged for a once-off engagement to set up QGIS’s approach to documentation. We should consider:

• Best practice document types, templates and writing styles, tailored for different target audiences.
• Documentation architecture.
• Quality expectations.
• Maintenance strategy.

Ideally this information architect would be the same person as the sustained technical writer role (in order to retain project knowledge).

4. Engage a technical writer

People from the core doc team have noted that much of the QGIS documentation is written by software developers, or power users (without formal writing training). For many, English is a second language.
I suggest a sustained technical writer role be set up to:

• Reviews all new documentation generated by the community.
  
• Work with the authors to ensure it fits with QGIS’s writing guidelines and quality standards.
  

This will require sustained resourcing, which I suggest be supported by a stipend, in-kind contribution from a company, or similar.

5. Attract external QGIS docs into the core

There has been discussion about the significant amount of external docs and training material which is not coming back into the core QGIS. I’d suggest:

• Publicly stating the value we place on internal rather than external documentation.
  
• Encourage sponsors, and those paying for training to make use of internal rather than external material.
  
• Reach out to external material providers and work with them to bring their material back into the core. Acknowledge extra effort required to do this. (It will be short term pain for long term gain.)
  
• Monitor community activity and opportunistically support people to bring their external docs back into the core.
  

6. Ignore the tools for the moment

It has been noted that the git/sphinx documentation toolchain is a barrier to entry for people coming into docs. While acknowledging the problem, I suggest leaving it for the moment as we have higher priority problems which we can resolve and should focus on. Leave this for the wider open-source documentation community to solve.