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
