This is the main thread to discuss general things about the May 2018 OCaml DocJam, an event which sprung from the discussion in the OCaml Documentation Open Thread here on Discuss. Feel free to ask any questions, now or during the event.
The May 2018 OCaml DocJam is a distributed/remote event happening in May 18, 19, 20, encouraging interested members of the OCaml community to collectively improve the documentation of OCaml programs and libraries by proposing improvements to the documentation of OCaml projects. One or two hours of your time during that period should be enough to make a valuable contribution.
There are some TODO items marked on the webpage, and some of them are outside my own skillset, so help/suggestions are warmly welcome. In particular, I would be interesting in having specific directions online places to meet, during the DocJam, for users of IRC, Matrix/Riot, and Discord – or any additional suggestions that people would have.
Would some users of these instant-communication channels (@octachron?) be kind enough to suggest the proper way to advertise them on the website? (Or let me know if they are not comfortable with having DocJam-related situation there?).
Here is the “Contribution protocol” that I propose for the DocJam: a list of steps for someone willing to join the fun. Feel free to suggest improvements. I hope that the steps listed below can be performed in at most two hours, for a given contribution.
decide on a project to look at, typically a project that you have
used as a beginner in the not-so-distant past (we will discuss
project suggestions during the event)
perform a small improvement to its documentation, or a series of
such improvement; if you apply patches to the project, they should
get into a fresh branch of your clone of the repository.
optionally, request some feedback on your proposed change to other
participants: create a pull-request from your fresh branch to the
master branch of your clone, and post it on the DocJam channels to
ask for feedback
once you are satisfied with your patches, send it to the maintainers
of the project, and log it in the “DocJam log” that collects all our
Jam actions
(I intend the “DocJam log” to be a Discuss thread of its own, mostly write-only. If you think that another place/medium would be preferable, speak out!)
I think the usual IRC/Matrix/Discord channel (now three way bridged thanks to @bluddy) would probably be fine. The traffic levels aren’t high enough normally to worry about our overwhelming anyone. Also, it would mean that other people in the community would see what we’re doing and might join in.
I tend to agree with @perry than separated channels would be most probably overkill.
I am not sure what you mean by the right way to advertise them @gasche : I think that giving channel names and maybe a link to freenode’s webchat should be fine; but I might be mistaken.
By the way, I have an ambition for this, which I’m going to require serious community help for, which is to try to write an initial PPX section for the OCaml manual. I don’t know that I’m going to particularly well succeed and I’ll need other people to tell me what I’ve gotten wrong.
I don’t think I can actually write something very useful since I don’t really understand it well, but I imagine I can create at least a page or two which can go in the main manual which might be enough to help someone figure out what to start looking at. Eventually I hope others will get disgusted enough to make it better.
I think that it would be nice if people that are not familiar with these channels (and maybe even not with the underlying technology) could have the possibility to join them for the purpose of the event – synchronous communication makes sense for time-bounded events with social we’re-doing-it-together components.
Maybe just a web link suffices for that (could you give me the URL(s) to include then?), or maybe a blurb on how to connect, on the webpage or as a separate document.
(I’m fine with using the usual channels if the regulars are ok with it.)
Linking to freenode webchat seems like a good option: Kiwi IRC .
You could add an irc link irc://irc.freenode.net/#ocaml . On the discord side, I think @bluddy would know which link would the best to include.
I’d like to either improve the CSS for odoc, write some material/examples on how some of the stuff on Language Extensions works, and/or write some material/examples on how to use Base Maps/Sets.
For the last 2, what would be an appropriate venue for that? It doesn’t seem like the documentation for either one lends itself to examples/explanation.
@gasche, could we maybe get a Github repository and Github Wiki for the weekend? It might be a good place to list possible projects for people to work on and to record progress. The home page could be moved to the README.md
If you want to create a github repo with a wiki, feel free. I have used github wikis in the past for hacking events, and I have found them disappointing. The bar for entry is high enough that most people don’t bother editing them unless I spend my whole time forcing them to.
So I have decided to try something different for the “record progress” part, which is to create a dedicated Discuss thread (not created yet) where people would just post a message.
I don’t have a specific plan for the “list of possible projects” angle (especially no plan where people could edit the page in real time to indicate what they are working on; I think most people won’t bother doing it anyway). If you want to create your own list as a wiki, feel free to. Otherwise I count on chat discussions and the already-existing documents that I would link from the announce page, in particular Awesome OCaml, to stand for themselves. (Feel free to suggest other sources of ideas to include in this page.)
I guess this is as good a time as any to introduce the ocaml wiki I’ve been working on. Feel free to create a topic off the main page for the docjam.
I wonder what would happen if we added “fake” questions to StackOverflow. By fake question, I mean a Google-friendly question asked by someone who already knows the answer.
Actually, I do have some real OCaml questions that I don’t even ask on StackOverflow because I’m not expecting an answer. Perhaps we all should start asking all practical questions there, even if end up answering them ourselves.
The advantages that I see about StackOverflow are the following:
Zero barrier of entry for most programmers (who are already using it) to become contributors.
No need for an editorial board.
Q&A format allows asking questions from many different angles, which isn’t done well with a structured document.
Multiple answers allow for alternate phrasing of the problems, which helps modern search engines match a question/answers page with search queries.
If it’s a complicated typing question, chances are that @octachron or I will answer. There are various other people hanging there with specialized knowledge. Very few questions on the “ocaml” tag are left unanswered, even complex ones.
@mjambon this is an interesting suggestion, but did you mean to post it on the OCaml Documentation Open Thread? I would rather keep this topic focused on the time-bounded DocJam on May 18-20, and it doesn’t look like you are suggesting this as a specific activity for the event.