In the case of openssl, a big gain would be to simply document the command
line interface better and create a doc centric forum for people to add their
lessons learned filed around the particular feature area of openssl.
WORKING EXAMPLES would be REAL cool. Does anyone on this alias want to let
me or others know how we can update the docs somehow?
-----Original Message-----
From: Carlo Wood
Sent: Thursday, November 15, 2012 8:31 AM
To: openssl-users@openssl.org
Subject: Re: I can't believe how much this sucks
On Tue, 13 Nov 2012 14:11:17 -0700
t...@terralogic.net wrote:
This is just a NORMAL way for a programmer to work IMHO. I HATE
comming into undocumented code years after its been written and IMHO
its a big booby trap because its very easy to miss something and that
creates hard to find bugs. Really criptic error messages don't help
this. I've looked in the OOS community and there are attempts to put
together systems and one I looked at was OXYGEN.
I concur. When I was 12, I wrote compact code with only single
character variables and no documentation. For some reason I was able to
have thousands of code lines all in my head at once and I had no idea
why I'd need to add documentation.
When I got older, I started to use more descriptive variable and
function names, mostly for the purpose of being able to
'grep' (reg.exp) them in large code. At some point I completely did
away with abbreviations and only used complete English words,
discovering that code is incredibly better to understand when the
variable names express exactly what they mean (to the point that it
avoids bugs). I still didn't see the point in documentation however:
the code explained itself as if it was English.
Only when my memory started to get worse and I couldn't remember
Megabytes of code anymore, especially when my code became so complex
that I had to use Object Orientation because it was impossible to keep
an overview, I started to document code. The funny thing is: I did this
mostly because I knew that a year later I wouldn't be able to
understand it myself anymore if I didn't; not because I thought that
anyone else might need it.
Now, after more than 30 years of coding experience I have reached the
same conclusion as terra wrote: Code is only as useful as it's
documentation. Don't bother to write code without good COMPLETE
documentation as it's worthless: only you, the developer (with a good
memory on top of that) will think it's trivial and usable. Everyone
else will not be able to use it.
http://www.stack.nl/~dimitri/doxygen/
I have no idea at this time how useful this would be.
Perhaps the best we might be able to do on the user side is a wiki
and perhaps one exists.
I did a google search on this.
https://help.ubuntu.com/community/OpenSSL
^ I did find this and I did not look very hard. Maybe there is
something better. If there is then it doesn't come up in the 1st
hits google finds.
So I think we can do much better.
Just my 2 cents.
--
Carlo Wood <ca...@alinoe.com>
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majord...@openssl.org
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majord...@openssl.org
