Documentation improvements

[odow]

Here are some thoughts on improving the documentation. As a general guide, we should aim for something like https://diataxis.fr.

Each of the "Interfaces" could use a tutorial that walks through a simple example, as well as some "How to" guides.

The "Terminology" section is good background explanation.

Guide

My thoughts on the guide is that it is too generic for a novice user. I think we're better off expanding the docs of each interface. For example:

HiGHS has comprehensive tools for defining and extracting models. This can be done either to/from MPS or (CPLEX) format LP files, or via method calls. HiGHS also has methods that permit the incumbent model to be modified. Solutions can be supplied and extracted using either files or method calls.

This isn't helpful because it doesn't say what the tools are, how they're called, or how things differ between the interfaces.

We could keep the Guide, and have something like:

## Load a model from file

The simplest way to use HiGHS to solve a model is to load it from a file using the method `readModel`.

HiGHS infers the file type by the extension. Supported extensions are:

 * `.mps`: for an MPS file
 * `.lp`: for a CPLEX LP file
 
HiGHS can read compressed files that end in the `.zip`, and `.gz` extension.

### Python

```python
model = highspy.readModel("filename.mps")
```

### C

```c
model = Highs_create()
ret = Highs_readModel(model, "filename.mps")
if (ret != 0) {
    printf("Something went wrong.")
}
```

Python

• Finish documenting highspy example
• See if @odow can figure out a way to run the Python code in the documentation
• "Classes" pages need formatting and examples. Not obvious how these relate
• Move Enums to a higher level? It seems they could go with the options, since they're the same for all interfaces.

C

The Gurobi docs have a very nice layout and structure: https://www.gurobi.com/documentation/10.0/refman/c_api_details.html

• Add types to the arguments
• Add examples
• Verify some of the docstrings. What arguments can be NULL, etc.
• Group into sections?
• Explain const enums
• Fix math https://ergo-code.github.io/HiGHS/dev/interfaces/c/#Highs_getBasisSolve-NTuple{5,%20Any}
• @odow fix link from docstrings to source

Julia

• Link to JuMP documentation
• Optional: add examples of how to use the C API

Other

• @odow fix the edit URLs

[jajhall]

Thanks for the ideas. Some of these may be useful in the future, but I'm concerned that we try to write documentation on a scale that (1) isn't needed and (2) can't be maintained.

My vision is of something relatively simple that allows Python users to learn how to use HiGHS, but with enough "tucked away" as a reference for experts. We don't need examples of how to use the C API. Anyone who understands C and (from the Guide) what HiGHS can do can work it out for themselves. Experts have been using HiGHS for years with no problems - just the occasional request for Options to be documented.

In Diátaxis terms, the focus is very much Tutorial and Explanation for beginners, with just enough for How-to and Reference for experts

The Guide shouldn't have examples in it: it's a way to find out what HiGHS can do, and is deliberately generic. Examples would dilute this. Someone wanting to use HiGHS in Python isn't going to want to look at C examples

I disagree strongly that the Gurobi docs have a very nice layout and structure. All I see is a bewildering list of method names. Where do I find out what it can do? To an extent I feel the same about the C API "documentation" in HiGHS: it's just a blizzard of unordered methods. Yes, it's an achievement to extract the docstrings from the C header file into HTML, but what more information does it convey than highs_c_api.h? Indeed, without types in the arguments it conveys less information.

Getting a way to run the Python code in the documentation would be great. However, @galabovaa hasn't found anything that works everywhere, so we intend to put the "live" Python examples in Colab.

I did wonder about making the enums more prominent, but they are only relevant for Python and C++ (and Julia?).

[odow]

My vision

Okay, I'll hold off making larger changes then.

Anyone who understands C and (from the Guide) what HiGHS can do can work it out for themselves. Experts have been using HiGHS for years with no problems

I guess I'm coming at this from the point of view that it would be helpful to me. In writing HiGHS.jl, I often had to experiment, or look into the C++ source to figure out what exactly was going on. This was also my motivation for working on the docstrings: so that I could look at them from Julia without having to read the source.

I disagree strongly that the Gurobi docs have a very nice layout and structure

Oh interesting. I find myself consulting it all the time when I go to do something and I haven't memorized the API. I know the method, but I don't remember the argument order etc. I guess I could look at the header, but online documentation is easier to find.

Getting a way to run the Python code in the documentation would be great. However, @galabovaa hasn't found anything that works everywhere

Live in the browser is a bit difficult. But in JuMP the Julia code runs during the doc build CI job to make sure that the syntax hasn't broken etc.

[jajhall]

Yes, re Gurobi, you know what it can do and just want a reference to how. Very, very few users of the HiGHS documentation will have your level of understanding of modelling and optimization. The HiGHS documentation isn't designed to be for the likes of you!

I see lots of documentation where the desire is to be comprehensive at all costs and/or assume too much knowledge of the language concerned.

I guess I'm influenced by decades of teaching where, you have to set aside your own deep knowledge and tell a simple half-story. If you attempt to give a complete story, you'll soon lose your audience.

[jajhall]

I've fixed the Maths in https://ergo-code.github.io/HiGHS/dev/interfaces/c/#Highs_getBasisSolve-NTuple{5,%20Any}

[jajhall]

HiGHS has comprehensive tools for defining and extracting models. This can be done either to/from MPS or (CPLEX) format LP files, or via method calls. HiGHS also has methods that permit the incumbent model to be modified. Solutions can be supplied and extracted using either files or method calls.

This isn't helpful because it doesn't say what the tools are, how they're called, or how things differ between the interfaces.

It's just introductory text. I can add that the "how" is outlined below.

Remember that you're utterly fluent in all the detailed things that different solvers can do. Most basic users of HiGHS won't have to use more than 10% of its functionality. I was even thinking of moving model modification to the "Advanced" part of the Guide.