On 9/22/2014 1:55 AM, alex chiosso wrote: > Hi . > I have to be agree with Gene on the man pages > interpretation/description/decoding . > I'm not criticizing anyone and I appreciate the efforts that the project > stuff is making everyday . > But reading some hal component man pages sometimes the description is > hermetic and cryptical and even missing a clear example on the usage and > the correct instantiation . > For sure for the most of you (gurus and geeks) everything is clear but for > a medium brained like I am sometimes is really hardful (even impossible) to > understand correctly what the man page mean .
Instructions that assume prior knowledge of something, or do not have pointers as to where else in the instructions (or online) all required information can be found are often not much better than no instructions at all. Of course a problem with documenting a rapidly developing system like LCNC is the rapid development. Most such projects, especially when worked on by people working physically far apart, suffer from an initial lack of standard practices for documentation, user interface and internal conventions. They start off with many people each expecting to do some things their own way and inevitably collisions happen. A couple of examples. The GIMP, an open source image editing program. It works but is an inconsistent mess due to contributors putting their additions wherever they like instead of where they logically ought to go. ZenCart, an open source e-commerce system. It works well enough and from the customer side appears the be pretty slick. But for the retailer's view it's rather awful. Just one of its faults is the inconsistency in terms for enabling or disabling something. Various parts use 1/0, on/off, true/false and just about every other such pair of terms. As a project reaches a plateau of completeness and usability, it needs to be put through a "rationalization" process where external and internal consistency is reviewed and fixed as needed. Code gets cleaned up and documentation spiffed up and multiply checked for accuracy. That process benefits the programmers as much or more than the users! Being able to go to the docs and finding current and correct information on someone else's part, and knowing that something like a named variable is not going to be changed on a whim, or actually is what the docs say it is, makes the work much easier. It's also a good practice for one person projects. Shovel out the junk, make sure what is left works, then document it. One of the very best instruction manuals I ever encountered was the one for the IBM PC jr. A person could sit down with that book, having completely zero knowledge of computers, and be able to plug everything in, boot it up and be using it. And lo! The computer 'elite' who learnt their craft in hallowed halls quaked in their boots that mere peons who knew not what a transistor was would be joining the ranks of the users... ;-) I do recall some whinging from certain sorts of people in the 80's about computers becoming too easy to use. --- This email is free from viruses and malware because avast! Antivirus protection is active. http://www.avast.com ------------------------------------------------------------------------------ Meet PCI DSS 3.0 Compliance Requirements with EventLog Analyzer Achieve PCI DSS 3.0 Compliant Status with Out-of-the-box PCI DSS Reports Are you Audit-Ready for PCI DSS 3.0 Compliance? Download White paper Comply to PCI DSS 3.0 Requirement 10 and 11.5 with EventLog Analyzer http://pubads.g.doubleclick.net/gampad/clk?id=154622311&iu=/4140/ostg.clktrk _______________________________________________ Emc-users mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/emc-users
