1. Cncf-Toc
  2. Messages

Re: the challenge of documentation

Sarah Allen
 

I can't speak to what was discussed at the meeting, but I agree that the contributors need help.  In my experience, they (mostly) do want to produce good documentation. 

Many projects would benefit from experienced technical writers; however, I think the need is bigger than that. I'm seeing that many projects don't often get effective feedback from target users.  In the security reviews, I'm finding that it often takes quite a bit of time to just understand what the project is supposed to do (e.g. what problem is it solving, what is is not trying to accomplish).  I'm seeing a lot of confusion where developer or operators expect a project wil handle some aspect of security, but the project believes that is outside of its scope... but this problem isn't just about security.  Often the fundamental project capabilities are very time consuming to understand.

I'd like to see the core functionality explained better with clear tutorials of common use cases.  This is very hard for a project to do on its own, since maintainers typically don't understand the full context in how their projects are used.

Some ideas...
  1. Pair a writer with user researcher and invite "End User" companies to participate, let the maintainers watch developers go through the process of using the software.  This is standard practice with UI, and increasingly with APIs in larger companies, but rare in open source -- access to the cross-functional team + willing participants is very hard for an open source project to make happen.
  2. Create a virtual internship program where unemployed developers or students can apply to spend 5-10 hours with a project of their choosing, attempting to build something, writing up issues, making doc PRs, etc.  I strongly suggest actually paying people money for this, even though the overhead can be significant.  This would expand the talent pool as well as addressing gaps in the docs that are very hard to see by maintainers.
  3. CNCF technical writer could hold office hours and help triage doc bugs, review information architecture, and other advice.  
  4. Tell projects there is a budge of YY hours of a technical writer -- they just need to tag doc issues as "help wanted" and make sure their contributor guide includes appropriate context for how people can contribute to the docs. 
I appreciate that the CNCF TOC is thinking about this!

Sarah


On Tue, May 21, 2019 at 9:33 AM Liz Rice <liz@...> wrote:
Great articulation, thank you Brian. IMO this adds more weight to the argument for hiring another writer to help the projects with these doc challenges. 


On 20 May 2019, at 20:11, Michelle Noorali <michelle.noorali@...> wrote:

Thank you Brian. That’s a really good point.

On May 20, 2019, at 6:41 PM, Brian Grant via Lists.Cncf.Io <briangrant=google.com@...> wrote:

The challenge of documentation was mischaracterized in the GB/TOC meeting today.

It's less that contributors don't want to produce good documentation, but that it requires specialized expertise to do so. Issues like:
  • Information architecture
  • Navigation hierarchy and SEO to make documents sufficiently discoverable
  • What types of documents are needed and what structure and content they should have
  • Identifying target audiences and user scenarios that need to be represented in tutorials and how-to documents
  • Documentation versioning
  • Site management and analytics
  • Internationalization and accessibility
  • Mobile and web layouts
  • Tools and services available for publishing/hosting documentation
  • Processes for accepting contributions and keeping technical content up to date
Producing and maintaining documentation is hard.
Join cncf-toc@lists.cncf.io to automatically receive all group messages.