Revise API docs initial page for newbies?

[mars0i]

Hi,
I have two suggestions for the API docs pages to make them friendlier for newbies.

The suggestion first is to add a note at the top that explains that, for example, BatList would normally be used as Batteries.List. (In the long run it would better if it's described as Batteries.List or something simialr in the documentation, but this is a general issue with OCaml documentation that's been discussed online and that I imagine will eventually be resolved. In the short run, a simple note would help new users to be a little bit less puzzled.)

The second suggestion is to provide a page in which all of the modules are listed in alphabetical order, or listed in groups according to similar functions. The current page http://ocaml-batteries-team.github.io/batteries-included/hdoc2 is no doubt useful for experienced users. "New Data Structures" and "New Modules" are irrelevant to someone for whom everything is new, and most of the other categories on the page are not very useful to a new user, either. If you're trying to find out what linear data structures are available, for example, you have to scan most of the page visually to find BatList and BatArray, or guess at their names and make the browser search the page. I would find it easier to scroll to the "L"s if I thought there might be a List module. (Actually, as it is, I know there's a BatList module, but I don't remember what section it's in, so I almost always type "list" into the browser search, which is less convenience than scrolling through an alphabet.) It would be possible to have both an alphabetical page and the current page, maybe also with some sort of functionally categorized page. However, I think the first page from the API link on the main web page should be to whatever page is easiest for newbies. This can contain a link to the current API page for those who've been using Batteries for a long time. That's my suggestion.

I can submit a PR for the first suggestion if that's desirable. For the second suggestion, I don't now how the docs are generated, so maybe that should be left for someone else, if it seems desirable.

[gasche]

The introduction to the API is in the file build/intro.tex. The syntax used is described in the ocamldoc manual.

I'm a bit hesitant about the first change (some people use BatList directly and it's fine as far as I am concerned), but the second change definitely sounds like a potential improvement, so I would be curious to see what you propose.

[mars0i]

For the first change, I'm only proposing that there be a note added explaining that BatList is also named Batteries.List. When I was starting out, I was looking for the latter and only figured out that it also had the name BatList by guessing. Having to do this is off-putting. I didn't mind too much, but I think it contributes a feeling of not being welcomed. I didn't care, but I think this matters to some people when there are multiple speedbumps that they encounter. (Being a functional language with an unusual syntax counts as two big speedbumps for some people, but these can't be avoided. I don't want to make more.)

For the second suggestion, an alphabetical list would be useful. A functionally categorized list would be useful, too, but that requires more thought. One suggestion would be to put all of the data structures, old and new, into one category.

I can't figure out how to access intro.text except via github. Is there a link to that page somewhere?

[gasche]

Ok, mentioning that Batteries.List works seems fine.

intro.text is part of the source tree that you get if you clone the git repository of Batteries -- you can then edit it locally and send a PR -- at the relative path build/intro.text. It is then transformed into HTML code to be included into API docs by the ocamldoc tool, as part of the documentation build process.

[mars0i]

Ah, I understand now about intro.text. Thanks. At least one PR coming.