Sorry if that’s how the conclusion appeared to you. I don’t recall it that way. We opened up the wiki feature of the ocaml.org github repo for this purpose. AFAICT, no one made much use of it, and nothing from there was ever ported into ocaml.org. Ideas and discussion are great, but more important is that we need people to do the work. We have systematically failed to get more manpower on ocaml.org.
You’re right. There was a lot of resistance to the idea at the time and my memory preserved that part and threw out the conclusion. Sorry.
I did do some work on the wiki before realizing nobody else was touching it.
Also, there’s a problem with using a github wiki – the feel is off. It doesn’t feel like a sanctioned community wiki, which doesn’t persuade anyone to contribute or consult it. Which is fine if enough people decide to use it anyway, but it makes it hard to get started.
Right, the GitHub wiki was a compromise. IIRC what you really wanted was for ocaml.org to directly support wiki like editing somehow. But there was pushback on that for a couple of reasons. One was the “how”. What software to use. All wiki software is pretty bad as far as I know, and prevents you from having pages with arbitrarily customizable layouts and other features such as the blog feed list, opam package list, etc. Also, it was argued that wikis often devolve into a mess unless there is some careful oversight of the content. It was felt that submitting PRs provided exactly this because some experienced member of the team ends up having to review the change.
No doubt the current solution is also not working since we get essentially no contributions. I’m not sure what is the reason. Is it the implementation or just the fact of being a small community or something else.
So I’ve been submitting some small contributions for the last couple of days. A few notes:
- I didn’t know that the “edit this page” button was what it was (fixed). It still might be a good idea to make the capacity more prominent, but I’m not sure what the right mechanism might be.
- Requiring that changes be approved seems like a good idea, but it’s pretty heavyweight having to fork a repo and do the entire git dance in order to alter a few words. I’m not sure what would work better, though. It needs to be thought about.
- Even having done the git clone etc., I was unable to check if my edits were okay because the tools to build the web site weren’t working correctly under >= OCaml 4.06. I’m hoping that will be fixed shortly.
- Something I’ve noticed from other open source projects: it’s a good idea to have pull requests and similar tickets disposed of quite quickly, as it encourages contributions and also (paradoxically) encourages project members to fix issues quickly because the list does not seem overwhelming. I note that the open issue list is very long (124 open issues), much longer than one would naively expect for a fairly small site, and that some of the pull requests are months old. Once lists like this get to the dozens, let alone hundreds, people get scared of doing work on them. I’d suggest that trying to reduce the length of the open ticket list and pull queue over time would be a good thing.
1 Like
I would venture to say there’s a mix of factors, all of which are amplified by being a small community. My narrative over the last little while is that we’re now a small community attached to a rapidly growing one (Reason), and we need to take advantage of that.
Picking on some reasons for lack of contribution, I would focus on design and psychology:
- Contributions will only come if the site is frequented by enough people, but that requires a sufficient number of useful attractions. Having the Planet more prominently placed is a good idea, as would having the curated list of Awesome-OCaml easily accessible.
- The PR-based approach increases the psychological barrier to contributions. If you’re submitting a document to a PR, you’re fundamentally losing control of the process, and in your mind, you’re ‘bothering’ someone else with your change and engaging in a longer process. I’m far less likely to correct a spelling mistake I see if it requires a PR, and that generalizes to bigger changes. I also don’t feel comfortable submitting partial work, even though that may be all I have time for. In a wiki, multiple people can finish the work started by a single person via quick iterations.
- A wiki is more dynamic in the sense that I can just create a new section when I feel the current sections don’t suit my added content. The markdown-based website feels more restrictive. A good example would be the document produced by @bobbypriambodo above.
I do agree though that I don’t know of a wiki that is easy to set up. Presumably though it wouldn’t be too hard to set up a MediaWiki and giving it a domain at wiki.ocaml.org. It requires just one machine, which we should have already. Also it’s worth noting that serious wikis have discussion pages attached to all wiki pages, allowing moderation of content behind the scenes. If the wiki is sufficiently successful, it would also lower the burden of ocaml.org, allowing it to be a simpler site designed around one of the popular modern frameworks.
I don’t see that as an issue for quite the same reason. It’s an insane amount of work to submit a change for a word or two, which makes one reluctant to do it (high barrier to entry), but if it took no effort and someone approved the changes I don’t think it would be such a problem. The big deal is what a pain it is. Having now done it a few times in the last day, it isn’t fun and quick — you’re likely to see it as not worth the effort if you’re a casual contributor.
1 Like
Do you know that you can edit the page in Github itself and then push the PR from there? No need to clone the repo on your computer to contribute content.
1 Like
I did know. But it works by forking the repo into your github account and doesn’t keep it synced to the original repo, and if you want to test your change it doesn’t help you by showing the results, you need to build the site locally to check.
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.
Personally, I find the new coq documentation much harder to navigate. The tactic index – which is the main entry point for the documentation day-to-day – is hidden at the bottom of the side-bar. The tactic index itself is also less pleasant to use.
The content of the new manual is also harder to read just as often as it is easier to read. Everything is far too packed together and the side-bar – which is basically never useful for this manual – occupies a huge amount of screen real estate. There are individual styling changes which make things clearer – the old manual had a habit of having some paragraphs with random indentation and poor delineation between different subsections – but I certainly wouldn’t say it was “vastly” superior.
So I’m not sure how good an advert for “modern typography” this is. I think the new manual looks prettier at a glance, but for actual use it isn’t an improvement.
1 Like
I should point out that I think Sphinx produces nice read-able output for tutorial-style documentation – where there are large bodies of text with the occasional note or code sample. However, for API documentation it tends to degrade into a cluttered mess that is hard to read. This is true of a lot of the markdown/rst based systems – their input just isn’t expressive enough to produce good layouts for API documentation which is light on text.
1 Like
Those are both fixable.
I will have to disagree in two ways. First, the screen real estate is not, in fact, terribly precious, because in practice humans cannot handle wide text displays without having trouble with reading. More than 70 or 90 characters wide and a column starts becoming very difficult for most people to handle. On mobile, screen real estate is precious. On a desktop it is not. (You will note, if you pick up a print book, that there are substantial margins, and that is not because publishers like being extravagant with paper because they’re rolling in money.) Second, having the index right there makes it possible to skip around much more efficiently.
I’ve found it is actually much easier to read. (I’ve discovered that certain things I didn’t think were documented actually were documented, for example.) I’ve heard the same from a number of other people, too.
1 Like
Those are both fixable.
Everything’s fixable. The point is that the most important thing about the documentation is how it is to work with day-to-day, and that sometimes people are willing to sacrifice that in order to get something shinier – which is a shame. The coq manual shouldn’t have been switched until these fairly obvious issues were resolved.
First, the screen real estate is not, in fact, terribly precious, because in practice humans cannot handle wide text displays without having trouble with reading. More than 70 or 90 characters wide and a column starts becoming very difficult for most people to handle.
Humans also read better with a wider margin, which is why the real estate matters. On my screen there is almost no margin between the large bar and the text making it more difficult to focus on the actual content. Similarly, the more clutter on screen the harder it is to read, and here again having a third of the width of the screen taken up by a visually prominent side bar makes it harder to read.
Second, having the index right there makes it possible to skip around much more efficiently.
Except the only place you actually want to skip to – back to the tactics index – is buried off the bottom of the screen.
These are laid out really nicely. Easily the most readable online documentation I have seen. What do they use? Is there a stylesheet that OCaml could steal? (sphinx or otherwise?)
I agree with @lpw25, the Coq stylesheet is certainly more appealing visually than the older one but I don’t find it practical as an API stylesheet. I concur with @n4323 that, for Ocaml APIs, adapting the Racket CSS would be nice (my only fear, w.r.t. the current OCaml stylesheet and that of @dbuenzli, is that the Racket doc is not very dense vertically so I imagine one may have to scroll for kilometers before reaching a given val documentation).
The CSS and underlying structure are easy to steal. I believe the tools are built by the Racket people, but we have similar ones.
This is what the left hand index is for.
I don’t have time to do it immediately, but I will gladly merge any PRs to odoc that make the CSS more Racket-like, or add a left-hand index, especially one that disappears/gets inlined into each page when the page gets smaller.
Regarding the index, see discussion here.
4 Likes
I also want to add that the guide on contributing to CSS is here, and this is the CSS file to edit. It needs a general reorganization and refactoring, so please go ahead and do that if you find the current one difficult to work on.
If more elements need to be rendered by odoc, or the current markup is inconvenient in any way, please open issues, and we can fix it.
To install the development odoc and try everything out, see the instructions. Basically:
-
Clone and pin the repo:
git clone https://github.com/ocaml/odoc.git cd odoc opam pin add --no-action odoc . -
Install the development odoc:
opam install odoc -
Test it on any Jbuilder project:
jbuilder build @docthe output will be generated at
_build/default/_doc/_html/index.htmlunder the project’s directory.
For editing CSS, you can probably edit it in the browser, then send a PR for the changes. The CSS file odoc generates is just a copy of the one in the repo, and it is at _build/default/_doc/_html/odoc.css, if you’d like to apply the changes there while testing. If you want to apply them, more permanently, to your local odoc clone, edit odoc’s CSS file, then do a commit, and
opam reinstall -y odoc
jbuilder build @doc
to test.
4 Likes
On the topic of live, interactive examples, just in case anyone is not aware yet, OCaml (through BuckleScript) is supported by Klipse, an online in-browser evaluator for interactive code snippets. See this neat article about integrating Klipse+OCaml on your blog. It supports Reason too.
I imagine that since odoc supports raw HTML, integrating Klipse is a matter of copy-pasting the css and scripts to your ocamldoc comments.
(Note that I’ve been meaning to post this since a few days ago, but I couldn’t for the life of me remember the name of the tool. I only remembered it started with a ‘K’ and has an ‘l’ somewhere in it… and today I stumbled again to the Reason 3 blog post and it came back to me.)
4 Likes