The Good Docs WG

šŸ‘„ Working Groups Documentation
1

Who writes, uses, and updates the docs? What do sustainable-first docs look like? How can we write better ones?

Bottom liner: Chris Chinchilla, @pia

Issues & Pull Requests: Add docs group #251

3 Likes
2

I donā€™t see traction here yet but Iā€™m interested and enthusiastic. I know a few different corners of the open source world I might be able to rope into this conversation, but I do not have bandwidth to be a bottom liner or lead this group.

1 Like
3

Sorry @jwf I didnā€™t even know this forum existed, there is some slow traction.

First tell any projects looking for help to sign up for an office hours session.

Next steps are also to compile resources, there are already a lot of these around, so I donā€™t really want to replicate them, more offer more specific advice and compile that for people to see, which I think might be more useful.

3 Likes
4

May the 4th, 2020 meetings ummary

Participants:

  • Richard Littauer
  • Chris Ward
  • Javier Canovasi
  • Justin Flory

Notes

  • Things that would be nice:

    • Best practices docs (could be moved over from kauri)
    • Make a guide/course, that can live here
    • If other people add to it, would be great

  • Office hours concept:

    • Everyoneā€™s requirements are different, so they just want to ask questions
    • Useful for building FAQs
    • How to find writers for small projects
    • Other projects like Google Season of Docs

  • Sustainability:

    • Help projects that want to improve, but donā€™t have resources
    • Not enough people who want to/are good at docs to help all of the projects
    • So a good outcome is:
      • To help technical people do what they do
      • Connect non-tech writers who never have enough work
    • Docs need a newcomers perspective, sometimes

  • Dimensions on sustainability

Action Items

3 Likes
5

Moved the session notes into the repo! :slight_smile:

1 Like
6

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
7

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
8

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
9

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
10

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
11

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

3 Likes
12

Thanks, Erin!

Chris and JWF: How did reaching out go?

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

13

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

14

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
15

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

2 Likes
16

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

17

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

18

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.

19

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

20

@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