Do we need to duplicate issue answers into actual docs?

[shankari]

I propose that if an issue is answered, then unless it is super general, we do not need to reflect it back in "docs".

Reasons:

• extra work - we don't have a dedicated doc person on staff
• danger of docs bitrotting/becoming obsolete if people forget to update while with an issue you can always see the timestamp of the last update and know which one is correct
• docs will get too verbose and confusing if every single possible issue is in the docs

Thoughts?

[bz247]

Yeah, maybe unless many people have the same problem, it should be okay to only answer them in issues.

[jackcsullivan]

Agree that we do not need to reflect it in "docs" as long as it is explicit somewhere in the readme that any users having issues should check the issues tab in the repo (both open and closed issues).

[shankari]

in response to #24 (comment), what do you think should be the threshold for many people?

[MetroPietro]

I agree. However when left in Issues, please note the keywords needed for us to search for the solutions to the problems on our own. RTFM is not sufficient when there are several hundred online "manuals" available for trying to solve questions.

[deepalics0044]

Yes I agree. I think reflecting on docs can be haphazard, we can look into the issues if some information is required.

[jackcsullivan]

@shankari 5 seems like a reasonable number.

[shankari]

@jackcsullivan hm and maybe we can have people vote on confusing issues. Hm, it looks like voting is a frequently requested feature of github but doesn't exist yet.
isaacs/github#9

Any thoughts on how to simulate voting?

[jackcsullivan]

@shankari we could comment a few numbers and people could thumbs up the ones they like.

[shankari]

@jackcsullivan I was talking about voting for issues to highlight that "it was confusing for me and needs to go into the docs"

[bz247]

Or you can upvote issues (emoji on the top right conner of each comment --> thumb-up). Then on the issues tab, top right conner, sort issues by reactions. This can track the popularity of the issues.

[shankari]

@bz247 that sounds like a great idea.
Let's see if others have any comments in the next couple of days, and then we can make the change.
Where should we put the instructions?
docs repository? README?

Also, who wants to do this?

[jackcsullivan]

@shankari Have an issues section under "Contributing" in the main e-mission-docs readme that has instructions for the protocol?