Different versions of the same documentation

[fonsp]

Problem

As @dpsanders pointed out, there is not one "best" way to explain something! Some users want a technical reference, others want a tutorial, others want an example, ...

In Julia's Base documentation, the docstrings are often of the 'technical reference' kind. This is great for some users, but not for newcomers. A good example is the docstring for rand, leading you down a path of Mersenne twisters and random arrays, and failing to tell users that rand() gives a number between 0 and 1.

Idea

A realistic solution is not to change Julia's documentation, since we don't want the technical documentation to disappear completely. I think we need a way to have different docstrings for the same object. This means:

• a way to declare multiple docstrings, and
• a way to view multiple docstrings.

Localization

Another use case is localization! Can we show the documentation in a language other than English? It might be worth looking into Julia's Chinese localization, I found that the manual entries are translated, but all docstrings are still in English: https://docs.juliacn.com/latest/base/collections/

[fonsp]

About declaring multiple docs: Julia has a built-in docstring system: https://docs.julialang.org/en/v1/manual/documentation/ which is awesome! but unfortunately for this project, having a single docstring per object is 'baked in' to its design.

[pfitzseb]

We don't necessarily need multiple docstrings -- different sections of the same docstrings could also do this. The current system already allows for showing additional info with help> ?foo (although I can't remember what that does, tbh).

[fonsp]

You mean using # for Markdown headers right? That's a nice simple idea!

We could 'standardize' some headers, like "Example(s)", and "Locale-ES"?

[pfitzseb]

Yep. Currently it works like this:

julia> """
       short help text

       # Extended Help
       loooong help text
       """
       f(x) = x
f

help?> f
search: f fd for fma fld fld1 fill fdio frexp foldr foldl flush floor float first fill! fetch fldmod filter falses finally foreach fldmod1 findmin findmax findall filter! function Float64 Float32 Float16

  short help text

  ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Extended help is available with `??`

help?> ?f
search: f fd for fma fld fld1 fill fdio frexp foldr foldl flush floor float first fill! fetch fldmod filter falses finally foreach fldmod1 findmin findmax findall filter! function Float64 Float32 Float16

  short help text

  Extended Help
  ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

  loooong help text

[logankilpatrick]

I did not know this was a thing, is it documented somewhere what shows in long vs short help text?

[pfitzseb]

Yes, here:

For long docstrings, consider splitting the documentation with an # Extended help header. The typical help-mode will show only the material above the header; you can access the full help by adding a '?' at the beginning of the expression (i.e., "??foo" rather than "?foo").