Guide the user through ?-REPL (Help mode)

[Iagoba_Apellaniz]

I think it would be interesting to guide the user on its first steps, to engage him/her, using the Help-Mode interface of the REPL. I did a first searching whether this is posted somewhere but with no success.

I try to clarify my idea

help?>
search: ⊻ ⊋ ⊊ ⊉ ⊈ ⊇ ⊆ ≥ ≤ ≢ ≡ ≠ ≉ ≈ ∪ ∩ ∛ √ ∘ ∌ ∋ ∉ ∈ ℯ π ÷ ~ | ^ \ > < : / - +

  Welcome to Julia 0.7.0-DEV.3465. The full manual is available at

  https://docs.julialang.org/

  as well as many great tutorials and learning resources:

  https://julialang.org/learning/

  For help on a specific function or macro, type ? followed by its name, e.g.
  ?cos, or ?@time, and press enter.
  
  For first steps guide try: ?+ and press enter.

Note the last line. What I think is useful is to build a net which connects the help docs of the julia functions in a coherent way. It would follow like so

help?> +
search: + .+

  +(x, y...)

  Addition operator. x+y+z+... calls this function with all arguments, i.e.
  +(x, y, z, ...).

  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> 1 + 20 + 4
  25
  
  julia> +(1, 20, 4)
  25

  dt::Date + t::Time -> DateTime

  The addition of a Date with a Time produces a DateTime. The hour, minute,
  second, and millisecond parts of the Time are used along with the year,
  month, and day of the Date to create the new DateTime. Non-zero microseconds
  or nanoseconds in the Time type will result in an InexactError being thrown.

  Similar functions: -, *, /
  Try: ?methods or ? 

Note the last two lines. It groups similar functions which the user can interact with and the next line presents a way of going forward or backward in thi guide.

I think of course this guide should be build as simple as possible. My idea would be to build a graph to group and connect all reasonable methods and the Help-Mode could check each time if it should print the guiding lines.

What are your ideas? Should I open an issue in Github?

Thanks for reading this

[Tamas_Papp]

I prefer linear structures (eg a Jupyter notebook) for tutorials. It is important to go back and forth. If you are traversing a graph, that becomes conceptually more difficult.

[improbable22]

I like the idea that help should point to similar / related functions at the end. Quite often you can guess the name of one, but aren’t sure what it’s opposite will be called.

Mathematica always has such a list and I find this extremely useful. But of course, they have teams of people to write and update them. I don’t know whether this could be automated, such as just suggesting some of the names appearing on the same page of the manual?

[Iagoba_Apellaniz]

I agree, indeed my proposal i think is quite linear, but it has some branching through “Similar” which would allow the user to go up or down on the diagram. Note please the arrows which represent the “Try” to go left or right in the diagram

In the green group would be the most significant identifiers such as +, sin, for, exp, methods… and then in the yellow circles they could go -, *, cos, atan, log, while, methodswith, typeof…

Of course its only an idea

[jlapeyre]

I find a see-also list almost indispensable for discoverability. When I implement a help system, a see-also facility (macros in the case of Julia) is one of the first features I include. For instance

@seealsogroup [take, drop, takewhile]
@seealso [xxx,yyy]

This adds the complement of take drop and while to each of these symbols’ see-also list, and xxx, yyy to only the currently documented one. The text is then inserted automatically in exactly the same place with exactly the same format for every symbol. “See also …”. That such an easy feature is rarely included in help systems is a bit baffling to me. Note that this is opt-in for the busy person documenting a function.

The format of Mathematica’s help pages is extremely useful and highly uniform: brief description, details, examples, examples->basic…, … scope, applications, possible issues, tutorials, etc. For instance take and drop may be linked to the same tutorial. Not all sections are included for all functions.

Providing similar (not the same) features for Julia might ease the task of writing documentation: Much of the formatting is transferred from author to the help system; The macros encourage the author to follow a format and make it easy to do so. Referring to the style-guide while writing docs is boring. Help-system macros are always there to remind you.

[kristoffer.carlsson]

You can just do:

See also [`take`](@ref), [`drop`](@ref).

Looks simple enough to me.

[jlapeyre]

@kristoffer.carlsson

You can just do:

See also take, drop.

That’s what we have now. You lose the all the advantages I mentioned.

1. If your example is in the docstring for takewhile, you might want to have See also [takewhile](@ref), [drop](@ref) in the doc string for take, and likewise for drop. You have to put them all there by hand. And for consistency, make sure they all go in the same place. And then change it all if a new style for documentation is used. With @seealsogroup [takewhile,take,drop] outside the docstring, this is all done for you.
2. You can’t choose how the see-alsos are formatted. You can’t choose where and how they are formatted in html. You can’t use the data for something have’nt thought of yet.
3. On a Mathematica symbol documentation page I always know exactly where any element of the documentation is found because its always in the same place and is formatted the same way.

[Tamas_Papp]

@jlapeyre

You have to put them all there by hand.

I am assuming that any solution to this problem would require someone to collect related material manually, and I don’t quite see how you could automate it. Some see also relationships are reflexive, some are even transitive, but not all.

