The Good Docs WG

Moved the session notes into the repo! :slight_smile:

1 Like

I am interested in working on and collaborating on best practice templates and tools for documentation writers. For example, I have a Sphinx-docs template repository with Travis CI, ReadTheDocs publishing, and more out of the box. It would be nice to collaborate on these kinds of projects (for me) with other folks.

This is one of my personal interests in this working group.

1 Like

Good call. I actually have a few of these two scattered about the interweb, so would be good to find them a home. I am however, not sure if that would be in the Sustain organisation, or somewhere else, but at the very least, it’s a pace to list those available.

1 Like

Chris has uploaded his rough draft of the manual to the repo. If anyone wants to take a look at it before next Monday, it’s available here: https://github.com/sustainers/docs

2 Likes

Good starting point.

I particularly like the Documentation Structure page, which I think is core. Also, I guess it is somewhat the scaffolding of issue 3 and issue 4. If needed, I can help to advance those issues.

1 Like

Hi all, thought I would follow up and share my own update. The working group met on Monday, 18 May. In attendance we had @ChrisChinchilla, @jlcanovas, @Erioldoesdesign, @esperluette, @RichardLitt, and @jdorfman (hope I didn’t forget anyone!). Here are the notes from our shared HackMD pad:

Exploration questions

  1. (JWF) WG goals?
  2. (JWF) Scope of WG?
  3. (JWF) Did Erin mention working on some sort of “collaboration” best practices docs for Good Docs Project? (thinking of Javi and Governance Readiness WG)

What are people hoping to get out of this WG?

  • Crossover of design and docs (design documentation)
  • Helping projects fill the common missing gaps in engaging with a project from a docs perspective (how to contact, issue templates etc)
  • What do mean by open source project documentation
    • Do we have a common vocabulary yet? Do you and I mean the same thing when we say “open source docs”?
  • What is the overlap between this WG, WTD, GDP etc, and how do they all fit together (or not)?

Possible paths forward

  1. Collaborating with other docs communities, and starting a Sustainability working group in those existing communities instead of pushing this work from Sustain
  2. Starting docs to keep them “maintainable”
  3. Defining what sustainability in open source docs means
    • What makes docs sustainable?
    • “Checklist” to test if docs are sustainable / cared about? :slight_smile:
    • (@jwf) …Principles of Sustainable Docs? :sweat_smile:
    • How to keep “docs going”, or up to date, maintained, cared about
    • (@esperluette) Content maintainability, technical maintainability, community maintainability
  4. (@Erioldoesdesign) Design documentation: Something underrepresented in open source to-date
    • Might not be what we traditionally think of docs
    • Could use a community-agreed definition

Action items for next time

  • @ChrisChinchilla, @esperluette, @jwf: Reach out to existing groups (WTD (Chris), GDP (Erin), Fedora/Red Hat (JWF))
    • We are a WG of sustain looking into how to help OSS projects “sustain” their docs. What does sustaining docs mean to you?
    • Chris to focus the office hours on these subjects, and invite others
    • Due date: 2020-06-01
  • @Erioldoesdesign: Bring up docs with the Sustain design community

hi folks! I shared with the Good Docs Project in this week’s meeting (3 June) and linked them to this doc.

3 Likes

Thanks, Erin!

Chris and JWF: How did reaching out go?

@Erioldoesdesign, did you mean the Sustain group in that comment?

Do you mean:

@Erioldoesdesign: Bring up docs with the Sustain design community

Yes I brought this up with the design & ux sustain oss WG :slight_smile: we spoke about it last meeting and notes were taken

I did a signal boost on the Fedora Documentation mailing list and added some of our working group meetings to the Fedora Docs scheduling calendar. Doesn’t seem like there were a lot of bites just yet, but I think it might help to narrow down our possible paths forward to make it easier for folks to climb on to these discussions.

1 Like

Is there a WG for docs meeting today? I have a placeholder in my calendar for 4pm UK time

2 Likes

There should be. I’m double checking with @ChrisChinchilla. I won’t be able to make it due to a conflict, unfortunately.

I also have it on my calendar, but I have a one-time conflict today and won’t be able to join either.

There is indeed, but it will be a slim meeting I think. I’ll still run it though, as I have things I want to report on, and move on with.

Ah I don’t have the call joining instructions If I could get them that’d be lovely @ChrisChinchilla

@esperluette The project I mentioned that I use as an example of ‘minimum indication of welcoming design contribution’ is: https://github.com/pa11y/pa11y

https://pa11y.org/contributing/designers/

Specifically this statement: “Pa11y hasn’t had loads of attention in this area and we’d love you to join us. It’s time to bring some thought and consistency to our project designs”

We also discussed design + docs in the last sustaining Design & UX WG: Design & UX working group

2 Likes

15 June Meeting Summary

attending: Chris, Eriol, Erin

Notes:

  • problem is that OSS projects need better docs

  • one discrete, significant problem is the lack of contributor guides

  • we can work on this – some overlap with governance group (Chris to follow up)

  • Contributor Guides should reflect all ways of contributing:

    • code
    • docs
    • design
    • marketing
    • speakers
    • community work
    • money
  • should be focused on contributor responsibilities use cases:

    • to contribute, you need to agree to Code of Conduct, license, etc. (link out as necessary)
    • should have different degrees of background info for different levels of contributors (design contributors might not be familiar with pull requests or licenses)
  • should have templates for process docs

  • for future discussion:

    • where will this guide live? (maybe The Good Docs Project?)
    • who should be consulted?
    • who will maintain it going forward?
    • who at the Gits (Github, Gitlab) would be a good person to connect with?

Action items:

  • Chris to set up repo and invite WG members
2 Likes

This task is in progress

Oh I came across Pa11y in preparation for a testing talk, it’s great!

2 Likes

Hey folks. I dropped the ball on notes when I got pulled into other meetings yesterday. However, I added a short addition to the Sustain 2020 Report draft in the Sustain organizers meeting. I’m sharing the excerpt I added to the Good Docs section of the report here:

This Working Group also remained active since the Sustain 2020 Summit, with meetings occurring roughly once a month since March 2020. While exploring future areas of collaboration, the Good Docs W.G. realized that documentation is an important and critical piece not just to our own Working Group, but also several others. Documentation is often a central part of equitable knowledge-transfer of skills and community norms.

At the time of publication, the Good Docs Working Group is currently exploring ways to support other Sustain OSS Working Groups by bringing a documentation perspective to active conversations already happening in the wider community.

The CHAOSS badging project also came up (cc: @GeorgLink):

We verbally discussed some next steps, but tragically I did not get them down. Some help on highlighting any major points from our meeting is appreciated!

1 Like