How to provide the perfect documentation?

General Usage
1

Everyone knows how import documentation is and how import tests are and stuff like that.
I don’t know a ton of people who love to write documentation because it is stressful to maintain.

How to build the perfect documentation?
The perfect documentation has to be

  • easy to maintain
  • easy to ready for everyone
    • online
    • REPL
    • editor

In my case it’s foremost about documentation about how to use different options which are stored in a type called SolverOptions. Which has fields like branch_strategy.
At the moment I’m using Documenter.jl and have markdown files without autodocs and stuff like that. Actually I kind of would like to keep it that way as I like to have longer documentation inside markdown than inside code. I don’t wanna write things more than once (easy to maintain) therefore I don’t want to have a small documentation inside the code if I have a full one in markdown.

My idea would be the following which I hope is at least somehow possible :smiley:

In my code I would like to have

" @LINK_TO_SolverOptions_MD"
type SolverOptions
    log_levels                  :: Vector{Symbol}
    branch_strategy             :: Symbol
    strong_branching_nvars      :: Int64
    strong_branching_nsteps     :: Int64
    strong_restart              :: Bool
    incumbent_constr            :: Bool
    obj_epsilon                 :: Float64
    time_limit                  :: Float64
    mip_gap                     :: Float64
    best_obj_stop               :: Float64
    solution_limit              :: Int64
    all_solutions               :: Bool
    list_of_solutions           :: Bool
    processors                  :: Int64
    traverse_strategy           :: Symbol
end

Then in my SolverOptions.md

Something like

## log_levels

Explanation for log levels

## branch_strategy 

.....
.....

The markdown is easy to include using Documenter.jl. But it would be nice to have documentation inside the repl as well. This also can be used by editors or extensions.

In the reply I would like to use ?SolverOptions to get the markdown version. Copying more or less works (should of course be automated :wink: ) Latex does seem to have a different structure like

“```math vs $”

It would also be nice to get a sub part of the documentation using ?SolverOptions.log_levels

which can be accessed by following the header structure in the markdown.

Several question

  • What do you think about this idea?
  • What do you use atm?
  • Is there a way to document stuff like SolverOptions.log_levels atm?

I’ve build a bunch of extensions for Brackets to make documenting JS easier and I think Documenter.jl and the REPL documentation are a good start to make Julia great in documenting stuff. This is just an approach to think about it in a different way and get some insights from other programmers.

2

How to provide the perfect documentation?

Get others to contribute to it.

2 Likes
3

I think a lot of what you’re documenting here is just too much anyways. I tend to think that documentation is for the high level user APIs (which should usually just be a bunch of functions on internal types, or functions on standard type). If someone wants to dig deep into what your types actually have in them, I tend to think it should be “self-documenting”, i.e. pick some names that make sense, or add a docstring here.

Of course, see comment #1: if users think it’s worthwhile to document, then it probably is.

4

Well it’s a list of options for a optimization solver. That’s the most importing thing for users (people who don’t care about code :smiley: ) Self documenting code is the dream from all of us, right?

There are different kinds of people who are interested in maybe different kind of documentation.

  • As a user I want to see what’s all about and how to use options.
  • As a developer I want to know how it’s working and if it’s good documented I might add a feature.
5

And this is why I don’t think simply putting docstrings into documentation is always a good idea. For a small developer-focused library? Sure. But for one that’s user-focused? Implementation details should be left out (or cited), and it should just be a bulleted list of “this does this” IMO.

6

I’m probably just a fan of documentation that is accessible by extensions inside an editor. Then you can hover over a variable or type or whatever and you get the information of what it does. This is also for users who might be also developers but just wanna use that code atm and get some useful information while typing. :smiley: