It is (very slowly) getting better, but it still needs a lot of work. I'd love to have some help with it, so I figured I'd write up a few ways you can help.
One of the best things you can do is read the documentation. Read it to yourself, to your child as a bed time story, or just out loud to a rubber ducky. It doesn't really matter how you read it, just read it. You can spot more errors in the documentation when you read it. It's a fact!
If you spot an error, an omission, or just something that should be improved let me know.You're more than welcome to email me (my email's all over the mailing list), catch me on irc (#ossec on irc.freenode.net), or open a ticket. Opening a ticket is probably the most reliable. I'll probably just open a ticket if I'm contacted any other way.
Just like the base system, we use mercurial and bitbucket to manage the documentation. The main repository for it is https://bitbucket.org/ddpbsd/ossec-rules. bitbucket has a decent issue creation page, and it'll send me an email when a new ticket is opened.
 |
| Open Tickets |
Creating a new issue is easy. If you don't know something, leave it at the default. Please include as much information as you can about the issue, it'll make it easier for me to fix it.
 |
| New Issue |
If you want a more hands on approach, you can fix problems yourself and send me the changes. As I mentioned above we're using mercurial and bitbucket for the repository. To build the documentation we use Paver and Sphinx. Sphinx uses the reStructuredText markup language.
Start by simply cloning the repository with "hg clone https://bitbucket.org/ddpbsd/ossec-rules":
 |
| ht clone https://bitbucket.org/ddpbsd/ossec-rules |
"hg commit" will commit the changes you make to your repository (use "hg add FILE" to add FILE to the repository if FILE is new). "hg outgoing https://bitbucket.org/ddpbsd/ossec-rules" will create a diff of all changes you've made to the repository. You can email that diff to me, and I'll look at integrating it.
You can skip the last bit by forking my ossec-rules repository using the fork button on my bitbucket page (you will need your own bitbucket account, it's free).
 |
| Fork the repository |
 |
| A fork in progress |
Once you've forked the repository, clone it using the "hg clone" command with the URL for your own repository. Then make and commit your changes, and finally push the changes back into your repository with "hg push".
After you've pushed a change into your repository, you can initiate a "pull request" against ossec-rules. Include a little description to give me an idea of what changes you've made. I will then be notified of the request, and have the opportunity to pull those changes into the main repository.
 |
| pull request |
Keep your eyes peeled for a second documentation post later this week.
I am reading this blog for the first time, so I don't know anything about you, good, bad, famous, whatever. That being said, I also have yet to read what documentation exists for OSSEC already. I am quite interested in this project however, as a former security practitioner. It has great promise.
ReplyDeleteIf you are going to "take over the project" for documentation of anything, and that "was awhile back", then you need to have already made a commitment to that community (and yourself) to work on that. If you find that you cannot make steady progress, or have lost time, energy, enthusiasm for following through, then just "give it back". let someone else have a shot who does have the time, interest, enthusiasm to see it done. There appears to be a large interest in this application and those people deserve GOOD documentation. Please, work steadily towards some completion or else give it up. It is not any poor reflection on you ar your ability. Simply your consideration for the community who wants and needs the information so that they can make maximum use of a nice toolset.
I recently evealuated Snorby and the documentation for that is pathetic. A nice tool which is missing a large part of its audience due to lack of good documentation.
I am retired from a 40 year career in computing, mostly as a developer but with some system administrator, system programmer, pre- and port-sales support thrown in. Since I learned early that good documentation was key to learning good tool usage, I was always committed to produce the best product whenever it came time to document that which I developed or assisted in bringing to market. It wasn't a business requirement; it was a commitment to all the others who I knew, were following me up that ladder of learning.
Do it right or let some else do that. Good luck.
Wow, lighten up Francis. Its an open source project, and anyone helping is a good good thing. If you think you can do a better job, then you do it.
Delete@CDC-EX: I'm a nobody, so no worries.
ReplyDeleteI've improved the documentation. No, it's still not what I would consider good, but it is better than when I started.
I'm not going to give up on it, I just need help. If I write something in the documentation I want it to make sense to everyone, not just me. I've had my head stuck in OSSEC for a little while now, so a lot of things are just "common sense" to me now. But someone who needs the documentation more than I do may not understand what I've written. And I do make typos. And I'll miss things, or confuse things.
I'm not giving up on the documentation, but I'm also not going to sugar coat the current state. Documentation is incredibly important, and I want OSSEC to have some of the best. That's hard to do, and it'll take time.
Thanks for your comments. :)
The documentation is not that bad. I've seen much worse. I have two suggestions to support making things better:
ReplyDelete- Crowdsource: put it in a wiki or at least enable the wiki next to the documentation
- On each documentation page: enable comments with easy login
What is kinda not so good is the web interface. I would love to control and manage OSSEC via a user restricted web interface.
Anyway I think that OSSEC and the documentation beeing available as they are is better than not beeing there at all.
OSSEC has quite some features and I would very much like to read more about adaption, extension and experiences others have running it.
Therefore there should definitly be more community/social features on the website.
Thanks for the work!
Your work did help me.
Don't give up.
We tried a wili, no one contributed. We hated it, and you can see how much. There's spam all over it.
DeleteI think comments in the documentation is HORRIBLE. The comments are never as up to date as the documentation, and all they do is distract from the actual content.
Generally I think the "social" features in documentation are trashy. If someone wants to contribute, they will.
There is no web user interface. People keep talking about making one but nothing's really come of it.
Dan,
ReplyDeleteI like what you have done on OSSEC. Great help!