Date
1 - 4 of 4
the challenge of documentation
Brian Grant
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:
Producing and maintaining documentation is hard.
|
|
Michelle Noorali <michelle.noorali@...>
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:
|
|
Liz Rice
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.
toggle quoted messageShow quoted text
On 20 May 2019, at 20:11, Michelle Noorali <michelle.noorali@...> wrote:
|
|
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...
I appreciate that the CNCF TOC is thinking about this! Sarah
On Tue, May 21, 2019 at 9:33 AM Liz Rice <liz@...> wrote:
|
|