1. 13
  1.  

  2. 4

    Hi, this is really great, thanks for the initiative!

    We have ZuriHac coming up, and I could imagine this being a really nice as a Workshop. Could you imagine running an online session in some form?

    Also, Niklas was recently working on making the async docs a lot clearer (https://nh2.me/async-docs/Control-Concurrent-Async.html), maybe it’s also worth putting the two of you in touch (if you don’t already know each other)

    1. 1

      Hi, thank you very much!

      Could you imagine running an online session in some form?

      Honestly I have no bloody idea. :) Documentation writing is not something that would fit the “Hackathon format” very well, because we need time and coordination with the stakeholders, rework the wording, etc.
      Also I voluntarily limited the scope of this initiative so we could bootstrap newcomers in an efficient way. as the tracking issue states:

      You are encouraged to tackle a module if you think you can add something missing, be it examples, unmentioned edge-cases, or a direct risk of runtime error (through the use of error/errorWithoutStacktrace/throw/undefined, etc)

      And in the context of writing / correcting documentation, I don’t believe the “hack and iterate fast” model adopted by Hackathons is appropriate. This is precisely the type of task where we ponder the meaning of words and how to optimise the words/information ratio (“writing long prose that gets your paper accepted” versus “get to the point, make people use your stuff”).


      maybe it’s also worth putting the two of you in touch (if you don’t already know each other)

      I don’t think we’ve ever spoke with each-other, but it would be nice, yes.

      Given that the ongoing work only targets base, a tracking issue on the GHC Gitlab is plenty enough in terms of features (especially back-linking).

      We will surely need another platform if we are to tackle the large Haskell libraries that live outside of GHC (vector, aeson, async, bytestring, text, etc…).
      And I don’t even want to think about coordinating efforts for the larger ecosystem yet because that seems like a Sisyphean task!

      1. 1

        Oh yeah, that makes sense. For what it’s worth, we had a documentation session two years ago, that was led by Oskar Wickström. It seems to have worked out quite well, but as you say, it wasn’t careful coordination with all the stakeholders, it was more filling some obvious gaps in libraries where it’s lower risk to just send a PR and get incremental changes merged. The newbies also liked it as an excuse to deep-dive into a library, wwhile having a mentor to support them.

        So I think you’re right about docs in base needing a more careful approach. You’re still very welcome however to come hunt for volunteers at ZuriHac!

        And I don’t even want to think about coordinating efforts for the larger ecosystem yet because that seems like a Sisyphean task!

        True, and it makes me happy to see that goods docs are becoming a lot more valued in a lot of communities, and projects with exceptional docs are nowadays geting the appropriate amount of praise.

        1. 2

          You’re still very welcome however to come hunt for volunteers at ZuriHac!

          Thank you very much 🙏 I’ll make myself discreet. ;)

          it makes me happy to see that goods docs are becoming a lot more valued in a lot of communities

          I was directly impacted by how good was the Elixir documentation, and the stark contrast with the state of the Erlang docs, when I started programming. Clearly documentation is less viewed as a luxury and more as a part of what makes a language.