Add an issue template for documentation

[yb66]

I put in a pull request the other day to add docs to a method with none. I spent too long trying to decide which issue template to use (are missing docs a bug? A language feature? My brain almost crashed trying to decide!:) and as it was a small change @straight-shoota suggested I could've skipped opening an issue, which I agree with but only did as the contribution guidelines say to always do "unless it is a minor fix". One man's minor fix is another's rejected PR…

So, I propose a new issue template (added below), just for doc changes. My reasoning is:

• It clears up any confusion
• It follows the contrib guidelines
• Reviewers know it shouldn't touch code and therefore might be an easier/quicker review. That's nice.
• Newcomers wishing to contribute can see an obvious low-hanging-fruit path to contributing (let's be honest, even with friendly people such as yourselves it's still scary putting forth changes)
• It might encourage more/better documentation.
• Issues like this are better labelled as documentation than bug or feature, why not automate it

And, I've been using the API docs a lot lately (I've the memory of a goldfish so I will continue to) and saw lots I'd like to add, having a button would be nice :)

This is the template:

## Documentation Improvement

This is for documentation only, no changes to code!

Please state what you think needs changing, or if it's for a pull request, how this change would improve the docs (e.g. there were none, clarification, better examples etc)

Any thoughts?

Regards,
iain

[analogsalad]

I've sent my first PR (adding missing docs) yesterday, and it was pretty straightforward. The issue originated at #12048 and my PR was #12530, you can skim through and maybe it'll give you an idea.

In any case, once the PR was sent I was mentored all the way with great feedback so there's really nothing to be afraid of 😄.

In my experience, reading CONTRIBUTING.md, engaging the team in an issue, opening a PR and following regular Git flow was a smooth ride.

[straight-shoota]

I don't think it's a good idea to add too many specialized options to the list. It would just become overwhelming. There are already 6 items which I see as a lot.

IMO this should fall under Language Improvement Discussion. Perhaps the description is not clear enough for that, though.
So perhaps we can change the label and description in a way that it better communicates this is a very generic option. It basically catches anything that is not a bug report or a specific feature request.

[yb66]

@analogsalad

In any case, once the PR was sent I was mentored all the way with great feedback so there's really nothing to be afraid of

Acknowledging a good experience after the fact and believing you'll have a good experience beforehand are two separate things. If you're telling me that the Crystal team are friendly and helpful, I agree. If you're telling me that you've never encountered strangely rude and unhelpful resistance to a high quality or (to your mind) uncontroversial suggestion of any size from an open source project, then I wish I had your luck. On this point, the point is to make it easier for newcomers.

@straight-shoota I disagree about the number of buttons (as an example I like, Rust's choices are good) but that could well be in the realm of preference so perhaps your suggestion is best.

Instead of

I want to start a new discussion about improving the language.

how about?

I want to start a new discussion about improving the language (if you're not sure what type of issue you have, pick this one)

If we widen it out, Language Improvement Discussion might be better termed Language/Project Improvement Discussion.

Regards,
iain

[analogsalad]

Acknowledging a good experience after the fact and believing you'll have a good experience beforehand are two separate things. If you're telling me that the Crystal team are friendly and helpful, I agree. If you're telling me that you've never encountered...

@yb66, let me clarify.

On this point, the point is to make it easier for newcomers.

I'm a newcomer to this project, and if you'll allow me, I'm sharing a fresh experience I've had. Please try not to read further into this simple feedback. I'll repeat myself just in case:

I found it extremely easy to contribute documentation to this project and I don't think we need to further complicate the process by adding documentation that will surely go stale and create bureaucratic burden for prospective contributors.

[straight-shoota]

as an example I like, Rust's choices are good

Honestly, I feel overwhelmed by that huge amount of choices.

It looks like the more relevant options, especially for uninitiated users, are at the top. Towards the bottom are more specialist choices. This is however contradicted by the options pointing to external links (aka contact_links) located at the very bottom. I think this is entirely on GitHub, though. These links (vulnerability, question, feature request) are certainly some of the most important ones for newcomers. Yet they're hidden away below the fold on a typical screen size. So I think that's another argument for keeping the list of choices short.

The Blank Issue choice serves as an easy way out if you don't know what to choose. I like that. It's just GitHub's default option (enabled with blank_issues_enabled: true) but we can make a custom one as well.
Maybe we could copy that as a replacement for Language Discussion?

[straight-shoota]

I've collected some statistics, just to see how much the options are used. I looked at the issues created since the start of this year (2022) and their current labels. So it does not exactly represent the choices made at the issue templates selection because labels are often altered afterwards by moderators. But it should be close enough.

As a base line, 381 issues have been created this year. 214 of them are bug reports. 77 of them are feature requests and 72 labeled as discussion.
For comparison, only 12 issues labeled as docs have been created. There is currently no option for this which likely accounts for some under-representation.

So I would say the choices we present are pretty good in covering the most common cases.

[straight-shoota]

We can certainly make improvements, but I think the overall selection of choices is good.

Language Improvement Discussion is a bit of an odd item and might be cause for confusion. I had already mentioned that when the issue templates were initially introduced: #8934 (comment)

Picking up on the definition I used above ("It basically catches anything that is not a bug report or a specific feature request.") I would suggest to move it more toward Rust's Blank Issue. Maybe call it exactly that? And move it to the top?
And probably don't apply any label (moderators can add discussion if it's actually a discussion).
As a description, maybe the suggestion from #12534 (comment) would fit?

I want to start a new discussion about improving the language (if you're not sure what type of issue you have, pick this one)

[beta-ziliani]

I agree with everything except that I wouldn't move it to the top. It seems better to have Bug, Feature, Anything else. Thanks @yb66 for bringing the issue!

[yb66]

@analogsalad I know many professional developers who never contribute to open source or will never again, because of the difficulties they may face. I want to help them overcome their anxiety and make things as easy as possible for them. I may be right in my proposals for that, or I may be wrong, but in my experience it works for me helps absolutely no one and is rarely relevant, and here, not at all.

As to this:

I don't think we need to further complicate the process by adding documentation that will surely go stale and create bureaucratic burden for prospective contributors.

If the documentation button that's there to make documentation changes easier "surely go[es] stale" then I think we can all pack up and leave for another project because that's a canary in the coalmine if ever I heard one.

[yb66]

As @straight-shoota has brought up the level, I did some digging around.

Projects that have some kind of documentation button:

• Python
• Go
• Rust
• Zig
• PHP
• Haskell

Projects with a miscellaneous (or similar) button:

• Ruby
• Elixir
• Haskell

Projects with neither:

• Typescript
• Nim
• Scala
• Swift
• Julia

That's all either Github or stuff I have an account with, there's plenty of others like Kotlin and D that aren't using Github (and Ruby, though several sub-projects are using Github but if I start down that track I'll never finish!)

Without access to their stats/experience, and as each project has its own needs, this may mean little.

Language Improvement Discussion is a bit of an odd item

I agree, but some of those project have this though many shuffle it off to a forum.

I would suggest to move it more toward Rust's Blank Issue. Maybe call it exactly that? And move it to the top?

Sounds good. The language Elixir use (link above) seems slightly better to me though, worth considering?

Report an issue
Tell us about something that is not working the way we (probably) intend
Get started (button text)