Gauging your interest for small external doc contribution

[mbarbin]

Hello! As I am discovering Miou and reading more, I can propose to submit small corrections to the doc for things like typos, and ask questions about things that give me pause. Would you be interested? (taking the perspective of someone discovering the text for the first time).

In particular I tried compiling the doc and formatting the repo:

• there are a lot of warnings generated by dune build \@doc.
• ocamlformat is still 0.26.2, with an opportunity to upgrade to 0.27.0 which enables formatting of doc comments, and code in code comments by default. I tried locally - at a quick glance, this looks like general improvements. Also, tangentially, formatting the code both with 0.26.2 and 0.27.0 shows a BUG in ocamlformat to report upstream (some comment changes).

I can propose to prepare chore PRs to:

• upgrade to ocamlformat.0.27.0, report the bug upstream
• address odoc warnings
• fix some typos in the doc

Please let me know if you are interested. For me this would fall within the time I allocate to learning Miou anyways, so I see it as valuable for me in the long term, while potentially making very small steps to making it easier to onboard future contributor changes.

Thanks!

[dinosaure]

Would you be interested? (taking the perspective of someone discovering the text for the first time).

Very much so! We've tried to produce good documentation and a small book to help people of all levels to use Miou. Unfortunately, my English isn't perfect, there's a lot of writing involved (which can take a week or 2) and, inevitably, there are typos, a bit of French here and there and not necessarily good reflexivity in all cases in relation to the readers. I'd be really pleased to have feedback on all this and to improve these crucial aspects.

I can propose to prepare chore PRs to:

Please, go ahead! I'm not very fussy about ocamlformat and it would indeed be nicer if there were no warnings in the documentation.

[mbarbin]

Même bateau 🥖 - I'll try to have something going during the cycles I dedicate to Miou. Thanks!

[mbarbin]

Thanks a lot for attending the PRs! I am somewhere through the reading, and have been enjoying that quite a bit, thank you for this learning material.

Before closing this issue, I had perhaps another suggestion, I can detail if you are interested but in a nutshell, I wanted to explore using mdx a bit through the book, and have the examples spinets be automatically inserted from annotated fragments located in actual ml files that would be part of the test build. Pros: the examples in the doc stays up to date, you have the guarantee they type check with the current version of the lib, and you'll be reminded to update them upon changes. Users can use their normal editor goodies when browsing it (personally I like to hover over values with Merlin to see their types). Cons: this adds a test dependency to the mdx tool, and extra build steps when you update the doc. Please let me know if interested and I can offer to have a look, while I'll dig deeper into the reading of the part of the doc. Thanks!

[dinosaure]

I wanted to explore using mdx a bit through the book

Cons: this adds a test dependency to the mdx tool, and extra build steps when you update the doc.

I'm not a huge fan of mdx and I can be pretty picky about adding dependencies to build documentation. I'm not against, however, adding dependencies for development (as was done for ocamlformat, for example).

[mbarbin]

It sounds like for now it'll be easier for me to build and explore the book examples on the side. I also noticed some tutorials written as mld files - I don't think I've seen this particular type of use before. That plus your mdx and build dep feedback will give me some things to think about. Thanks! 👍

I can propose to prepare chore PRs to:

I think this about wraps it up, and I'm preparing to close this issue. Thank you for your time, and talk soon!