Re: the challenge of documentation
toggle quoted message Show quoted text
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.
I appreciate that the CNCF TOC is thinking about this!
On Tue, May 21, 2019 at 9:33 AM Liz Rice <liz@...> wrote: