ssfrr
commented
5 years ago I tend to think that it's useful to organize docs into a few standard sections:
- User Guide: Guides the user through high-level concepts of the library, introduces how it is used, and the relationships between the types and methods the package provides.
- API Reference: List of all public types and functions, generally auto-generated from their docstrings.
- Examples: Not too many examples, but enough to get a flavor and exercise the library. Definitely some filtering examples would be useful here.
- Developer Docs: Documentation on the internals of the library. This is probably similar to the "User Guide" in structure, but documents implementation details for contributors
I guess even if folks like this division there's still the question of whether this lives above or below the submodule hierarchy that we have currently.
I also don't necessarily want to derail this focused issue with a big refactoring of all the docs, so definitely a smaller change that makes filtering more accessible would be great.
galenlynch
ErikBuer
It would be great if we had a more prominent tutorial in the docs. I remember when I first started using DSP.jl, I was at a loss for how to use it for simple filtering tasks. The most helpful section on how to filter is a little bit buried. It seems that other people were also confused by the current documentation, so some clarification may be helpful.