[darcs-users] Separating the user manual and code

Trent W. Buck trentbuck at gmail.com
Wed Oct 22 04:27:20 UTC 2008


When Eric invited me to become documentation manager, I mentioned that
one of the first things I'd do is push for physically separating the
user manual from the actual code.  Because this was probably done in IRC
just before one of us went to bed, it got forgotten about.  I'd like to
put the issue on the table here on the list and solicit discussion.

At present the user manual are generated from literate haskell (lhs)
source files.  These files also contain the source code and the API
documentation (haddock).  What I'm proposing is moving all the user
manual parts to doc/.  The haddock API documentation stays with the
code, because it's relevant to hackers, not end users.

Arguments for mixing the user manual with the source code:

  If there's no dedicated documentation team, then the only people who
  can keep the user manual up to date are the hackers themselves.
  Mixing the user manual and the source code help hackers remember to
  update the manual as they update the code.

  Updating the user manual and the code in the same patch has some nice
  consequences when cherry-picking patches; the user manual is never
  "wrong" or out of date.

Arguments for separating out the user manual:

  It's unusual for people to be good at both hacking and technical
  writing.  If technical writers are available to work on the user
  manual, then it'd be better to let the hackers do what they do best.

  As hacking and technical writing are indepenent roles with little
  overlap, and any individual line is usually either only code or only
  user manual, then it makes sense to put them in separate files.  After
  all, the hacker doesn't want to be distracted by verbose, high-level
  explanations for end users, and the technical writer doesn't want to
  be distracted by detailed low-level code details.

  Using separate files means that the user manual can be arranged
  differently to the underlying code modules.  You can already see this
  done for some sections of the user manual that don't have
  corresponding code in src/*.tex. There's also some clever code to
  arrange the "Darcs commands" section into some logical subsections
  that doesn't occur with the source modules.

  This clearly separates API documentation (which is targeted at other
  hackers) from user documentation (which is targeted at end users, who
  just want to run darcs, not change it).  For example, the "Introduction"
  section at the top of Lcs.lhs is really API documentation.

  Literate Haskell means the user manual source has to be TeX.  A
  separate tree would allow us to evaluate alternative source formats,
  such as texinfo, docbook or restructured text (reST).

  It would also make it easier for us to include translations of the
  user manual (into other human languages).  It's not obvious to me how
  that can be achieved using literate haskell.

  Lastly, Emacs isn't very good at handling two very different languages
  (like Haskell/TeX or XHTML/Javascript) in a single file, and tools
  like literate-haskell-mode or mumamo only partially address this. :-)



More information about the darcs-users mailing list