* was there any discussion about supporting comments on online doc pages? @ 2022-01-12 9:42 Robert P. J. Day 2022-01-12 10:52 ` [docs] " Michael Opdenacker 0 siblings, 1 reply; 5+ messages in thread From: Robert P. J. Day @ 2022-01-12 9:42 UTC (permalink / raw) To: YP docs mailing list 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [docs] was there any discussion about supporting comments on online doc pages? 2022-01-12 9:42 was there any discussion about supporting comments on online doc pages? Robert P. J. Day @ 2022-01-12 10:52 ` Michael Opdenacker 2022-01-12 11:03 ` Robert P. J. Day 0 siblings, 1 reply; 5+ messages in thread From: Michael Opdenacker @ 2022-01-12 10:52 UTC (permalink / raw) To: Robert P. J. Day, YP docs mailing list 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [docs] was there any discussion about supporting comments on online doc pages? 2022-01-12 10:52 ` [docs] " Michael Opdenacker @ 2022-01-12 11:03 ` Robert P. J. Day 2022-01-12 11:12 ` Michael Opdenacker 0 siblings, 1 reply; 5+ messages in thread From: Robert P. J. Day @ 2022-01-12 11:03 UTC (permalink / raw) To: Michael Opdenacker; +Cc: YP docs mailing list 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [docs] was there any discussion about supporting comments on online doc pages? 2022-01-12 11:03 ` Robert P. J. Day @ 2022-01-12 11:12 ` Michael Opdenacker 2022-01-12 11:27 ` Robert P. J. Day 0 siblings, 1 reply; 5+ messages in thread From: Michael Opdenacker @ 2022-01-12 11:12 UTC (permalink / raw) To: Robert P. J. Day; +Cc: YP docs mailing list 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [docs] was there any discussion about supporting comments on online doc pages? 2022-01-12 11:12 ` Michael Opdenacker @ 2022-01-12 11:27 ` Robert P. J. Day 0 siblings, 0 replies; 5+ messages in thread From: Robert P. J. Day @ 2022-01-12 11:27 UTC (permalink / raw) To: Michael Opdenacker; +Cc: YP docs mailing list 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-01-12 11:27 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-01-12 9:42 was there any discussion about supporting comments on online doc pages? Robert P. J. Day 2022-01-12 10:52 ` [docs] " Michael Opdenacker 2022-01-12 11:03 ` Robert P. J. Day 2022-01-12 11:12 ` Michael Opdenacker 2022-01-12 11:27 ` Robert P. J. Day
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.