Add feedback links to all the files #11317
Conversation
| PS C:\enlistments\core-setup> darc verify | ||
| Dependency verification succeeded. | ||
| ``` | ||
|
|
There was a problem hiding this comment.
For these long docs, I don't know if I think anyone would get down to the very bottom of the page. Should we consider putting it at the top, so they see it early, and if it was helpful/not they could come back up to it?
There was a problem hiding this comment.
(I almost wonder for this doc specifically, if having a feedback link per section might be better, so we could shorten it to only the things people actually use)
There was a problem hiding this comment.
Right now I made helix-admin that can auto generate them, so it can put them at the top if we want. Though generally you can't know if something is useless until you've read it... which means to give feedback you'd have to scroll back to the top after failing to find something. We could put it in... both places? It's a little weird for it to be before the title of the doc though... I think that looks weird... Hrm...
(The links can also be moved/added manually, they are just boring markdown blobs, nothing fancy)
There was a problem hiding this comment.
Per section could be interesting. I'm not sure that a user would know that it was section specific... but also that doesn't really matter. Wow this doc is long...
There was a problem hiding this comment.
I think what I'm thinking about is that, in particular for something like Darc.md, you might have the following flow:
- Open the doc.
- Scroll the doc for the subsection you are interested in (like, I need to update a subscription, find "subscription" in doc).
- Follow the instructions in the subsection
- Find it helpful, close doc
It's one of those weird ones where if you've made your way to it, you're going for a very specific reason "I need to do X", and you don't actually read the whole thing, but could find it helpful
There was a problem hiding this comment.
Could it go under the title?
There was a problem hiding this comment.
Per section could be interesting. I'm not sure that a user would know that it was section specific... but also that doesn't really matter. Wow this doc is long...
very long
There was a problem hiding this comment.
"Under the title" is a little hard for me to detect automatically. :-) I wonder if we could have a less intrusive section level one...
|
How will the results be presented? |
|
@garath All feedback tracking data is just a pile of customEvents in App Insights, so it's pretty easy to build whatever visualizers we want. It's hard to know what a good visualization is without the data first (are we seeing 5 views a day, or 5,000?... are they evenly distributed or all to a handful of pages). I assume it will end up on some PowerBI dashboard somewhere. :-) The of the times someone clicks the up/down and writes up text, it creates an issue that does the AzDO -> GitHub bounce, which is unfortunate, but I think necessary. |
|
I'm going to try it this way for now... I'm worried about putting it at the top, since it will push useful information down. It's not perfect, but at the bottom should be unobtrusive and accomplish our goals, and we can make it more complicated later. :-) |
|
@garath , @michellemcdaniel do either of you have any complaints about giving this a try for now (and would one of you be willing to approve the review?) |
|
Let's give it a spin! |
3 participants
Feedback links in all our documentation!