Clarifying Doc Contribution Workflow

[SilasVM]

Topic

Hi, I am a new contributor and have been working on documentation fixes for the past week with (@thatguyseven, @snwarner22, @OnexiMedina, @emmet0r). We noticed the following advice on the p5.js website:

1. If you're just getting started, one really helpful way you can contribute is by opening issues for documentation needs. If you notice a typo, a missing or broken example, or a function description that is confusing, open an issue for it! Please include a link to the page that needs fixing so we can find it easily.

2. Read through the reference, and look for typos, broken examples, or confusing documentation. If it's a straightforward fix, go ahead and work on it! If it's a more involved question that requires discussion, create an issue.

What is the expected contribution workflow for a documentation fix? So far we have been opening issues, but based on the above don't know if this is necessary for simple edits (typos, capitalization).

We would love to help improve access for new users. If there is interest in clarifying expectations in the Contributor Guidelines, we would love to work on it. If issues are desired for every documentation edit, we could add a Documentation issue template (with automatic tagging), which could make issue-reviewing smoother for stewards and maintainers.

[RandomGamingDev]

This would go well with #6286.

[davepagurek]

I think the distinction between points 1 and 2 is that if you are going to open a PR to fix typos/capitalization, they don't really need discussion, so they don't need an issue. I believe point 1 is saying that if you aren't comfortable making a PR yourself, we still appreciate it if you open an issue to let us know that there's a typo somewhere so that someone can then fix it. We should could clarify the docs to be clearer -- if that's something you're interested in working on, that would be great!

[thatguyseven]

Thank you for clarifying! We are definitely interested in making this part of the documentation a bit more understandable since our group also had a hard time distinguishing what the doc was trying to say. Hopefully our changes can make the project better.

[davepagurek]

Thanks @thatguyseven! I'll assign this to you on behalf of the group.

[thatguyseven]

@davepagurek Do you mind if we also make a template for documentation errors while we are at it? Our group had trouble finding the right issue template to use and we think that having a template for documentation errors that automatically tags the "Documentation" tag would be really helpful. It would save a lot of time and effort for both stewards and contributors.

[davepagurek]

I think that could make sense, although @limzykenneth do you think that would have too many templates? The risk is that with too many, people might not read them all and pick the right one. This is our current set of templates:

I think one more documentation one probably still would be good, but a second opinion would help.

[davepagurek]

This issue got closed from that PR, but I'm reopening it so we can continue the discussion about the docs template 🙂 We can close this again if we decide not to make one.

[limzykenneth]

I think we probably don't want more issue templates. There are some thoughts on moving existing ones off issues and possibly consider using discussions but that's just another forum to maintain (in addition to the Processing forum and Discord). The main thing about issue templates is for mostly automatic triage purposes, since the opened issue looks more or less to us in the list. If something more specific for documentation is required, we can possibly revisit and adapt the "Found a bug" template, maybe rename it to something a bit more generic (not too generic or it will get chosen for things it's not meant for) and tweak the fields in there for documentation.

A slightly unrelated but annoying thing about the issue template list is that they are sorted alphabetically, causing "Discussions" which should probably be the least use one at the top and many issues that should have been one of the others got lump into discussions which we need to triage manually.

[thatguyseven]

@limzykenneth @davepagurek Would you be interested in us making modifications the issue templates so that the discussion template appears at the bottom?

It is possible to change the order of the templates by modifying the filenames of the .yaml files in the .github folder since GitHub orders the templates by alphanumeric order. We could add a number to the beginning the template files so that they can be ordered manually.

[Qianqianye]

Thank you @SilasVM and @thatguyseven for bringing it up.

I agree with @limzykenneth that we don't want add too many issue templates, to avoid confusion. 3-4 issue templates probably should be the maximum. However, I do see the needs to open issues for documentations only, like the doc issue template in node.js GitHub repo. We're open to suggestions to improve our current issue template structure to create the space for doc improvement, either by adjusting existing issue template to include descriptions about doc, or adding an issue template for doc only.

While we are on this thread, I'd also like to discussion the following:

1. Is it necessary to distinguish 'Existing Feature Enhancement' and 'New Feature Request'? The two issue templates are quite similar, and sometimes it's hard to tell the difference. How about combining them to just 'Feature Request'?
2. The 'Discussion' issue template was initially created to announce and gather feedback for upcoming releases. We have seen contributors accidentally mis-used 'Discussion' issue template when the issue should be bug, enhancement or feature request. So we've been thinking that we can either add a description to the 'Discussion' issue template to narrow down its scope or rename it to 'Announcement'. What do you think?

Adding a number to the template files sounds like a great idea. We can organize the issue template with numbers after we reach to an agreement in this discussion.

[thatguyseven]

It would be nice to have a verbose indication as to where documentation issues can be reported. Personally, I think it would be fine to add documentation to one of the existing formats and add a small addition to the documentation about which issue template to use.