Date   

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.


Re: the challenge of documentation

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. 


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.


Re: the challenge of documentation

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:

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.


[RESULT] tikv moving to incubation (APPROVED)

Chris Aniszczyk
 


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:
  • 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.


Re: [VOTE] tikv moving to incubation

Matt Klein
 

+1 binding

On Tue, May 14, 2019 at 9:05 AM Chris Aniszczyk <caniszczyk@...> wrote:
tikv has requested to move to the incubation maturity level. Xiang Li from the TOC has performed due diligence and called the vote:
https://docs.google.com/document/d/1isLh8e5D0pAgocbj2ht_ZbZ5MORN3fFD-98tCsVu0rM/edit
https://all.devstats.cncf.io/d/54/project-health-table?orgId=1&var-repogroup_name=TiKV

Please vote (+1/0/-1) by replying to this thread; the full proposal
located here: https://github.com/cncf/toc/pull/221

Remember that the TOC has binding votes only, but we do appreciate
non-binding votes from the community as a sign of support!

--
Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] tikv moving to incubation

Michelle Noorali
 

+1 binding


From: cncf-toc@... <cncf-toc@...> on behalf of Davanum Srinivas via Lists.Cncf.Io <davanum=gmail.com@...>
Sent: Friday, May 17, 2019 6:59 AM
To: Brendan Burns
Cc: cncf-toc@...
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation
 
+1 (non-binding)

On Thu, May 16, 2019 at 11:24 PM Brendan Burns via Lists.Cncf.Io <bburns=microsoft.com@...> wrote:
+1, binding.



From: cncf-toc@... <cncf-toc@...> on behalf of Liz Rice via Lists.Cncf.Io <liz=lizrice.com@...>
Sent: Thursday, May 16, 2019 1:29 AM
To: CNCF TOC
Cc: cncf-toc@...
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation
 
+1 binding 

Liz
On 16 May 2019, 08:14 +0100, Brewer, Jeff via Lists.Cncf.Io <jeff_brewer=intuit.com@...>, wrote:

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Xu Wang
Sent: Tuesday, May 14, 2019 7:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation

 

This email is from an external sender.

 

+1 non-binding

 

On Wed, May 15, 2019 at 10:26 AM Haining Zhang <hi@...> wrote:

+1 nb

On 5/15/19 2:26 AM, Dongxu Huang wrote:

Thank you!


 

--

Xu Wang

Senior Staff Engineer at AntFin

A member of Kata Containers project

github/twitter/wechat: @gnawux



--
Davanum Srinivas :: https://twitter.com/dims


Re: [VOTE] tikv moving to incubation

Davanum Srinivas
 

+1 (non-binding)

On Thu, May 16, 2019 at 11:24 PM Brendan Burns via Lists.Cncf.Io <bburns=microsoft.com@...> wrote:
+1, binding.



From: cncf-toc@... <cncf-toc@...> on behalf of Liz Rice via Lists.Cncf.Io <liz=lizrice.com@...>
Sent: Thursday, May 16, 2019 1:29 AM
To: CNCF TOC
Cc: cncf-toc@...
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation
 
+1 binding 

Liz
On 16 May 2019, 08:14 +0100, Brewer, Jeff via Lists.Cncf.Io <jeff_brewer=intuit.com@...>, wrote:

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Xu Wang
Sent: Tuesday, May 14, 2019 7:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation

 

This email is from an external sender.

 

+1 non-binding

 

On Wed, May 15, 2019 at 10:26 AM Haining Zhang <hi@...> wrote:

+1 nb

On 5/15/19 2:26 AM, Dongxu Huang wrote:

Thank you!


 

--

Xu Wang

Senior Staff Engineer at AntFin

A member of Kata Containers project

github/twitter/wechat: @gnawux



--
Davanum Srinivas :: https://twitter.com/dims


Re: [VOTE] tikv moving to incubation

"shidaqiu2018
 

+1 non-binding


