Wednesday, November 26, 2014

Snort FAQ is now on Snort.org!

When the old Snort.org was still around, we had a section for the FAQ on the documents page. However, contributions to the pages involved sending in suggestions to the admins of the site, via email, and then the changes would be shoved onto the site using regular old html, and then the site had to be pushed.

While this worked, it truly wasn't in the same participatory community that has made many open source projects, including ours, truly inclusive of the community. To counter this, the FAQ was moved to github. Here it allowed forking, editing, pull requests, etc, all in the easy to understand format of Markdown.

Since the move we've had several hundred changes submitted by way of pull request through github, as well as people submitting information the old fashioned way, via the mailing list, or email directly to us. However, the FAQ was on github itself, requiring you to visit an external page off of Snort.org, and then somehow navigate back, if you wanted more content on Snort.org such as other documentation.  

We found this experience to be cumbersome and downright awkward. The user experience was bad, and while no one really complained a great deal, we thought we could do better. 

So now, the FAQ is back on Snort.org. While the content is rendered seamlessly on the page, the meat of the information is actually pulled from Github. This allows the best of both worlds, to allow the user experience of github and allow forks, pulls, etc, the content is now beautifully rendered on Snort.org, providing a much better experience. 

We'd like the community to participate, to create pages, update FAQs, and provide content that you believe would help the Snort community.  You may do so by going to Snort's github page, and either forking, making edits, and submitting back to us, or creating a branch and submitting back to us. We'll review the content for integrity and to ensure it is correct, so we don't have bad, incorrect, or mis-information out there. 

The intent is to make Snort.org, truly the home, of Snort and its ecosystem.  There are around 60 known projects out there that participate or create a project to augment Snort, its input, output, or analysis.  I'd love for every one of those projects to have their own section in the FAQ.

Got an answer to a question that is asked every day on Snort's mailing list?  Create an FAQ page for it, let's point people to that.  Wrote some documentation to help people out with turning off LRO on their NIC?  Submit it!

Let's create a documentation repository.  We'll keep it cleaned up, neat and tidy on the site and make sure we are following all the appropriate rules surrounding content as well as layout in Markdown, etc.  But the content should be living, changing, and updated, and I'd love to have everyone participate.

Check out the Snort.org Documentation page, you'll see on the left hand side the "Snort FAQ".  You'll see all the current pages on the FAQ that people have created over the years, as well as the READMEs that are contained in the doc/ section of the Snort tarball.  Along with the Snort Manual that is also linked from the Documentation page, it should be much simpler to find the answers you need to almost any Snort question.  If you want to participate, head on over to the Github page, create your own branch, and start editing!

I'll be moving some of the one-off documentation that we have on Snort.org to the FAQ in coming days.

For a Markdown primer, head on over to Daring Fireball, the creator of the Markdown format.

A big thanks to our web team here in the Talos Group for making this happen!

No comments:

Post a Comment