Reinvigorating Community Documentation

[Connor Imes]

It's been a long time since I chimed in on documentation, but here goes...

After a quick (and incomplete) review of the discourse threads, I see 
that many of the problems and challenges have been touched on.  In 
summary, documentation is hard - it requires constant attention since 
systems (both hardware and software) are constantly changing.  
Maintaining good documentation requires coordination with many people, 
including but not limited to: developers, tech writers, translators, 
infrastructure maintainers (e.g, Canonical's IT), release managers, and 
of course users who have varying levels of expertise and a wide range of 
needs and expectations.  Additionally, it's usually a thankless job and 
too often not valued by other types of contributors, yet often a target 
of complaints.

We've been fortunate to have some long term contributors over the years, 
like Gunnar and Doug in recent times (thank you!).  It's otherwise been 
extremely difficult to keep contributors interested and active in the 
long run.  This is probably unavoidable since people inevitably move on 
to new things and life priorities change.  Therefore any reinvigorated 
approach likely needs to regularly attract new contributors to keep up 
with the churn.

But bringing in new contributors won't solve many of the big problems, 
e.g., the vast documentation rot on the community wiki. We've made some 
attempts in the past to organize it, scrap old and obviously incorrect 
material, and document pages needing attention (see Tag [1]).  I last 
took a pass at this in 2017 but definitely did not get to all the pages 
- it took me the better part of a summer to get up through the K pages 
[2] before I had to turn my attention to other things.  Truly overcoming 
big challenges like this requires planning, consensus, and sustained 
execution.

It may be that somebody (e.g., a full-time Canonical employee) needs to 
accept ultimately responsibility for a re-invigoration project.  In such 
a scenario, it would be their responsibility to shepherd this 
project---in collaboration with the community---from ideas, to plans, to 
execution, and then to maintenance and regular re-evaluations.  There's 
no doubt that this is hard, but without an incentivized and accountable 
organizer, I expect we'll pretty much be stuck where we are now.

[1] https://help.ubuntu.com/community/Tag
[2] https://help.ubuntu.com/community/TitleIndex

Cheers,
-Connor

On 7/29/2021 5:59 PM, Monica Ayhens-Madon wrote:
> I am so sorry all! Here is the link:
>
> https://discourse.ubuntu.com/t/ways-to-improve-documentation/23478/
>
> Monica
>
> On Thu, Jul 29, 2021 at 5:53 PM jim <jim at well.com> wrote:
>
>>
>> Seems there is no link in the first paragraph.
>> Please send link.
>> With thanks
>>
>>
>> On 7/29/21 2:43 PM, Monica Ayhens-Madon wrote:
>>> Hello, all!
>>>
>>> It's definitely not a secret that our documentation is really outdated in
>>> places, and updating it has not been easy. The community team, however,
>>> wants to help the community not only update the documents, but update our
>>> documentation processes as well, as shown in some of the ideas in this
>>> Discourse thread.
>>>
>>> If this sounds like something you would like to be a part of, please join
>>> the discussion linked in the paragraph above, or start a discussion here.
>>> We know any fixes won't be easy, but we want to help the community build
>>> documentation and processes that are useful, user-centered, and
>> sustainable!
>>> Cheers,
>>>
>>> Monica Ayhens-Madon (she/her)
>>> Ubuntu Community Representative
>> --
>> ubuntu-doc mailing list
>> ubuntu-doc at lists.ubuntu.com
>> https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
>>