As we are currently working on the updated version of Real World OCaml, we are in need of a way to gather feedback. It would be great if we could use discuss.ocaml.org for this, and embed it on the RWO development website.
It would be preferable though to keep this category initially closed and invitation only to keep the amount of noise low.
Once the RWO category is created we would need to create topics for each page we want to gather comments on. The id’s of these pages would then need to be added to the discourse embed script for RWO.
Challenges:
not clear yet how we can indicate that a task is finished
Firstly, thanks to @SanderSpies for his hard work on RWO. Our first attempt to do commenting using GitHub issues was fairly successful a few years ago, but the hurdle of requiring a GitHub account and the very significant oAuth requirements were a definite barrier.
This time around, we thought that a topic per chapter on Discourse would be far more accessible to readers, as it requires only a forum login. However, I have a few concerns that it might disrupt the overall running of the site, so raising them here before taking action:
A topic per chapter is 15 topics, which could be quite spammy initially. What we could do is to create a group (a feature we are not using yet) that is opt-in for people who want to be part of the reviewing process. This group would then see all the feedback threads for the RWO chapters.
We could create a category for the book feedback, but this would (to my knowledge) still subscribe everyone who generally logs in. Is it possible to create a category that only shows up if subscribed to?
This may just me being overly cautious also In the long term, I am hoping that having the ability to comment and discuss chapters of RWO will give us direction on what libraries, tools and techniques to focus on for the next print edition.
Yes, but I am avoiding that for the reason of not splitting up the community unnecessarily. Ultimately, we want Real World OCaml to be an OCaml community resource, and it makes sense to be able to tie beginner threads here into the commenting system. I also hope other books and resources can use a similar integration in the future, as we are open sourcing all of the RWO sources as part of the refresh (including some new documentation generation scripts using ppx_expect
That sounds reasonable. Personally I think that having the topics show up to everyone is not a big deal (especially if there is one topic per chapter instead of one topic per comment), but maybe it would be better if the users of the mailing-list mode did not receive emails on each RWO-related post by by default.
I’m not sure whether this remark belongs here, but below is a question on StackOverflow from a beginner having a problem with a discrepancy in RWO, simply due to the example being outdated.
Two questions arise from this:
Is there a place where we can file issues about the examples to make sure they are dealt with in the new edition? (Maybe RWO’s Github repos?)
What do we say to the readers? I answer the question with a quick-fix, but I wish I could redirect them to a beta of the updated RWO, or maybe a place with up-to-date examples, if that exists.
Hey there - working my way through the book and have some feedback. Was a decision made in the end as to where feedback should be directed? I see the little ‘Feedback’ tab but clicking on it only seems to bring up a sidebar that doesn’t do anything in my case.
We don’t have a satisfactory solution right now, but FWIW, PRs with simple fixes get looked at and accepted pretty quickly. Github issues are also good ways to give feedback right now, though it’s not the ideal solution.
In the long term, I am hoping that having the ability to comment and discuss chapters of RWO will give us direction on what libraries, tools and techniques to focus on for the next print edition.