Documentation understanding feedbacks

Meta Discussion
,
1

I thing it would be better to have a system where reader can give feedback of how much they understood a section in documentation chapter. This will help us create better documentation system.

  • They can give star ratting to sections that they understand :star:. Total count can be publicly visible for each section headings.

  • They can mark paragraphs/lines of a section part that they could not understand. These annotation can be visible to Julia team only

  • They can comment or ask questions on paragraph.

These feedback counts can then be used for editing or improving documentation. Please suggest your opinions or suggestion for it and hurdles we may have in achieving this.

1 Like
2

Are there any examples of an existing system like this?

1 Like
3

Yes Sir, we can like :+1: a video or comments in youtube and also timestamp a location in video. Star ratings are used in almost every website. :grin:

4

I mean a document-display system that lets anonymous readers highlight and rank particular passages.

1 Like
5

Why not add checkpoints( a short tricky conceptual question ) like in Fundamentals of Physics? If reader is not able to answer it then they should revise last section that contains this checkpoint. I think that it should be easy to include Checkpoints in documentation.

6

Documentation by itself is not interactive, it’s just a bunch of files. If you’re talking about the documentation website, then that’s not much interactive as implemented either. An interactive system would be more complicated, and a feedback system would be even more complicated e.g. YouTube. Anybody can give it a shot, there’s just not much motivation for it.

2 Likes
7

Because the manual is already too long as it is.

While data on how readers perceive individual sections would be valuable, what the manual would benefit the most from is rewriting entire chapters with an editorial eye. This would mean reorganizing, rephrasing, and, in some cases, cutting material. This needs to be done from time to time, but it is a major undertaking.

That would duplicate the functionality of this forum. If users have questions, they should ask them here. “Commenting” on the manual serves no purpose, we need PRs that improve it where needed, not exegesis.

2 Likes
8

You can quote/copy quote lines of Discourse.

image
image998×215 27.2 KB

Can we Quote lines of Julia Documentation so that when we click on quote to open that line or highlight?

9

I know it can be done with Chrome by default at least, and Firefox has an extension too I think

10

The Home Assistant project has a feedback section at the bottom of every documentation page, for example: Understanding Home Energy Management - Home Assistant

afbeelding
afbeelding1053×274 16.1 KB

These links bring you to the right pages in github issues. I think it’s a fantastic system, I’ve used it myself not only to provide feedback but also to make PRs. Often an issue has already been reported.

2 Likes