------------------ Original ------------------
From: Xing Yang <xingyang105@...>
Date: 周三,5月 15,2019 07:06
To: Chris Aniszczyk <caniszczyk@...>
Cc: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation

+1 non-binding

On Tue, May 14, 2019 at 12:05 PM Chris Aniszczyk <caniszczyk@...> wrote:
tikv has requested to move to the incubation maturity level. Xiang Li from the TOC has performed due diligence and called the vote:
https://docs.google.com/document/d/1isLh8e5D0pAgocbj2ht_ZbZ5MORN3fFD-98tCsVu0rM/edit
https://all.devstats.cncf.io/d/54/project-health-table?orgId=1&var-repogroup_name=TiKV

Please vote (+1/0/-1) by replying to this thread; the full proposal
located here: https://github.com/cncf/toc/pull/221

Remember that the TOC has binding votes only, but we do appreciate
non-binding votes from the community as a sign of support!

--
Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] tikv moving to incubation

Gou Rao <grao@...>
 

+1 non-binding

On Tue, May 14, 2019 at 9:05 AM Chris Aniszczyk <caniszczyk@...> wrote:
tikv has requested to move to the incubation maturity level. Xiang Li from the TOC has performed due diligence and called the vote:
https://docs.google.com/document/d/1isLh8e5D0pAgocbj2ht_ZbZ5MORN3fFD-98tCsVu0rM/edit
https://all.devstats.cncf.io/d/54/project-health-table?orgId=1&var-repogroup_name=TiKV

Please vote (+1/0/-1) by replying to this thread; the full proposal
located here: https://github.com/cncf/toc/pull/221

Remember that the TOC has binding votes only, but we do appreciate
non-binding votes from the community as a sign of support!

--
Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] tikv moving to incubation

Brendan Burns
 

+1, binding.



From: cncf-toc@... <cncf-toc@...> on behalf of Liz Rice via Lists.Cncf.Io <liz=lizrice.com@...>
Sent: Thursday, May 16, 2019 1:29 AM
To: CNCF TOC
Cc: cncf-toc@...
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation
 
+1 binding 

Liz
On 16 May 2019, 08:14 +0100, Brewer, Jeff via Lists.Cncf.Io <jeff_brewer=intuit.com@...>, wrote:

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Xu Wang
Sent: Tuesday, May 14, 2019 7:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation

 

This email is from an external sender.

 

+1 non-binding

 

On Wed, May 15, 2019 at 10:26 AM Haining Zhang <hi@...> wrote:

+1 nb

On 5/15/19 2:26 AM, Dongxu Huang wrote:

Thank you!


 

--

Xu Wang

Senior Staff Engineer at AntFin

A member of Kata Containers project

github/twitter/wechat: @gnawux


CNCF Telecom User Group Kickoff

Cheryl Hung <chung@...>
 

Please see the draft slide deck for our kickoff next week of the Telecom User Group. If other operators or vendors would like to propose work items, please respond privately to me. 

Kick-off meeting
Twice-a-month calls
Private mailing list
Cheers,
Cheryl

--
Director of Ecosystem, Cloud Native Computing Foundation


Re: [VOTE] CNCF Storage SIG

Jimmy Song <jimmysong@...>
 

+1 non-binding
---------------------------------------
Best Regards.
 
Jimmy Song(宋净超)

Developer Advocate at Ant Financial
CNCF Ambassador
Co-founder of ServiceMesher community
 
WeChat: jimmysong



On May 16, 2019, at 8:21 AM, 刘海锋 <bjliuhaifeng@...> wrote:


+1 non binding 

— Haifeng Liu 

在 2019年5月16日,上午6:52,Matt Klein <mattklein123@...> 写道:

+1 binding.

On Tue, May 14, 2019 at 8:41 AM Chris Aniszczyk <caniszczyk@...> wrote:
A new CNCF Storage SIG has been proposed with Xiang Li as the TOC liaison.

