The problems faced by open source doc teams - and what to do about it

[Cameron Shorter]

I've written a detailed analysis about the significant challenges faced by the QGIS documentation team. (QGIS is an open source desktop geospatial application).

While research is specific to QGIS, I feel the lessons are broadly applicable to most successful open source projects. I'd be interested to hear feedback, and in particular, would be interested to hear whether the lessons should help frame next year's Google Season of Docs.

Tweet: https://twitter.com/cameronshorter/status/1203528611740831744

Blog post: https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html

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.

More: ... https://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

[Dashamir Hoxha]

On Sun, Dec 8, 2019 at 6:28 AM Cameron Shorter <cameron...@gmail.com> wrote:

I've written a detailed analysis about the significant challenges faced by the QGIS documentation team. (QGIS is an open source desktop geospatial application).

While research is specific to QGIS, I feel the lessons are broadly applicable to most successful open source projects. I'd be interested to hear feedback, and in particular, would be interested to hear whether the lessons should help frame next year's Google Season of Docs.

Your research and analysis is indeed detailed. I would like to give my opinion on a small issue.

Somewhere you say: "Typically, a good tech-writer is a programmer who has learned to write, or a writer who has learned to program."

From a software engineering perspective, the process of documentation writing is closely related to the process of software analysis and software testing. During analysis you try to identify the features that should be implemented, during testing you test (among others) that what was implemented satisfies the needs of the users, and during documentation you try to describe those features in the most easy way to understand and learn.

So, in my opinion, a good tech-writer needs to be much more experienced and skilled than just a random programmer.

Regarding GSoD, there are two preconditions of writing good docs (in my opinion):
- Learning very well the software that you are trying to document. If you don't know how to use it yourself you cannot explain it to the others.
- Following the issues and discussions made by the users, in order to understand what problems they have while using the software. Why do they need to ask for help? Is the explanation missing from the docs? Or the solution to the problem is not explained clearly? Or it is not so easy to find it in the docs?

Of course, not all projects are the same and generalizations may not apply to all of them.

Regards,
Dashamir

[Max V]

Cameron, there is another problem specific to small teams and solo devs. They produce docs to their best (limited) ability, but there is no feedback loop for them, so they cannot improve. Here is why I think there is no feedback ...

Pull requests and issues are not always suitable for documentation.

* it's too much work for what may be perceived as nit picking

* the reader may see a problem in the doc, but not being able to fix it other than pointing out at it

* it goes beyond grammar or style, e.g. a missing step or an confusing explanation

We have means and incentives to test the code before releasing it. How do we test the docs?

Spellcheckers and grammar tools will pick up on passive voice, but not on a confusing explanation.

* not many programmers are skilled or interested in writing docs

* those that do write may not have sufficiently skilled or motivated peers to review it

* EN proficiency may be low, if we all assume that docs should be in EN

There is little incentive on the part of the user to contribute back to the docs because they already figured it out for themselves and it doesn't affect anything downstream for them, which comes back to my gripe about using pull requests or issues for fixing docs - too much work for something that has little upside to the contributor.

Larger teams have technical writers, proofreading and a release process. Smaller teams and solo devs bang it out at the end of the project and publish.

1. There should be a simple way for smaller teams to "test" their docs before releasing.\

2. There should be a simple way of giving feedback to ANY docs while we read. E.g. "did you mean X?", "a diagram would help",  "Too verbose".

I think the solution is in coming together as a community to build tools for proofreading and feedback so everyone can improve bit by bit.

Cheers,

Max

[Max V]

Cameron, I would also add the problem with getting feedback and proofreading of documentation to your list.

The normal pull request workflow doesn't always work for documentation either:

* It's just too much work for what may be perceived as nit picking.

* An outsider may be able to point at where the problematic parts are, but not be able to re-write them.

* Once someone got the downloaded code going there is no incentive to work on the docs.

We test our code before releasing it, but how many of us test the documentation?

If proofreading is testing, then it's a near impossible task for small teams and solo developers. I can test my code, but I cannot test the documentation I wrote. I'll need at least one more pair of eyes for that.

Who's going to review my readme.md unless I pay for it?

I started working on https://feedback.farm to build a peer-to-peer proofreading community.

The project is still at the idea validation stage. I'd really appreciate your opinion on it.

Cheers,

Max

[Cameron Shorter]

Hi Max,

I can see that you have been thinking hard about this problem. I agree with you assessment that the barrier to entry for contributions is very high and is turning away potential contributors. I also agree that if we can improve the tools - and people learn to use them, then we have the potential to attract a greater contribution community.

I see you are aiming to lower the barrier to entry with the feedback.farm tool. Which is a great goal. However, I think your project needs a strong community to work, and I feel your community proposition is currently a tough one.
 I guess the question remains:
1. What is the return on [learning] effort for someone considering using feedback.farm?
2. How much effort do I have to invest to get involved?
3. What is the likelihood that effort invested reviewing someone else's project will result in quality input into my project?

For me as a tech writer, I see this as a high risk proposition. I'm not keen to invest time in reviewing someone else's content - when I'm not sure that other person will like my writing style. Equally, I'm not sure that someone who doesn't know my project will provide quality review for me.

I'm not sure if that is what you want to hear. Sorry about that.
I wish you all the best in your endeavours,
Cameron

--
You received this message because you are subscribed to the Google Groups "Season of Docs - Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to season-of-docs-di...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/season-of-docs-discuss/80664c60-fbbb-4a7f-9c74-6602c9ccaca3%40googlegroups.com.

--

Cameron Shorter

Technology Writer at Google

Open Technologies and Geospatial Evangelist