Documentation suggestions from Discourse

[odow]

I put out a call for suggestions on Discourse: https://discourse.julialang.org/t/please-suggest-improvements-to-the-jump-documentation/55596

• [x] "Something I’m usually struggling with when using (later versions of) JuMP is that there is on longer an automatic understanding of norm(x), instead I get a message saying that I have to manually rewrite the constraint or objective using the SecondOrderCone. It would be good to have one (or many) clear examples on how to do this, I usually have to try and fail for a while, or dig up the code from the last time I did it."

  • We should expand the conic tutorial section with "tip and trick" from the Mosek cookbook https://jump.dev/JuMP.jl/dev/tutorials/Optimization%20concepts/conic_programming/
  • Improve the error messages to point people towards that section

• [x] #2490 "One thing that may improve is: to add a forum section. Then new beginners and experts have the opportunities to communicate. Thanks."

  • We need to make the forum way more obvious!

• [x] "A “performance tips” section would be great." They linked to solve old posts, that indicate the main thing we should explain is why you should use macros.

  expr = x + y
  # instead of
  model = @expresssion(model, x + y)

[odow]

@baggepinnen I'm looking into your suggestion.

What part of the error message isn't clear? https://github.com/jump-dev/JuMP.jl/blob/64b290a85e4e27a2e6f40174d4e9120657f3e3c2/src/sets.jl#L80-L84 Do you have examples of where this error message wasn't sufficient?

[baggepinnen]

If I want to minimize the norm of an expression, I need to rewrite my problem into minimize t and then add the constraint in the error message. That is not obvious to everyone.

[odow]

Closing since these are done for now. I will re-open if there are new suggestions.

[sean-lo]

Hi! I have a comment on the ambiguity in the docstring for RotatedSecondOrderCone() on whether we are taking the 2-norm or squared 2-norm of the vector. The docstring describes it as "the square of the euclidean norm of a vector" while the mathematical formula in the example shows ∥(x−1,x−2)∥_2 ≤ 2tx.