Add issue-trackers to the doc repos

Anki Suggestions
1

The Anki docs are great – but they could be even better.

Is your feature request related to a problem? Please describe.
There is currently no set place to report or discuss issues in the Anki Manual and FAQ.

  1. When you spot an issue in the docs – typo, confusing text, undocumented changes/updates, outdated text, etc. – your primary options are fix it yourself right now, or ignore it and hope someone else notices it and fixes it.
  2. There is nowhere to propose significant changes to the docs that might merit some discussion and consensus-reaching before someone puts in a lot of editing effort. Similarly, there is nowhere to propose or discuss new FAQ pages.
  3. When new features are rolling out, it’s up to Damien or another developer to document the changes. This doesn’t always happen, and sometimes gets overlooked. No criticism intended here – people are busy and not everyone who enjoys programming also enjoys tech writing! But the end result is “secret” features that users only find out about if they read all the release notes.

Describe the solution you’d like.
Adding issue-trackers to the ankitects/anki-manual and ankitects/faqs repos. Adding report-a-bug links to the Manual and FAQ for easy reporting.

[Or would just one issue-tracker (in anki-manual) be enough/more efficient? Can issues be spun-off to the FAQ repo if the solution would be better to implement there? Maybe someone more familiar with GitHub than I am can share some insight on that.]

Drawbacks to the solution

  • It’s another channel of information (and another vector for complaints), so more overhead for folks who need to monitor those kinds of things.
  • Since there isn’t one already, it seems like there must be a reason it is ill-advised, and I just don’t know what it is.

Describe alternatives you’ve considered.

  • Encouraging folks to post these things (small issues, larger discussions, proposals) in the Forums / adding a Documentation category
    • Most small issues don’t need any discussion, so a separate post here (that can’t be marked completed by the person who submits a fix) seems like overkill.
    • A post or discussion here doesn’t naturally lend itself to inviting someone to fix it in GitHub.
  • Fix them when I find them.
    • For those of us who are active users of the docs, but still GitHub novices, even a little fix can take a lot of effort (and a significant amount of time reminding myself of the right procedures so I don’t mess anything up!). It’s not always an easy ask, especially with fixes that should be made carefully and deliberately to avoid user confusion.
  • Continuing to keep my own secret list of issues I’ve seen users struggle with.
    • In an effort to find my own outside-of-GitHub solution, I started making a note of things I couldn’t really ignore anymore. It turns out that it doesn’t actually fix anything unless I also have time to go back and check them off my list. :person_shrugging:t4:
2 Likes
2

One more drawback: There are people who provide fixes to the manual on their own. If an issue tracker is added, might not they just delegate this to other people in the issue tracker?

edit: How about a Forum thread instead of a category? If you want to edit the manual, you’ll have a ready list of issues with you, instead of having to jump around in different threads.

3

It doesn’t seem very likely to me that someone who is ready and available to fix something would decide to write it up instead – but okay, suppose that happened. Is there a negative outcome at the end of that? Possible-fixer writes an issue instead of fixing it themselves and that’s followed by (a) someone else grabs the issue and fixes it – wonderful, it’s fixed! – or (b) no one else grabs the issue and it remains unfixed. It seems like someone who cared enough about the problem to write up an issue is going to make their way back to make sure it gets fixed. Maybe I’m too optimistic?

Just one post like this, with a stream of comments below it containing every different thing that’s reported? That seems like it would be jumbled and disorganized. There’d be no way to know what had already been fixed, and no way to discuss any of the issues without making the thread ever more jumbled. That seems like it would be worse than having no reporting/tracking system at all.

4

I think so but I don’t mind the experiment. If issue tracker plus link to the tracker in introduction.md later seems to have more demerits, we can always revert back. I also think more people will have a github account than a forum account so the former might be a better choice. And, issues can have labels, can be closed, reopened, closed again. You can link a PR to an issue, and can have “merging PR auto closes linked issue”.

I simply fear that people will 1. expect all issues to be fixed by dae 2. will report things like “you didn’t put a comma in the first sentence of deck-options.md”.

By the by, I remember there was once a issue opened in Anki’s isuue tracker which was referenced in a PR for the manual. Is using that issue tracker accepted, I don’t know.

I agree with you now.

1 Like
5

I’ve enabled issues on the manual repo. Let’s see how that goes for a while before we think about adding it to FAQs as well.

For discussions, I still think the forums might be a better place, as these topics generally don’t require a strong technical background. But I can appreciate the argument for a place to keep track of things that need updating in the future, be it because we’ve made changes that require updates, or because someone doesn’t have the knowledge to file their own PR.

2 Likes