Documenting corner cases

[Rob Nelson]

Some of us (and I seem to be really good at this) run into edge cases that others often do not. The information is then stored in some obscure Jira ticket, GitHub issue, or just in someone's head. When the next person runs into the same corner case, if they're lucky, they'll stumble onto an error message that is in the previous ticket/issue and find the answer. However, in many cases, that user will end up not finding the issue, or not seeing the relation between that issue and the user's situation.

If you had a preference for where you would expect to find corner cases documented, what would that be? I'll suggest a few common places to start:

A) Jira tickets at https://tickets.puppetlabs.com/browse (e.g. https://tickets.puppetlabs.com/browse/PUP-6106)
B) Github issues on the project (e.g. https://github.com/rodjek/rspec-puppet/issues/377)
C) As an addendum on the closest-related official documentation (e.g. the very last paragraph at https://docs.puppet.com/hiera/1/lookup_types.html#example)

Please write in any other locations you would look for it. I'm very interested in making sure that others don't feel the same pains I do, so want to be sure to get the most eyes I can on documentation.

Thanks,

Rob Nelson

[Alex Harvey]

A good question and I have thought about this a lot.

I'm sure like most, my first search is on Google for the error message, and that will search Jira & Github & public documentation too.  No luck, I'll had quotes to force Google to search for the exact string.  Next I'll search the code using grep and regular expressions, or Github search.  Then it's off to git blame to see if there's any more info.

As far as what I'd expect, rather than hope for, if it's really an edge-case, and the observed behaviour is not designed behaviour, then I'd expect to find it documented in Jira or Github, and I'd expect and hope to not find it mentioned in public documentation.

[Alex Harvey]

And of course there may not be an error message or an output string to search on.  In that case, I would be appreciative to a reporter who spends time thinking about the kinds of search phrases that others might come up with to find the same issue.  Test them, see where they lead.

If they took me to someone's unanswered question on Stack Exchange or Ask.puppetlabs.com or some other forum I'd add links there back to the now-documented issue.

--
You received this message because you are subscribed to a topic in the Google Groups "Puppet Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/puppet-users/-xwPAfgOsTA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to puppet-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-users/7e0aec54-6021-4eeb-a7f7-d21ac5b2ff09%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Rob Nelson]

Thanks for the confirmation of my suspicions!

You received this message because you are subscribed to the Google Groups "Puppet Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to puppet-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/puppet-users/CAF0Ep4Wt5y4Mwd52%2B%3Dww%3DaqeNEr4RMbVkErFZQ%3DBmnQRwZqFLg%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Rob Nelson
rnel...@gmail.com