Don’t worry, your document is already better quality than half the content in the learn section (it badly needs a cleanup). 
2 Likes
This reminds me of another technical item: it might be nice to put a link on every page on the ocaml.org web site pointing at the corresponding code in GitHub and encouraging people to click and submit pull requests. (Though really it would be nice to find an even lighter weight mechanism to let people submit changes, as even GitHub is a bit heavyweight.)
1 Like
Is it? I think GitHub does a good job providing an in-browser editing experience. I made the last two commits to the repo on github.com directly, perusing the “Edit this file” feature. I’m not sure how it works with forking though; I imagine it should handle it as well…
1 Like
There is a button “edit this page” on every page.
2 Likes
If such a button is on https://ocaml.org/ or on Learn OCaml or on The OCaml Community or on Learn OCaml I cannot find it.
[Edited to add: it is the pencil in the upper right corner. It never occurred to me this was the edit button. Yes, I know, perhaps it should have occurred to me.]
It’s the pencil icon at the top-right of every page. I agree it could use a bit more emphasis (or text?) though.
4 Likes
Seriously, I have been looking at these pages for a while and absolutely no idea what that meant. (My eyes no longer even registered it as there.) It could probably use some text, or maybe a link at the bottom in addition that says “edit this page”.
1 Like
(BTW, quite seriously, features are more useful when they’re obvious. And yah, arguably I was being thick, but remember, there are a lot of thick people out there who you still want helping to fix grammar problems etc. I suppose I should have guessed by analogy to the similar icon GitHub provides and the one on discourse, but it never occurred to me. Anyway, I’ll call this 80% on me, but call this a vote for a button that says “edit” — I think there’s a reason Wikipedia’s “edit” button is a word…)
2 Likes
The burger menu only appears if you’re viewing with a width less than X pixels.
1 Like
This is what I suggested when the new ocaml.org design went up; a wiki for rapid iteration and community contributions, followed by copying the best stuff to ocaml.org. But I was shot down.
Should we fork this thread to have a place to discuss ocaml.org? I recently posted a critique of it here, but Bobby’s contribution reminded me that we really need a more flexible system that allows people to evolve the pages as we see fit.
1 Like
So I’m trying to contribute a bit to ocaml.org right now and having a problem.
In order to build the dependencies so I can see if my change works, I’ve tried doing make dep and it fails. I’ve posted a trouble ticket to the github repo, if someone could have a look at https://github.com/ocaml/ocaml.org/issues/985 I’d appreciate it.
I don’t see the burger menu because I’m not on mobile. If “Edit” could somehow be added to the pencil on the normal page that would be awesome. Alternatively, it could be added to the footer to catch imbeciles like me who don’t figure out what the pencil is immediately.
Yes, could you start a new topic? It would be appreciated.
BTW, I now have pull requests in to remove the obsolete OCaml 2017 meeting from the front page news, and to add a “News” button at the top.
This is a great doc and goes well beyond a start, covering pretty much everything I was looking for. Thanks for taking the time to put it together
3 Likes
A link is now in each footer.
2 Likes
Ok, in the spirit of making odoc more open, I turned the many good suggestions in this thread into issues in the odoc repo:
- better CSS and HTML
- better navigation
- centralized hosting
- docs-wide search
- Docusaurus
- creating how-tos
- types on hover
- Reason syntax support
- running examples in CI
- running examples in the browser
- math support
- links to source
- proper in-page search
- version switching
This is mainly just to keep track of them in an organized fashion. Discussing suggestions here remains much more visible than in the odoc repo
In addition, the odoc repo now has:
- A
CONTRIBUTING.md, including a quick start for working on CSS and HTML. There is also a hyperlinked explanation of how the repo is structured. - Some kind of initial README with basic docs. Edits very welcome
@bobbypriambodo, would you like to PR a link to your guide into the odoc README? It would be much appreciated.
In the coming days, I’ll start writing easy issues. They are nice for people getting started with a code base, and they can help odoc a lot I’ll post again when a few of them are ready. We should probably make some kind of “About odoc” topic at that point, with links to everything.
15 Likes
This is worth a woot. WOOT!
An interesting new Compare and Contrast. The Coq documentation was recently converted to Sphinx. It has made an incredible difference.
Coq 8.7.2 Documentation, before Sphinx conversion: https://coq.inria.fr/distrib/8.7.2/refman/
Coq 8.8.0 Documentation, after Sphinx conversion: https://coq.inria.fr/distrib/current/refman/
Go through both of them a bit. There’s been little or no change in the content, but I would argue the Sphinx version, merely by being better formatted, is vastly easier to read.
Formatting matters.
It would be neat if we could organize a similar facelift for the main OCaml manual. It’s not nearly as bad as the old Coq manual was, but it will be nicer if it gets modern typesetting.
5 Likes