[wplug] Writing Tech Manuals

[Gentgeen]

I first want to thank everyone for their response to my original
posting, it gave me some great things to think about.

With the movement towards using Subversion, I have decided to go that
route (I know there are great reasons for both.... vi vs. emac anyone?)

After reading the first few chapters of the Subversion manual, I now
have a follow-up question, mainly directed toward those of you that have
written manuals before.

As noted before (see below if you are new to the thread).. these
"manuals" are not like the books that come with software/at the book
story, but more like the HowTos/Mini-HowTos that you find at TLDP. 
Things like "How to set up your email" and "How to use the Online
School".  There will be some directed towards students, some towards
parents, and some towards the staff.  Each one will be done with La-TeX
as the original source, then I an export them as HTML, PDF, etc based on
my final needs.  I expect that they will be short, maybe 3 or 4 pgs.
each.

Now for the question :-) .... Any thoughts on how to set up the
Subversion repository?

My way of thinking right now has each audience similar to a completed
book.  So I am kind of writing 3 books, "How to be a
Student/Teacher/Parent in PAVCS".  Then each howto is like a chapter in
the book.  So my thought is to set up 3 repositorys/projects, one for
each
audience/book.  Then within the projects there would be the various
manuals/chapters.  

I know that each HowTo will be a project by itself (i.e. one will not
have to read #1 before reading #2) but it seems kind of silly to set up
1 repository per HowTo.  

Those of you that have done this before... Does this sound like a good
idea?  Maybe you have a better way, or found something out during your
experience.  Any feedback will be appreciated.

  


On Sat, 24 Jun 2006 10:47:34 -0400
Gentgeen <gentgeen at linuxmail.org> 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 
> 
> 
> 
> -- 
> http://gentgeen.homelinux.org
> 
> #############################################################
>  Associate yourself with men of good quality if you esteem    
>  your own reputation; for 'tis better to be alone then in bad 
>  company.        - George Washington, Rules of Civility
> _______________________________________________
> wplug mailing list
> wplug at wplug.org
> http://www.wplug.org/mailman/listinfo/wplug
> 




-- 
http://gentgeen.homelinux.org

#############################################################
 Associate yourself with men of good quality if you esteem    
 your own reputation; for 'tis better to be alone then in bad 
 company.        - George Washington, Rules of Civility