Co-Chairs: Alex Chircop, Quinton Hoole
Tech Leads: Saad Ali, Xing Yang, Sugu Sougoumarane

Please vote (+1/0/-1) by replying to this thread; the full proposal located here: https://github.com/cncf/toc/pull/234

Remember that the TOC has binding votes only, but we do appreciate non-binding votes from the community as a sign of support!

--
Chris Aniszczyk (@cra) | +1-512-961-6719




Re: [VOTE] CNCF Storage SIG

Liz Rice
 

+1 binding

Liz

On 16 May 2019, at 07:52, Brewer, Jeff via Lists.Cncf.Io <jeff_brewer=intuit.com@...> wrote:

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Wei Ding
Sent: Wednesday, May 15, 2019 9:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] CNCF Storage SIG

 

This email is from an external sender.

 

+1 non-binding

 

丁尉    Wei Ding   

京东零售JDR   技术与数据中台   硅谷中台研发部

Phone+1 814-321-6472

Email wei.ding@...

Address 675 E Middlefield Rd, Mountain View, CA 94043

<image001.png>

 

 

From: <cncf-toc@...> on behalf of Chris Aniszczyk <caniszczyk@...>
Date: Tuesday, May 14, 2019 at 8:41 AM
To: CNCF TOC <cncf-toc@...>
Subject: [cncf-toc] [VOTE] CNCF Storage SIG

 

A new CNCF Storage SIG has been proposed with Xiang Li as the TOC liaison.

 

Co-Chairs: Alex Chircop, Quinton Hoole

Tech Leads: Saad Ali, Xing Yang, Sugu Sougoumarane


Please vote (+1/0/-1) by replying to this thread; the full proposal located here: https://github.com/cncf/toc/pull/234

Remember that the TOC has binding votes only, but we do appreciate non-binding votes from the community as a sign of support!

 

--

Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] tikv moving to incubation

Liz Rice
 

+1 binding 

Liz

On 16 May 2019, 08:14 +0100, Brewer, Jeff via Lists.Cncf.Io <jeff_brewer=intuit.com@...>, wrote:

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Xu Wang
Sent: Tuesday, May 14, 2019 7:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation

 

This email is from an external sender.

 

+1 non-binding

 

On Wed, May 15, 2019 at 10:26 AM Haining Zhang <hi@...> wrote:

+1 nb

On 5/15/19 2:26 AM, Dongxu Huang wrote:

Thank you!


 

--

Xu Wang

Senior Staff Engineer at AntFin

A member of Kata Containers project

github/twitter/wechat: @gnawux


Re: [VOTE] tikv moving to incubation

Brewer, Jeff
 

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Xu Wang
Sent: Tuesday, May 14, 2019 7:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] tikv moving to incubation

 

This email is from an external sender.

 

+1 non-binding

 

On Wed, May 15, 2019 at 10:26 AM Haining Zhang <hi@...> wrote:

+1 nb

On 5/15/19 2:26 AM, Dongxu Huang wrote:

Thank you!


 

--

Xu Wang

Senior Staff Engineer at AntFin

A member of Kata Containers project

github/twitter/wechat: @gnawux


Re: [VOTE] CNCF Storage SIG

Brewer, Jeff
 

+1 binding

 

From: cncf-toc@... <cncf-toc@...> On Behalf Of Wei Ding
Sent: Wednesday, May 15, 2019 9:57 PM
To: CNCF TOC <cncf-toc@...>
Subject: Re: [cncf-toc] [VOTE] CNCF Storage SIG

 

This email is from an external sender.

 

+1 non-binding

 

丁尉    Wei Ding   

京东零售JDR   技术与数据中台   硅谷中台研发部

Phone+1 814-321-6472

Email wei.ding@...

Address 675 E Middlefield Rd, Mountain View, CA 94043

 

 

From: <cncf-toc@...> on behalf of Chris Aniszczyk <caniszczyk@...>
Date: Tuesday, May 14, 2019 at 8:41 AM
To: CNCF TOC <cncf-toc@...>
Subject: [cncf-toc] [VOTE] CNCF Storage SIG

 

