Netgate SG-1000 microFirewall

Author Topic: Doc board  (Read 10498 times)

0 Members and 1 Guest are viewing this topic.

Offline cmb

  • Hero Member
  • *****
  • Posts: 11226
  • Karma: +896/-7
    • View Profile
    • Chris Buechler
Doc board
« on: December 22, 2005, 09:52:04 am »
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...). 

Offline simpat1zq

  • Jr. Member
  • **
  • Posts: 50
  • Karma: +0/-0
    • View Profile
Re: Doc board
« Reply #1 on: December 22, 2005, 11:01:12 am »
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.

Offline john3voltas

  • Full Member
  • ***
  • Posts: 218
  • Karma: +3/-0
    • View Profile
Re: Doc board
« Reply #2 on: December 22, 2005, 01:36:57 pm »
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
pfSense 2.2.4 running on a HP DL385 G5
WAN bce(4) + LAN em(4) + OPTn em(4) with 10 VLANs + Snort + PPTP VPN soon to be trashed by OVPN

Offline sullrich

  • Hero Member
  • *****
  • Posts: 5110
  • Karma: +7/-2348
    • View Profile
    • pfSense
Re: Doc board
« Reply #3 on: December 22, 2005, 01:48:20 pm »
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.

Offline colin_

  • Newbie
  • *
  • Posts: 15
  • Karma: +0/-0
    • View Profile
Re: Doc board
« Reply #4 on: December 22, 2005, 04:34:56 pm »
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.

Offline cmb

  • Hero Member
  • *****
  • Posts: 11226
  • Karma: +896/-7
    • View Profile
    • Chris Buechler
Re: Doc board
« Reply #5 on: December 24, 2005, 02:00:50 pm »
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. 

Offline cmb

  • Hero Member
  • *****
  • Posts: 11226
  • Karma: +896/-7
    • View Profile
    • Chris Buechler
Re: Doc board
« Reply #6 on: December 24, 2005, 02:04:52 pm »
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.