The best way to document a library?


#1

I intend on publishing a new library soon, but I’m somewhat conflicted on what is the best way to document the library in terms of: easy access and navigation, visually appealing, and maintainable by the community.

LaTeX (to PDF)? Markdown? Scaladoc? Other options?

Any suggestions and experiences are welcome, both from a user and a library maintainer perspective.

Thanks.


#2

Take a look at:

It may be of interest.


#3

The most valuable documentation appears to be the one you add to every type and method, since people can access it from their IDE, and you can automatically compile it into HTML, which you can put on a website dedicated to the library. Don’t forget to have a sub folder for each published version.

Besides Scaladoc, you want to have a tutorial with examples, probably also added to the same website. For maximum community involvement, you can have a wiki.

A forum, for example a Google group, helps with community building.

If your library code lives on GitHub, as most do, you want to add a README.md, which is written in Markdown, and explains at least the essentials, like what this is, and how to get started, including links to the website and the forum. The README can be as extensive as you want, and it is very helpful that it is version-controlled together with the code, although it will never be as visually appealing as a decent website.


#4

Hello,

I have used LaTex for documentation of my final year BE project. Initially it was complex for me later on i was smooth. Scaladoc is also a good alternative.

Regards,
Adrian Gates


#5

I would also add in addition the above answers that a test suite crafted with good method names and intended to be used as documentation can be useful. It’s not a substitute for the other documentation steps mentioned in this thread already, but it is reassuring to the library user that they can run the test suite themselves, see that various things work for them locally as the library developer intended, and then perhaps copy/paste from the test usages to their code to avoid syntax or other errors when initially kicking the tires on the library.