[Os-project-managers] Fwd: Re: Documentation

[R. Kipp Martin]

Gus' suggestion for refactoring manual for ApplicationTemplates -- Kipp 
to revise

-------- Original Message --------
Subject: Re: Documentation
Date: Thu, 13 Oct 2011 22:59:11 -0300
From: Horand Gassmann <Horand.Gassmann at dal.ca>
To: R. Kipp Martin <kmartin at chicagobooth.edu>

"R. Kipp Martin" <kmartin at chicagobooth.edu> wrote:

> Hi Gus:
>
> Your observation today that our User's Manual is really for people
> building OS as opposed to using the binary distribution really got
> me thinking. Right now there are three related OS documents:
>
> 1) Our OS User's Manual
>
> 2) CoinEasy description of ApplicationTemplates (which is really
> nothing more than illustrations of various aspects of OS) see
>
> http://www.coin-or.org/CoinEasy/doc/visualstudio.pdf
>
> 3) CoinEasy description of how to use the OSSolverService
>
> http://www.coin-or.org/CoinEasy/doc/coinEasyServer.pdf
>
>
> I really think COIN-OR does a poor job of showing the masses how to
> use COIN-OR. Very few people ever need to build a project. Rather
> they should either use modeling languages, or OSSolverService, or
> link to libs (as in Application Templates).  We need to create more
> synergy among the three documents. I am thinking somehow combine 2)
> and 3) and then have that serve as our main document but also for
> CoinEasy.
>
> Any ideas?

Hi Kipp,

there is probably a lot to chew on here. I have also thought about it,
and I am not sure I agree that the largest client group will be the
ones wanting to use the OS libraries. There definitely are three if
not four different groups, based on our central tenet that OS links
together modeling languages and solvers:

1a. Those that want to do only that. That is, they use AMPL or GAMS or
CMPL (or MPL?).

1b. Those that just want to use OSSolverService from the command line.
I do not know if this groups is really different from the first, but
the needs are slightly different, and perhaps the documentation should
reflect that.

2. Those that want to use the OS libraries and API to build their own
matrix generators.

3. Us, that is, developers who need to build OS and all that good stuff.

That really is three very distinct groups and therefore three
different documents, and I suspect that we are not the first folks to
see this trichotomy. Don Knuth solved it in the TeX book by using
dangerous bends and double dangerous bends --- how successful that was
is open to debate.

I do not like the idea of three separate documents --- unless they are
proper subsets of each other.

But maybe we can leverage what we have into a single document. Three
parts: Running OS, building applications with OS, developing OS. (They
do not have to be called that, but that is the gist of what I think we
should put there.) What goes into these parts?

Part 1: section 3.1, chapter 7, chapter 9, chapter 6
Part 2: Here we need to talk about chapter 12, 10, 11
Part 3: the rest of chapter 3, chapter 4, 8, 13.

We can slot the CoinEasy stuff wherever it fits best.

I know this is radical, but then, that`s what I do :)

Cheers

gus