Bill Wood wrote:
On Wed, 2006-12-27 at 09:13 -0700, Shawn Willden wrote:
I'm looking into the possibility of using LyX for design documentation, and I'd
like to get some feedback on the feasibility of what I'd like to do, and
recommendations for packages that might help.
We currently manage all of our design documentation as Microsoft Word
documents. There are numerous problems with this, which I probably don't have
to describe to the readership of this list.
The advantages I see to using LyX are:
More standardized output. We have Word templates, but obviously Word allows
people to munge the doc however they like and, frankly, very few people
actually know how to use Word, so they tend to screw things up with no idea how
to fix it. I think an appropriate document class can provide consistent layout
and formatting (though I'm a raw novice with LyX and LaTeX).
Prettier, more readable output. LaTeX just produces better results than Word.
Better change management. We can put our documents in CVS! And perhaps even
merge changes from parallel work streams, etc.
Easier document creation/editing. Word is a PITA to use, and people tend to
spend lots of time tweaking things. I think separating text entry from
fiddling with formatting (and making fiddling with formatting hard) will
significantly reduce time spent on documentation.
Shawn, unfurtunately I can't supply any detailed help since I've been
away from using LaTeX for awhile and I'm just starting to use Lyx. I
can tell you, however, the LaTeX *can* be used successfully for design
documentation. A company that I used to work for used LaTeX for all the
support docs for a special-purpose computer and associated OS. Both
hardware and software designs and implementations were documented in
LaTeX, and the (home-grown + commercial) tool chain worked with it quite
nicely. Our process included maintaining design/implementation docs
with the various component source code, etc. and requiring the engineers
to maintain the docs for their parts. These small files could be
integrated automatically into several distinct larger docs on demand, so
LaTeX provided a lot of leverage for keeping documentation in sync with
other parts of the development, build and delivery processes.
There are numerous style files and extensions available that can be used
to produce syntax diagrams and other special-purpose diagrams that are
integrated into LaTeX source. We were also able to produce our own
packages that supported things like diagrams of registers and other
hardware components. This latter does, however, require that somebody
(you perhaps :-) becomes a LaTeX and TeX expert. Our home-grown experts
figured out TeX commands for trade marks and other logos and custom
document styles.
We also exploited the ability to write programs that analyzed system
engineering docs, figured out things like requirements/design tracking
matrices, and churned out LaTeX fragments for inclusion in documents; it
*is* just ascii after all.
-- Bill Wood
Yes, I'll second that. We've managed to get LyX integrated with the
build environment for our software products so that we manage the docs
just like they were source code, using CVS for version control and using
our in-house perl build system to run off the docs as part of the
product. It's taken a lot of work, mind you, but the results are worth
it, partly for the consistent presentation, but more because we can
include automatically generated material which would be tough to
integrate into Word docs (e.g. doxygen output for API reference,
tr2latex for manual pages, dia for figures etc. plus our own automated
catalogue generation for reusable classes). Another big payoff has been
that doc builds are as portable as the source builds, so our linux and
solaris builds produce packages ready to install without having to
include the docs by hand from a windows box with all the risks involved
in that (missing something out, getting the wrong version etc.).
That said, it's not a panacea. A lot of the developers still aren't
comfortable with LyX - they are too used to Word to let go and allow LyX
and LaTeX to do the work for them. I'm always having to explain to
people that they can't just keep hitting space/enter to get extra white
space. Also, any time we have to exchange material with sales people,
they always ask for word docs and get grumpy when told that they can't
have them. Sometimes, although developers accept using LyX they still
want to use tools like Visio for diagrams which raises problems of
version control again (since visio is windows only and, as far as I can
tell, a binary file format).
Anyhow, best of luck.
guy
