1. The project is a hobby and that they don’t have time to write decent documentation.
2. Anybody that has any knowledge of computer programming should be able to figure it out. If you don’t have a Ph.D. in Computer Science, you shouldn’t be in the IT industry.
My response to that is this:
1. If they had planned and organized their project from the very beginning like they teach you to do in college, the documentation would have been written before they ever wrote a single line of code. Should it come as a surprise then that their project is so buggy from the get-go? Poor planning and poor documentation is the sure sign of an amateur. Period.
2. What is the point of creating software for someone to use if nobody can figure out how to use it? I have better things to do with my time than reverse engineering their project even if I was a code-head. It would be easier and more cost effective to purchase a retail version that is well planned and well documented. Heck, it might even be more cost effective to write it myself or pay someone else to write it!
3. Everyone in the IT industry does not have Ph.D.s in Computer Science. In all the places I’ve worked in my 30 year career, less than one-third of the people I worked with had any extensive formal computer programming training and experience.
4. If your program, like syslog-ng for example, is “written by programmers for programmers” not everyone that knows how to program know how to program in C# or whatever language your program is supposed to emulate.
If a user can’t figure out how to use a piece of software without having to reverse engineer it first, what is the point of writing it in the first place?
Take for example this article I recently read entitled "Receiving Messages from a Remote System" for the rsyslog logging software installed by default on my OpenSuSE Linux PC.
1. It says "Note that the server port address specified in $InputTCPServerRun must match the port address that the clients send messages to." In the sample configuration file that immediately follows this statement, there isn’t one single line that even contains "$InputTCPServerRun". So how am I supposed to use this statement? When? Where?
2. The author writes that to receive logging messages from remote devices, certain plugins need to be loaded at the start of the of the configuration file and shows examples in the sample configuration file. After the sample configuration, the author states that you need to activate “listeners” and that loading the “plugins” is not sufficient.
- Are "plugins" the same as the "modules" that are loaded in the configuration file? He doesn’t say.
- Nowhere in this article, or any other article, does he specify exactly what a "listener" is, nor does he describe how to "activate" them. Is a listener the same as a filter? A ruleset? Who knows?
4. In another document "Storing Messages from a Remote System into a Specific File", the author writes "It is important that the rules processing the remote messages come before any rules to process local messages." He doesn’t mention that in this document anywhere.
5. I enter the "Config Statements" shown in the document exactly as written and they don’t work.
- Error messages in the log files say that "no listeners are defined – no input will be gathered" among others. Why would anyone put a incomplete, non-working configuration example in their documentation? What is the point in doing that?
- The configuration is for TCP, but most logging programs send their log messages via UDP (including Cisco, which is what I’m trying to receive messages from). What good is a configuration that receives only TCP to me?
- module (load="imtcp")
- input (type="imtcp" port="514")
- In other examples he uses "$Modload imtcp" but doesn’t explain why there is a difference.
The documentation on the rsyslog website is extensive, yet there is nothing there, that I can find, that is actually usable. It’s like trying to hunt down little bits and pieces here and there in the various different articles and then try and fit them all together like a jig-saw puzzle. Yast’s description of rsyslog says that it is easy for novices to use.
I’d be willing to bet real money that they never actually asked a novice user to try and figure out how to use it before making that statement.
Why people say on the Internet that this logging program is better than the old syslog program is beyond my comprehension. I am going to unload rsyslog and load the old, tried and true syslog.
As far as syslog-ng is concerned – though I do have some programming training and experience, I don’t have a Ph.D. in Computer Science. My degree is in Electronics Engineering Technology. I don’t have the time or the motivation to learn their programming language. I need something that’s KISS. I don’t need something that will clean the kitchen sink. Whatever happened to
Keep It Simple Stupid?
What about the Windows logging program called Kiwi? It doesn’t support IPv6. REALLY? With the remaining IPv4 address allotment being exhausted in a matter of months, Kiwi won’t support the newer IPv6 addresses? Who’s the genius that made that command decision?
The university I went to required engineering majors to take a class in technical writing in addition to the usual English Composition classes. Don’t all universities require engineering majors to take a course in technical writing for graduation? Sadly, apparently not.
