Open lorenzoh opened 2 years ago
two very minor comments about the current state of documentation:
Thanks for the comments! Re the code highlighting: I plan to mirror the syntax highlighting used in Documenter.jl 👍
Updated with ideas from https://github.com/FluxML/FluxML-Community-Call-Minutes/issues/35
With the new Pollen.jl frontend having been adopted in https://github.com/FluxML/FastAI.jl/pull/203, I am taking the opportunity to think about changes and additions to the documentation.
The term Reader refers to someone who is reading the documentation. I'll also be referencing the terms Tutorial, How-To, Reference, and Background so if you're not familar with this system for organizing documentation, please read https://diataxis.fr/.
Structural changes
Domain documentation
With #240 making domain-specific functionality subpackages, FastAI.jl has moved toward a one core, multiple domain extensions design. I think this is also beneficial for Readers who consult the docs for help with a problem in some domain they want to solve.
Each domain (e.g. computer vision, tabular, time series, text) will have its own page group in the docs menu, which should include the following pages:
TabularRegression
), of the kinds of data it deals with (i.e.Block
s) and relevant data processing steps (i.e.Encoding
s) for those blocks.loaddataset
, ready-made learning task,tasklearner
) and link frequently to other pages with more detailed Reference and Background information.Documentation for a domain module may also contain
General documentation
Next to the domain-specific docs, the domain-agnostic parts of FastAI.jl, like concepts, interfaces, training, data handling etc. should be documented. Good examples from domain submodules should be used in tutorials and how-tos to set explanations into context.
Additions
APIs overview
FastAI.jl has a lot of API layers, that build on top of each other and having a page that summarizes these in a neat diagram would be nice.
API tour
As a more interactive tour through the API and how pieces relate, I have long been thinking of something organized as follows: the tour starts with a high-level, 5-line example (as in the README), and gives some context for what is happening. Then, you can "drill down" into each of the lines and it'll give you the extended version using APIs one layer below. Consider the following high-level example:
We could then drill down on each line, e.g. the first would take us to the following, expanded code:
We could again drill down on relevant lines, demystifying the API at every step, showing the Reader how they could use their custom components and linking to relevant material everywhere. For some more examples of "drilling down" from high-level one-liners, see this older post under the heading "API flexibility".
Extending
Every interface that is extensible should have documentation describing how to do so. Since most interfaces belong to the core FastAI.jl (i.e. not a domain library), this should be part of the general documentation.
test_encoding
that perform automated checks on the interface's invariants should be providedContributing
To make it easier to contribute and decrease maintainer burden, a contributing section should be part of the docs. It should clarify the following topics
Other content
(This is copied from https://github.com/FluxML/FluxML-Community-Call-Minutes/issues/35)
LearningMethod
machinery with a regular Flux.jl training loop and, inversely, using aLearner
but with a custom data iterator and no learning method.