A new CNCF Storage SIG has been proposed with Xiang Li as the TOC liaison.

 

Co-Chairs: Alex Chircop, Quinton Hoole

Tech Leads: Saad Ali, Xing Yang, Sugu Sougoumarane


Please vote (+1/0/-1) by replying to this thread; the full proposal located here: https://github.com/cncf/toc/pull/234

Remember that the TOC has binding votes only, but we do appreciate non-binding votes from the community as a sign of support!

 

--

Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] CNCF Storage SIG

Wei Ding
 

+1 non-binding

 

丁尉    Wei Ding   

京东零售JDR   技术与数据中台   硅谷中台研发部

Phone+1 814-321-6472

Email wei.ding@...

Address 675 E Middlefield Rd, Mountain View, CA 94043

 

 

From: <cncf-toc@...> on behalf of Chris Aniszczyk <caniszczyk@...>
Date: Tuesday, May 14, 2019 at 8:41 AM
To: CNCF TOC <cncf-toc@...>
Subject: [cncf-toc] [VOTE] CNCF Storage SIG

 

A new CNCF Storage SIG has been proposed with Xiang Li as the TOC liaison.

 

Co-Chairs: Alex Chircop, Quinton Hoole

Tech Leads: Saad Ali, Xing Yang, Sugu Sougoumarane


Please vote (+1/0/-1) by replying to this thread; the full proposal located here: https://github.com/cncf/toc/pull/234

Remember that the TOC has binding votes only, but we do appreciate non-binding votes from the community as a sign of support!

 

--

Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] CNCF Storage SIG

Niraj Tolia
 

+1 non-binding


On Tue, May 14, 2019 at 8:41 AM Chris Aniszczyk <caniszczyk@...> wrote:
A new CNCF Storage SIG has been proposed with Xiang Li as the TOC liaison.

Co-Chairs: Alex Chircop, Quinton Hoole
Tech Leads: Saad Ali, Xing Yang, Sugu Sougoumarane

Please vote (+1/0/-1) by replying to this thread; the full proposal located here: https://github.com/cncf/toc/pull/234

Remember that the TOC has binding votes only, but we do appreciate non-binding votes from the community as a sign of support!

--
Chris Aniszczyk (@cra) | +1-512-961-6719


Re: [VOTE] CNCF Storage SIG

Karl Wehden
 

+1 nb. 

On Wed, May 15, 2019 at 10:19 PM GolfenGuo <golfen.guo@...> wrote:

+1 non-binding

 

 

Thanks

--

郭峰  Golfen Guo

Co-founder & CTO

+86 18016427071

Shanghai DaoCloud Network Technology Co,. Ltd

#Your Containers. Delivered!#

 

发件人: <cncf-toc@...> 代表 Chris Aniszczyk <caniszczyk@...>
日期: 2019514 星期二 下午11:41
收件人: CNCF TOC <cncf-toc@...>
主题: [cncf-toc] [VOTE] CNCF Storage SIG

 

A new CNCF Storage SIG has been proposed with Xiang Li as the TOC liaison.

 

Co-Chairs: Alex Chircop, Quinton Hoole

Tech Leads: Saad Ali, Xing Yang, Sugu Sougoumarane


Please vote (+1/0/-1) by replying to this thread; the full proposal located here: https://github.com/cncf/toc/pull/234

Remember that the TOC has binding votes only, but we do appreciate non-binding votes from the community as a sign of support!

 

--

Chris Aniszczyk (@cra) | +1-512-961-6719


本邮件及附件含 DaoCloud 保密信息,仅限发送给上面地址中列出的个人或群组,禁止任何其他人以任何形式使用本邮件中的信息。若误收本邮件,请务必通知发送人并直接删去,不得使用、传播或复制本邮件。



--

Karl Wehden
VP of Product Strategy / Marketing
karl.wehden@...
M: +1 206.669.1494


4261 - 4280 of 7554