was there any discussion about supporting comments on online doc pages?

was there any discussion about supporting comments on online doc pages?

[Robert P. J. Day]

  my apologies if this topic came up and i missed it ... a colleague
is pondering what to migrate to WRT existing documentation, and i
suggested taking a look at how brilliantly YP is doing it with sphinx;
in particular, she was enthused about the expandable/collapsible ToC
down the left side. the only thing she brought up was the need for
user-suppliable comments on online pages so readers could ask
questions or leave suggestions.

  i know sphinx supports online comments as mentioned here:

https://sphinx-comments.readthedocs.io/en/latest/

was there any discussion as to whether this was worth doing?

rday

Re: [docs] was there any discussion about supporting comments on online doc pages?

[Michael Opdenacker]

Hi Robert,

On 1/12/22 10:42 AM, Robert P. J. Day wrote:
>   my apologies if this topic came up and i missed it ... a colleague
> is pondering what to migrate to WRT existing documentation, and i
> suggested taking a look at how brilliantly YP is doing it with sphinx;
> in particular, she was enthused about the expandable/collapsible ToC
> down the left side. the only thing she brought up was the need for
> user-suppliable comments on online pages so readers could ask
> questions or leave suggestions.
>
>   i know sphinx supports online comments as mentioned here:
>
> https://sphinx-comments.readthedocs.io/en/latest/


Very interesting. I tried to activate this on a local branch, and
enabled the Hypothesis engine. After registering an account at
hypothes.is, I could see that you can add shared notes or private ones.
However, there's something I don't fully get... What's the real value of
adding an annotation system to our Sphinx generated docs?

Maybe because you don't need any browser extension to see that you can
annotate text. Anyway, a solution such as Hypothesis seems to work with
any website. After installing their browser extension and logging in, I
was given the possibility to add annotations to any website, including
https://docs.yoctoproject.org/.

So, do we want our readers and users to share their annotations and
comments directly in the HTML manual? We could get more engagement and
feedback this way, but this should be extra work to manage...

>
> was there any discussion as to whether this was worth doing?


Not as far as I know, but maybe before I joined.

Thanks!
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] was there any discussion about supporting comments on online doc pages?

[Robert P. J. Day]

On Wed, 12 Jan 2022, Michael Opdenacker wrote:

> Hi Robert,
>
> On 1/12/22 10:42 AM, Robert P. J. Day wrote:
> >   my apologies if this topic came up and i missed it ... a colleague
> > is pondering what to migrate to WRT existing documentation, and i
> > suggested taking a look at how brilliantly YP is doing it with sphinx;
> > in particular, she was enthused about the expandable/collapsible ToC
> > down the left side. the only thing she brought up was the need for
> > user-suppliable comments on online pages so readers could ask
> > questions or leave suggestions.
> >
> >   i know sphinx supports online comments as mentioned here:
> >
> > https://sphinx-comments.readthedocs.io/en/latest/
>
> Very interesting. I tried to activate this on a local branch, and
> enabled the Hypothesis engine. After registering an account at
> hypothes.is, I could see that you can add shared notes or private
> ones. However, there's something I don't fully get... What's the
> real value of adding an annotation system to our Sphinx generated
> docs?
>
> Maybe because you don't need any browser extension to see that you
> can annotate text. Anyway, a solution such as Hypothesis seems to
> work with any website. After installing their browser extension and
> logging in, I was given the possibility to add annotations to any
> website, including https://docs.yoctoproject.org/.
>
> So, do we want our readers and users to share their annotations and
> comments directly in the HTML manual? We could get more engagement
> and feedback this way, but this should be extra work to manage...

  i haven't yet tested this myself; the idea was to support online
feedback strictly as off-the-cuff suggestions about a page, or asking
questions about something on that page, etc -- there was no suggestion
as to adding any of that feedback back into to the official docs,
other than manually and explicitly.

  in effect, this online feedback mechanism would be totally divorced
from the current docs preparation. is that the question you were
asking?

rday

Re: [docs] was there any discussion about supporting comments on online doc pages?

[Michael Opdenacker]

On 1/12/22 12:03 PM, Robert P. J. Day wrote:
>
>   i haven't yet tested this myself; the idea was to support online
> feedback strictly as off-the-cuff suggestions about a page, or asking
> questions about something on that page, etc -- there was no suggestion
> as to adding any of that feedback back into to the official docs,
> other than manually and explicitly.


Of course.

>
>   in effect, this online feedback mechanism would be totally divorced
> from the current docs preparation. is that the question you were
> asking?


Right, but it could be a valuable source of feedback. However, we would
have to keep track of such comments, take the relevant ones into
account, answer questions and if possible discard the irrelevant ones.
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] was there any discussion about supporting comments on online doc pages?

[Robert P. J. Day]

On Wed, 12 Jan 2022, Michael Opdenacker wrote:

> On 1/12/22 12:03 PM, Robert P. J. Day wrote:
> >
> >   i haven't yet tested this myself; the idea was to support online
> > feedback strictly as off-the-cuff suggestions about a page, or
> > asking questions about something on that page, etc -- there was no
> > suggestion as to adding any of that feedback back into to the
> > official docs, other than manually and explicitly.
>
> Of course.
>
> >   in effect, this online feedback mechanism would be totally
> > divorced from the current docs preparation. is that the question
> > you were asking?
>
> Right, but it could be a valuable source of feedback. However, we
> would have to keep track of such comments, take the relevant ones
> into account, answer questions and if possible discard the
> irrelevant ones.

  all certainly true, but nothing says anyone *has* to follow the
discussions -- one could just look at it as a place where readers
could share tips and so on.

  on the other hand, it could also take the place of submitting
official bugzilla bugs, if someone just wants to leave notes like,
"hey, there's a spelling mistake", or "you forgot to mention option
'--fubar' in your list of options."

  anyway, it was just a thought.

rday