[improbable22]

I do wonder if it could be partially automated. I find the search suggestions (at the top) helpful for this purpose… but not for opposites. Defaulting to the reverse of any existing see also links, filled up to 10 with random entries from the same page of the manual, would be good.

Another downside of manually adding “See also…” as the last line is that once you load any package which adds its own help, these will land up somewhere in the middle.

Anyway, right now it does not seem to be the convention now to include “See also …” in the help. Perhaps the thing to do is to start somewhere and make a PR of 20 or 50 or something, and see what people think. If we follow exactly kristoffer.carlsson’s pattern above then it should be easy to copy them to something fancier later if desired.

[jlapeyre]

@Tamas_Papp

I am assuming that any solution to this problem would require someone to collect related material manually,

I am thinking about doing this for future functions, or when working on an existing one. If we don’t have a see-also for a function, its ok. My guess is that semi-automating the process is more trouble than doing it manually. If the system turned out to be really useful, there would be more motivation to revise existing docstrings.

@Tamas_Papp

Some see also relationships are reflexive, some are even transitive, but not all.

Yes, there are both @seealsogroup and @seealso. The latter only applies to the function being documented. I wrote @seealsogroup when I got bored with writing a @seealso for each of a group of related functions. But, its use is limited.

There are two ways of looking at documentation. The first starts with a string holding a blob of text. Then you want to extract or highlight some information from the blob. You do this piecemeal, adding formatting requirements to the blob. This includes the number of spaces here and there, etc. Make sure you put 4 spaces there and not 3 or 5! Then add Arguments, admonitions each with its own special syntax. Exclamation points, a hyphen here, a colon there.

The other way is to look at documentation as a set of elements belonging to distinct classes that describe or otherwise illuminate the function (symbol, etc.) You may want to present some or all of these elements in various formats: cli, html, etc. You want the elements to be placed and formatted in a uniform way whenever possible, like a team of paid technical writers would do. (This can be overridden, of course.) You may not know yet what will be the best format or which media you will use in the future.

The brief description becomes

@brief "bar(x[, y])" "Compute the Bar index between `x` and `y`."

The arguments …

# Arguments
- `n::Integer`: the number of elements to compute.
- `dim::Integer=1`: the dimensions along which to perform the computation.

become

@arguments("n::Integer", "the number ...",
           "dim::Integer=1", "the dimen...")

Likewise with the other elements of documentation. Eg. no !!! for admonitions and notes, rather @note "This is the content...."

Finally, tagging the elements and entering them in a uniform way encourages the second way of thinking about documentation. I find writing documentation this way to be much easier than manually.

[Iagoba_Apellaniz]

One of the main problems I see right now, and the main reason I started this thread, is that once one installs Julia in its system, the splash screen suggests to Type "?help" for help. The next logical step it to do so.

Suddenly, the only three things one is encouraged to try are two internet links (which are useless if one hasn’t access to internet, or in the best case they take you out of the terminal, and I think this is not the best for engage the first coming user) and a random guessing procedure to discover the language.

  Welcome to Julia 0.6.2. The full manual is available at

  https://docs.julialang.org/

  as well many great tutorials and learning resources:

  https://julialang.org/learning/

  For help on a specific function or macro, type ? followed by its name, e.g.
  ?fft, or ?@time, and press enter.

I think we should do it better, at least for the main parts of the language. Of course it would be interesting to automate it for all the packages and for all the documentation it is generated each day.

On the other hand I would be extremely happy to do it for the core functions, macros, types, and so on. We must engage the first coming user for the success of the language.

What do you think? Shall I open an issue in Github and start writing a first graph to connect the main “features” of the language?

Thanks

[Tamas_Papp]

@Iagoba_Apellaniz

useless if one hasn’t access to internet

Is this a realistic concern in 2018, given that the user has access to a computer?

Also, as the worst case scenario, the user should have a copy of the manual offline, which is bundled with the binaries.

[Iagoba_Apellaniz]

I’m also afraid about the people (especially young ones) in not developed countries, see the list of the developed ones I think there is yours as it is mine. JuliaConIndia took place in India two years ago. Please, offline features are good. What is 2018 for us it may be 1940’s for others.

@Tamas_Papp

… is bundled with the binaries.

Thanks, I don’t know how to access it. But it points in the right direction

[UPDATE] Could then what’s printed with ?help point to this bundled copy of the manual as well as the webpages?

[Tamas_Papp]

@Iagoba_Apellaniz

Could then what’s printed with ?help point to this bundled copy of the manual as well as the webpages?

This would be a great idea.

[airpmb]

I’ll add that something similar is part of MATLAB’s help system so it would help new Julia users who are familiar with MATLAB:

Clicking on the “Reference page for exp” link pulls up more exhaustive documentation:

I’m not sure if the Julia REPL supports clickable links but if so it could have a very similar functionality that would make the online documentation just a bit more accessible. One big advantage I can see near-term is that the links could be crafted to point to the documentation appropriate for the running Julia version, so there would be less of the (I’d expect) common situation of a new user trying 0.7 or 1.0, Googling for a particular keyword or function and finding mostly-obsolete documentation.