Re: Faq format

Thanks for the advice; due to the consistency of the source html I figured
y'all used some sort of automated tool to generate it - as always I am
impressed at the quality that the Openbsd community produces.

Speaking of work wikis, I bring dokuwiki everywhere I go - I like it because
all of the content is in flatfiles. I can edit the pages in vim and do large
search/replace operations using tools like find and sed; I also like it
because I can can generate automated pages using any scripting language that
suits me.

I am finding, however, that most people at my workplace require a more
wiz-bang approach to documentation - since I have a lot of Linux/BSD
documentation written I was hoping to convert all of my stuff into something
centralized and simple enough for people not to bother asking me to copy/paste
it into a java monstrosity of a wiki (Atlassian Confluence). Since dokuwiki is
somewhere in between wiz-bang and minimalist, I'd prefer to go minimalist and
make my stand there. Who can argue with the guy who's written 90% of all
documentation at a company?

Maybe I'll go with a customized markdown-to-html script or just roll
guerrilla-vi style like you - thanks for the information everyone!

Niko

________________________________________
From: Nick Holland [[email protected]]
Sent: Thursday, May 17, 2012 9:25 PM
To: Niko Gonzales
Cc: [email protected]
Subject: 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]






















.