Suggestions for documentation improvements

[odow]

Hi there!

This issue is a catch-all for documentation improvement suggestions. I'll keep it updated with things to work on, rather than having lots of separate issues.

• If you have suggestions for things to add to the documentation, leave a comment below.
• If you're looking to contribute to JuMP, picking something off this list is a great place to start!

General editing

The easiest place to start is just to read through any portion of the docs and give it a good edit. Spelling, grammar, or edits for clarity are always good.

The easiest way to get started is to pick a Markdown page, e.g.,:
https://github.com/jump-dev/JuMP.jl/blob/master/docs/src/index.md
and then click the "Edit this file" pencil icon:

Make your changes, and then scroll to the bottom of the page for instructions on how to submit a pull request.

If you're not sure about a change, make it, open a pull request, and then we can discuss it.

Prior art

There are two existing sources of documentation that I would like us to work towards:

• The AMPL book https://ampl.com/resources/the-ampl-book/
• Mosek modeling cookbook https://docs.mosek.com/MOSEKPortfolioCookbook-a4paper.pdf

Resolved items

Resolved items

Improve current tutorials

A lot of the tutorials are quite basic and consist of just functions. We should revise the existing tutorials to show a wider range of interesting JuMP and Julia syntax and features.

I think it'd also help if each tutorial used a standardized template. Perhaps something like

# Title

This tutorial was contributed by XXX. It is based on the article/book/example of CITE.

## Goal

The goal of this tutorial is to demonstrate ...

## Setup

This tutorial requires the following packages
```Julia
using JuMP
import Foo
```

In addition, you need to data files [bar.txt] and [baz.json]. These files are contained in the JuMP repository 
```
const _DATA_DIR = joinpath(@__DIR__, "data")
```

## Now start the tutorial

• linear/knapsack
• linear/multicommodity-flow
• linear/workforce-schedulig
• linear/steel-t3
• nonlinear/qcp
• nonlinear/rosenbrock
• nonlinear/mle
• nonlinear/clnlbeam
• conic/kmeans
• conic/correlation
• conic/sdp-max-cut
• conic/min-distortion
• conic/robust-uncertainty

Add new tutorials

Structuring larger models

I wrote a nice answer here:
https://discourse.julialang.org/t/integrating-mathoptinterface-into-an-industry-scale-project-e-g-constraint-management/71943/2?u=odow

Improved MIP modeling tricks

People consistently ask how to reformulate max and abs. These should be added. The Mosek modeling cookbook is the gold-standard for this: https://docs.mosek.com/modeling-cookbook/mio.html

Parallelism

I get this question quite frequently. A section should be added to the docs explaining the different options.

Links with content

• https://stackoverflow.com/questions/64177415/create-jump-model-with-multi-threading-in-julia
• https://discourse.julialang.org/t/parallel-solves-in-gurobi-jl/9908/8?u=odow
• https://discourse.julialang.org/t/improve-performance-of-a-code-with-very-large-of-garbage-collection/75548/20

How to debug a JuMP model

We need a getting started on debugging.

0. The Julia debugger doesn't work well with JuMP.
1. Update your packages to the latest version. JuMP will only support the LTS an the latest point release.
2. Try a different solver
3. Simplify the problem
4. Comment out constraints until the infeasibility resolves itself
5. Write tests.

@BenLauwens has a great chapter on debugging: https://benlauwens.github.io/ThinkJulia.jl/latest/book.html#chap21. We should link to it, and re-phrase some of the suggestions in a JuMP context.

Parametric problems

The same user as #2662 asked for ways to solve a collection of problems over a set of parameters. We don't have a good way of doing this in JuMP (we have @NLparameter, but not @parameter), but it could be scripted using the modification API (or even just rebuilding the problem).

We should write a tutorial with the different approaches. Here's their suggestion:

![image](https://user-images.githubusercontent.com/8177701/129110774-cc2688d9-ac27-40e2-b6b0-390e1d7c2e0a.png)

I like the idea of visualizing the heat map.

[odow]

• add an introduction to optimization tutorial. See the discussion in [docs] Add a "Getting Started with optimization" tutorial #2859

[odow]

Use or mention PiecewiseAffineApprox.jl in the piecewise linear tutorial: https://jump.dev/JuMP.jl/stable/tutorials/linear/piecewise_linear/

[odow]

Add a section on anti-patterns

[jd-foster]

More visual content in the docs would be welcome, I think.
This is a good example for flows in graphs: https://doc.sagemath.org/html/en/thematic_tutorials/linear_programming.html#flows

[jd-foster]

Another interesting idea from Sage docs: a compilation page "presenting commands roughly in the order a student would learn the corresponding mathematics" (but for LP not group theory, of course)
https://doc.sagemath.org/html/en/thematic_tutorials/group_theory.html