Over at Interpolations.jl, we've started thinking about restructuring our documentation a little. We basically have (or will have) three levels of documentation: usage docs, specifying how to use the library; math docs, fleshing out the mathematical background to the algorithms and assumptions we've used; and devdocs, which describe implementation details that might not be obvious just from reading the code (for one thing, the library is quite heavy on metaprogramming).
The usage/api docs are slowly being migrated to docstrings, with the hope that the users will actually be able to find it :) I'm looking for input on what tools, formats, platforms etc have worked well for the other two types of documentation in other projects, and in what form you, as users or contributors to the library, would prefer consuming that documentation. A stong requirement is that it is editable, and preferrably also quite readable, as plaintext. For the math docs, it's also important (obviously) that the support for rendering equations, matrices etc is good. Have you used any tools or platforms previously that solve these problems well? Do you have recommendations about which ones to avoid? All suggestions are welcome! // T
