Encourage documenting features as part of a PR contribution

[afgane]

Stemming from a discussion in prep for a release (#2821 (comment)), I'd like to start a discussion about strongly encouraging contributors to add documentation about features they PR. At a minimum, this encouragement would be just a note in CONTRIBUTING.md file. The other extreme would be a requirement to point to user and/or admin facing docs on the wiki prior to a PR merge. My view is that without proper documentation, many features just see adoption by people waiting for the given feature rather than being discovered by others as well.

The current model of listing features in the release notes is great but those are temporal and once a release is a bit dated, users do not visit those notes much. Also, those notes are not grouped by functionality as proper docs are likely to be. They also tend to be developer centric.

Thoughts on the happy middle ground?

[jmchilton]

In the past I have tried to group related items together in the release notes, I'd encourage anyone who notices items that should be grouped closer together to open PRs or write comments that indicate these things should be grouped closer. I also have traditionally reworded developer-facing PR titles into user-facing or deployer-facing wording - again if you find particular items that are this way in the release notes I'd encourage you to reword them. The release notes should target many audiences - not just developers.

[hexylena]

The other extreme would be a requirement to point to user and/or admin facing docs on the wiki prior to a PR merge

I think it might not be feasible to do this (even though I like the idea on the surface). Too large a number of PRs are so small or not-interesting from an end-user/admin-user perspective that it doesn't make sense to require it for all.

Possible criteria:

• Does it make a visual change to the UI/UX of galaxy
  • Would it be meaningful to the end user that this change has been made? (E.g. no to Composite Datatype upload panel needs text fix on buttons #2591, but yes to List resolver toolshed packages #2750)
• Does it make a change in galaxy.ini that isn't spelling/grammar? → must have admin docs

Might be nice to expand this into a flow chart

[dannon]

I'd assume this, as it stands in theory, would only refer to PRs tagged enhancement/feature, right?

Anything else is going to get out of hand very quickly. And we already have a problem with wiki pages being write-once, read-seldom, rewrite-never.

[dannon]

(sorry, that damn 'close and comment' button)

[hexylena]

@dannon what about

Label	Needs Docs
kind/bug	maybe
kind/enhancement	yes
kind/feature	yes
kind/refactoring	no
kind/testing	no

[afgane]

Personally, I think @erasche's thinking sounds very reasonable. Also, docs associated with a PR don't necessarily need a dedicated page but perhaps a paragraph or similar on an existing page - just something that describes/explains how to use a feature, whether it be by admins or end-users.

[dannon]

@erasche Just perusing https://github.com/galaxyproject/galaxy/issues?q=label%3Akind%2Fenhancement makes me think 'enhancement' should be a maybe at most. And 'bug', I'd say no.

[afgane]

The enhancement should probably be a docs edit if needed, right? That would also help with keeping more docs up to date vs. writing things once and never/rarely updating.

[dannon]

I guess my ideal stance-o-the-project here would be for committers to recognize the fact that to use features, users need instructions, and to ask for them when necessary at merge.

[dannon]

@afgane If you look through the 'enhancements', no, that is not the case.

(not commonly the case, looking through the list of how we currently use the tag, I should have said -- of course there are enhancements where the documentation might need an update)

[jxtx]

On a quick glance it looks like PRs tagged with enhancement that might not need docs are probably mistagged refactorings. Anything that changes any aspect of how Galaxy looks, functions, is configured, etc probably needs docs.

I agree roughly with @erasche's table, but I also think this is hard to legislate. It will always be subjective, but I think we should err on the side of more docs. We are far from there.