Doc board

cmb

hi all,

welcome to the new doc board.

I've messed with far too many options for wikis, and other means of documentation formatting. Personally, I like m0n0wall's DocBook XML, but I don't think virtually anybody else does.

So…here I go again. Any suggestions for something to use? I'm poking around with Dokuwiki right now, and will probably end up sticking with it unless somebody presents a better option (just because I'm tired of looking through packages and we need to get something going already...).

simpat1zq

I would think that the best way to go here is to make your own. Make it look just like the web interface for pfsense, and when you click on something, (like say, Firewall -> Traffic Shaper), you essentially get a picture of the same page you would see in the web interface, but with a little "help blurb" under it.

And taking that one step further, you can just build the help directly into the ISO, and just put the help in with the web interface. Every dropdown, text field, check box, etc would have a little question mark next to it.

And you may consider redoing the forums to match that, so it's easier for people to get support.

I've seen a few programs documented this way, and it makes navigating the help so much easier.

rds_correia

I disagree.
That kind of documentation is very good for programs that don't have much choices in them.
I mean, pfSense is full of features and there should be a nice guide for:
-setting up your firewall
-setting up port forwarding
-setting up PPTP vpn
-setting up IPSec vpn
-setting up IP road warriors
-…
There's just too many options to have it your way simpat1zq.
We need a good initial setup guide based on the install wizzard.
And then we need some guides to help us setting up specific tasks.
For instance it would be nice to have a guide with the essential steps to debug a problem.
Basically where to look (which log) and what to write down when a specific problem arrises.
Just my 0.02€

sullrich

I think any wiki that will export a PDF is a good solution. We can export the manual pages to PDF and include them in the webConfigurator, etc.

colin_

@cmb:

So…here I go again. Any suggestions for something to use? I'm poking around with Dokuwiki right now, and will probably end up sticking with it unless somebody presents a better option (just because I'm tired of looking through packages and we need to get something going already...).

I've personally been formatting the package documentation with LaTeX, which can be exported to a wide variety of formats (dvi, pdf, html, etc. etc.). Not sure what everyone else thinks of it, but I thought I'd throw that option out there.

cmb

@simpat1zq:

I would think that the best way to go here is to make your own. Make it look just like the web interface for pfsense, and when you click on something, (like say, Firewall -> Traffic Shaper), you essentially get a picture of the same page you would see in the web interface, but with a little "help blurb" under it.

That's way too much trouble at this point. We'll be lucky to get some things together using software already written. DIY is not up for discussion at this point.

cmb

@colin_:

I've personally been formatting the package documentation with LaTeX, which can be exported to a wide variety of formats (dvi, pdf, html, etc. etc.). Not sure what everyone else thinks of it, but I thought I'd throw that option out there.

If we're doing something like that, I'd rather stick with DocBook. Problem with either of those is the potential contributor base is much smaller than if you use something like a wiki. Just because people don't want to mess with it.