Re: Faq format

It's all done by hand.  That's why we tend to keep the formatting very
dull and simple -- it's easy to write, easy (and reliable) in rendering.

I use the stock OpenBSD vi to do the editing.

I've got some macros I made using a .exrc file...so I can hit "F1" to
insert a <p>, SHIFT-f1 to insert a <br>, "F5" inserts a
<blockquote><pre>  </pre></blockquote> pair, etc., for the most common
things I use.  And really, it's quite simple; at work, I have to use MS
Word, I usually have to think about how to make it do what I want more
than I do my FAQ writing and editing.  The only places where I sometimes
wish some magic formatting system was used is at updating time where I
have to change a lot of VERSIONNUMBER to VERSIONNUMBER+0.1, and man page
links are a pain; but that's really the only places I'd appreciate it.
The actual writing of content would not be helped.

We have a very small number of formatting options...it's about the
content, not the CSS, frames, graphics, etc. that people like to brag
about in their fancy websites.

Like the rest of OpenBSD, the man pages are checked out via CVS, edited,
and then committed.  OpenBSD webservers do periodic checkouts of the
same CVS tree, and thus, are updated shortly after changes are committed.

Personally, I tend to have three trees going at once -- the "typo" tree,
where quick-and-simple changes are made.  Update, edit, commit, done.  I
have the "project" tree, where new content and rewrites are done, things
that might be interrupted by several "typo" fixes in the period of time
it take to commit a big change, and the "next" tree, where I put changes
for the next release.  Typically, my "next" tree becomes the new "typo"
tree after the release, and the old typo tree becomes my "snapshot" of
what it was at the end of that release (which I never go back to, so no
idea why I actually keep all that stuff).

My main work tree on my main work machine gets mirrored to a little
netbook computer (first gen Acer Aspire One), where I do a lot of work
while waiting for other things.  I should probably have my own repos
that I work from, other than most of the places I sit around with the
netbook working have no Internet, so the copying of work between the
netbook and the "big" machine tends to be very manual.

More than you probably wanted to know. :)


Unrelated to OpenBSD...for system documentation in the work world, I
find wikis nice.  I've used "Twiki" in the past, I rather liked it,
other than they switched to a "GUI" editor by default, and the version I
used, the GUI editor really sucked.  I'm now using MediaWiki at work,
and I really don't like it, too many features, too complicated, and the
markup language is overly...well...marked up (at a certain point, it
starts re-inventing HTML...poorly.  Twiki was "simple layouts";
Mediawiki has tipped quite completely into "reinveted HTML").  That's
not what you want for system docs...you want something that's easy to
get into, get out of, and not going to make you wonder, "how do I do
that?" because if it puts up the slightest fight, it won't get done.

Nick.

On 05/17/12 15:28, Niko Gonzales wrote:
> Hey,
> 
> Just wondering what you guys use to generate your FAQ pages  do you edit them
> by hand? Or have some automated way of generating them? I'd like to generate
> some of my own for my University's documentation.
> 
> Thanks!
> 
> Niko Gonzales
> University of Denver
> Linux/UNIX Systems Engineer
> [email protected]
> http://www.du.edu/uts/
> [cid:B5BB9927-8E19-4944-A898-6CDE9DF6B557]