[wplug] Writing Tech Manuals

[Michael Semcheski]

Kevin,

I just wanted to make two comments regarding source control:

Source control is very useful, even for binary files.  I think the
ability to do a diff is great, but you can also add a message which
describes what changed when you commit.  This works for binary or text
files.  Source control facilitates working on multiple copies of the
same file.  I try to use it for all work-products I create, regardless
of whether its binary or text.

Second, I'm not that familiar with Subversion, but I think CVS gets a
bad rap.  The thing that I really like about CVS, which I don't think
Subversion can do, is that CVS keeps the source repository in a normal
directory hiararchy.  That is, if you cd to the CVSROOT directory,
you'll see the same hierarchy of files that you have in your project
directory.  You can copy, move, delete files directly in the
repository.  Yes, you can get yourself into trouble if you abuse it. 
But, it can be handy.  And if (and this has never happened to me) a file
becomes corrupted, well, big whoop.  You might lose some history info. 
What if your subversion database gets borked?  Maybe you should use
Subversion but check the subversion database file into CVS.  But
seriously, I like the fact that CVS keeps everything in the filesystem
with one file in the repository for one file in the project. 

I think other people raised valid points which may conflict with the
views expressed in this email, and you should consider them as well.

Mike

Gentgeen wrote:
> Dear List,
>
> For the next school year, I know that part of my job description will
>  include writing "tech manuals" (for lack of a better word).  These
> manuals will cover a number of issues that we see in our school (an
> on line virtual school).  Some will be for the parents, some for the
> staff, and some for the students.  These "manuals" will probably be
> pretty short, kind of like the Linux mini-howtos.
>
> I am currently thinking that I would like to do them with LaTeX
> (maybe via LyX) so that I can create HTML, PDF, etc all from the same
> source. If I recall properly, there is even something like CSS for
> LaTeX, so I could easily make all the files similar in appearance.  I
> am also thinking that with LaTeX I will be able to use CVS type
> software to help keep track of the changes.  Since I am not very
> familiar with either, I need to get an early start so that by the
> time they tell me what topics to work on, I will be ready.
>
> I am wondering about anyone else's experience/thoughts.  LaTeX a good
>  way to go?  CVS a good way to go?  Would OpenOffice and stylesheets
> be a better way?  Would OpenOffice work nice with CVS?  And what ever
> else anyone might think of since this would be a new realm for me.
>
> Kevin
>
>
>