Suggestion: Hierarchical structure for documentation

[gdalle]

The current documentation has many sections in the menu on the left, but hardly any subsections. I feel like this doesn't help navigation, and I would prefer a more hierarchical approach (like the one from networkx. Does anyone agree?

[cormullion]

I think this would be a great idea.

The current documentation is definitely more developer-focused at present, and it could be expanded and re-organized to be user-oriented as well.

I think the Divio System is a reasonable structure to follow.

I made a quick test to see how the current documentation could be re-presented.

Here all the main sections are expanded, but they can be closed by default.

[gdalle]

Working on this right now, @cormullion how did you get foldable sections in the sidebar?

[cormullion]

In the make.jl file, there's this:

makedocs(
    modules     = [Graphs],
    sitename    = "Graphs.jl",
    doctest     = false,
    format      = Documenter.HTML(
        prettyurls = get(ENV, "CI", nothing) == "true",
        warn_outdated = true,
        collapselevel=1,
        ),
    pages       = Any[
        "Introduction to Graphs.jl"            => "index.md",
        "Tutorials" => [
            "Quick and short"                  => "tutorials/quickstart.md",
            "Tutorial 2"                       => "tutorials/tutorial2.md",
            "Tutorial 3"                       => "tutorials/tutorial3.md",
            ],

        "Examples" => [
            "Simple examples"                  => "examples/simpleexamples.md",
            "More examples"                    => "examples/moreexamples.md",
            ],

        "How to guides"  => [
            "Choosing A Graph Type"            => "howto/graphtypes.md",
            "Accessing Properties"             => "howto/basicproperties.md",
            "Making and Modifying Graphs"      => "howto/generators.md",
            "Reading / Writing Graphs"         => "howto/persistence.md",
            "Plotting Graphs"                  => "howto/plotting.md",
            "Path and Traversal"               => "howto/pathing.md",
            "Coloring"                         => "howto/coloring.md",
            "Distance"                         => "howto/distance.md",
            "Linear Algebra"                   => "howto/linalg.md",
            "Matching"                         => "howto/matching.md",
            "Degeneracy"                       => "howto/degeneracy.md",
        ],
....

The answer might be here somewhere... :)

[gdalle]

thanks! I did not find this option in the Documenter docs, I should have looked closer!

[gdalle]

OK I did a complete revamp and tried my best to separate tutorials from the API reference. This is still a very rough draft, page names especially are subject to change, but could anyone give me their opinion?
I did the build on my fork so you wouldn't have to do it locally: check out the result at https://gdalle.github.io/Graphs.jl/dev/

[gdalle]

For simplicity I tried to imitate the file structure from src/ when constructing the API Reference, but I'm not convinced. There's too much information for my taste, so maybe we should add another hierarchical layer, like in Networkx (https://networkx.org/documentation/stable/reference/index.html) for instance

[gdalle]

@cormullion what do you think?

[cormullion]

I think that's great! It's definitely an improvement - and I know that it's a lot of work too!

The API reference is an interesting one; using Documenter's search tool should make that middle level superfluous (eg BIconnectivity, Centrality...) but perhaps some people would find those headings useful, particularly if they're more experienced coming from another graphing package. I can see that. But when I rearranged docs for one of my repos, I flattened it out by moving all function references out of the Markdown files and into a single autogenerated reference list. (see here). I figured that having an alphabetical listing of all functions was useful anyway, and quicker to search through than Documenter's search. As well as doing this, and to make it more usable, I changed all mentions of functions in the Markdown files to cross-references (eg [`preview`](@ref)). Of course, many of the Graphs' API reference sections could have more helpful information in a matching "How To" section. Splitting the information between the various sections is tricky though.

The organization of the "How To" entries can consist of common tasks that people want to do need grouped into categories and given user-oriented names. I'm not really knowledgeable enough about graphs to be very good at this, but I would definitely look to existing structurings such as Mathematica's or MatLab's to see what are the general headings people would expect to see. You want "action-oriented" titles here, I think. "Graph Types" and "Interface" might belong in "Explanations" perhaps. The others ("Access", "Plotting" etc) probably need expanding since these are probably what most users want to know.

Hope some of these thoughts are useful...

[etiennedeg]

Awesome work, here are my thoughts and suggestions :

I don't get the difference between Tutorial and How-to...
Explanation puzzles me, I don't get what goes in.

Construction => Making and Modifying graphs
Access => Accessing properties
API reference => Algorithms
Module => Interface

A structure I could see:
First Steps:

• Graph Theory
• Choosing a graph type
• Making and Modifying graphs
• Accessing properties
• Paths and traversals
• Plotting
• Reading and writing

Graph Types :

• Interface
• SimpleGraphs
• SimpleweightedGraphs
• ...
• Creating a new graph type

Algorithms

• Biconnectivity
• Centrality
• ....

Advanced Functionalities:

• Error handling
• Parallel algorithms
• Experimental algorithms

[cormullion]

The divio approach is to use tutorials to establish basic techniques and procedures; then write "how to" guides for combining these basic techniques to accomplish tasks. For example, a cooking tutorial might walk you through making a white sauce from butter and flour. A lasagne "how to" recipe might expect you to know how to do that.

From https://documentation.divio.com/how-to-guides/ :

How-to guides are wholly distinct from tutorials and must not be confused with them:
A tutorial is what you decide a beginner needs to know.
A how-to guide is an answer to a question that only a user with some experience could even formulate.
In a how-to guide, you can assume some knowledge and understanding. You can assume that the user already knows how >to do basic things and use basic tools.
Unlike tutorials, how-to guides in software documentation tend to be done fairly well. They’re also fun and easy to write.

Tutorials will be the most challenging to write (since coding implementation knowledge isn't that helpful).

My references to divio are just suggestions, I have little experience with them but they seem well-regarded...

[gdalle]

Thanks to you both for your feedback. I must say I tried @cormullion's divio approach, but I'm not so sure it fits our needs. It would be great if we had the time / manpower to write actual tutorials and how-to guides, but I'm not ready to throw myself into this. Which means that for most of the functions provided by Graphs.jl, the best resource we have are actually the docstrings themselves (until something better comes along).
As a consequence, I actually agree with @etiennedeg. I think we should focus on structuring this massive pile of docstrings into meaningful, theme-based categories. Not to say that we shouldn't have a few text-based tutorials at the start, but the rest should be easy to browse as well.

[cormullion]

Yes, good decision.

My suggestion is that it would be good idea to build a structure that allows (and encourages) future contributions. If, say, there's an empty section marked as a placeholder, people may be more encouraged to contribute some material to it, since there's a natural desire to fill holes. 😂 Though this approach might be too far for some, I agree!

[gdalle]

Here's my second attempt, where I included a few docstrings from ecosystem packages (I think it was @simonschoelly who suggested to bring stuff together like this): https://gdalle.github.io/Graphs.jl/dev/
If this sounds promising to you, I suggest we do this at least for packages that define other graph types, and possibly for algorithm packages (flows, matchings => see recent discussion on the #graphs Slack channel).
@etiennedeg @cormullion, any thoughts?

[gdalle]

Tagging @matbesancon too since it is one of my favorite occupations

[matbesancon]

I'm largely in favour of this restructuring, the sample above on @gdalle's account looks good. I would rename Graph theory with
"Basics of graphs theory" or "GT concepts"

[gdalle]

Yes the names are still very temporary

[etiennedeg]

Wow, I haven't read fully in details but this is now so much clearer and beginner friendly. I really like the new structure of the sections and subsections.
Here are my first observations :

• Graph and DiGraph constructors for empty graphs must be mentioned in "Constructing a graph", and probably also in "Basic use".
• zero has been removed from the interface.
• GraphsFlows, GraphsMatching and other JuliaGraphs packages should be cited in Ecosystem docs
  Their algorithms should probably be cited in "Algorithms", with a clear redirection to the corresponding package.

[cormullion]

Looks great! You could leave some room for a tutorial or two, perhaps...

[gdalle]

I took another stab at it, here's the result: https://gdalle.github.io/Graphs.jl/dev/. Among the main novelties:

• I extracted page titles directly from the markdown source for the sidebar
• I automatically copied the README into index.md during build
• I added a few sets of docstring from the most recently updated JuliaGraphs packages (the others broke my docs environment with compatibility conflicts)

[gdalle]

To follow up on this, I think we should try to reduce the number of different JuliaGraphs packages. That would definitely make maintenance easier, and add some clarity, as was discussed on Slack a few weeks back.

• GraphsFlows, GraphsMatching, GraphsExtras and CommunityDetection all implement graph algorithms that could just as well be part of the main package. The only exception is those that require heavy dependencies, most notably JuMP: they could remain in a separate package called GraphsOptim (for example). See Move code from GraphFlows and GraphsMatching to GraphsOptim #108 for this discussion
• GraphsExtras, SNAPDatasets, Graph500 and GraphDataFrameBridge all have to do with graph datasets, would it make sense to group them?

[gdalle]

On a side note, I'm not sure it makes sense to put the docstrings of all JuliaGraphs in the main docs, because it leads to a very constrained docs environment for Graphs.jl. That could be a good thing though, because if we can build such an environment, it means that JuliaGraphs packages play nicely together. At the moment, it doesn't work though (or at least I didn't succeed).

I think it would be good to put the documentation of alternative graph formats there, and possibly add the docstrings of graph optimization algorithms, but not much beyond that. We should also find a way of copying the READMEs of those repos when building the GitHub page for Graphs.jl, since they are often the only redacted documentation (eg for SimpleWeightedGraphs)

[gdalle]

This has been dragging on for some time, so here's a PR to get things going and hopefully we can work from there!