The GAMS documentation has changed considerably since it was first released in 1988: in format, in scope and content, and in how it is distributed and accessed. At the same time, it maintains many elements of the original style: part tutorial, part user's guide, and part reference manual. We describe here the evolution of the GAMS documentation and related topics.
The first published GAMS documentation is the book GAMS: A User's Guide (aka the "red book") by Brooke, Kendrick, and Meeraus, published in 1988 by The Scientific Press. Copies were sold in bookstores and included a chapter on the model library (100 models at that time), a much-appreciated and well-used index, appendices describing the solvers available (MINOS and ZOOM), and a 5.25 inch floppy disk containing a student version of "PC-GAMS version 2.05". This was followed up in 1992 with GAMS: A User's Guide, Release 2.25 (aka the "blue book") by a different publisher (Boyd & Fraser), a soft cover, and no floppy disk: by this time the software was available directly from GAMS. The final section of installation notes in the red book was replaced in the blue book by notes on the new features in GAMS 2.25, but the content was otherwise unchanged.
As the pace of development increased, it became clear that we needed a new documentation scheme, one that would allow us to update the document continuously as language features, models and model libraries, solvers, and tools/utilities were added to or updated in the system. Consequently, we converted the existing documentation to MS Word, expanded, updated, and edited it as appropriate, and sent it to the copy shop to be printed. This was a group effort spearheaded by Ramesh Raman, whose name was included as an author in the User's Guide first included (along with a CD) in shipments of our 18.0 release in Feb 1999. The solver manuals in this release were collected from various sources (with varying styles, content, and organization) and put into a separate binder. A further push was required to unify this solver documentation (using LaTeX) to use a common style and organization: this unified Solver Manual was included with the 21.0 release of May 2003. In addition to hard-copy, all of these documents were included as PDF in the GAMS system and freely available via the Web. Thus, the shift away from published documentation to manuals produced in-house went hand-in-hand with a shift from printed documents to viewing and searching PDF documents.
During this time Bruce McCarl had been regularly teaching GAMS courses: basic and advanced, targeting a general audience but with a distinct flavor of agricultural economics. As part of this he developed course material to use in his classes, and he was in a good position to notice that the GAMS User Guide was not keeping up with all the updates to the software. With some encouragement from GAMS, Bruce started the ambitious project of creating a new GAMS User's Guide, one that would be more complete, more to his taste with an increase in tutorial flavor, and designed to take full advantage of being a Web document: linked, cross-referenced, searchable, and indexed. The end result was the McCarl Guide that emerged as a PDF based on a Word document in 2002. This was redone in the more convenient CHM format with the 22.1 release of Mar 2006 and renamed as the Expanded GAMS Guide (McCarl) in release 22.3 of Nov 2006. We also kept the original GAMS User's Guide, by this time as PDF generated from LaTeX source. With its improved content, organization, and navigability, Bruce's new guide was a boon to all GAMS users, not just those taking his courses. We owe a debt of gratitude to Bruce for this and many other contributions.
The Expanded GAMS Guide (McCarl) was never intended to be printed and was not shipped as hard-copy with GAMS. In 2013, GAMS stopped making physical shipments altogether and moved to an online order-fulfillment system. For those who still wanted printed documentation, the documents were also made available via Amazon's CreateSpace, but most users browsed the documents online or as part of an installed GAMS system, often via the GAMS IDE, so the need for printable documents was small and growing smaller.
Having two user's guides was counter-intuitive or confusing for some users, especially when the content for some topics was different, missing, or even contradictory. The additional effort required to maintain two documents became more noticeable, especially since the Expanded User Guide (McCarl) was implemented using a Windows-only product that did not lend itself to version control via SVN or git. When we documented our object-oriented APIs in Feb 2013, we used the opportunity to experiment with a doxygen-based authoring process that uses text files as source, is platform-independent, and produces output in multiple formats. The results were good, and in 2015 we hired a consultant, Martha Loewe, to research what it would take to convert all of the GAMS documentation to use the doxygen-based process and to set up a framework for this. We eventually committed fully to this process and produced a unified set of documentation as of release 24.9 in Aug 2017. This involved reorganizing things somewhat to better fit a linked document, merging the two user guides into one (while trying to maintain the best qualities of each), adding links throughout, and submitting everything to review and editing by internal subject matter experts so the content is accurate, updated, and complete. The end result is something we believe is an improvement over its predecessors, but it is also something we are committed to maintaining and improving. The current system allows and encourages immediate updates by the whole GAMS team and has helped foster a culture and attitude where this takes place.