[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 literate-haskell-mode or mumamo only partially address this. :-)
More information about the darcs-users