gasche/manual-ocamlbuild

Outline

Opened this issue · 0 comments

In editing and using this manual I think it is important to get agreement on the layout or outline of each section. In particular, a way of addressing questions such as:

  • What are the major sections of the manual?
  • What belongs in what section?
  • What level of detail to use in the respective sections?

I'll try to give brief answers to the above as a starting point for discussion.

Major Sections:

  1. Table of contents (not really a 'section)
  2. Introduction
  3. Reference
  4. Appendix (Index, Glossary?, FAQ?)

Description of sections:

  • Intro: A fast and readable tour that describes the features of ocamlbuild. Light on details.
  • Reference: Provide a description of how to use ocamlbuild. Heavier on the details, but in an ordered (TBD) way.
  • Appendix: Tables and indices that can be almost used as documentation.