I beg to differ and this is one reason I am not very active. Several years ago I contributed a function to determine endianess. I had done it years and years before so it was quite simple for me. I took the time to put documentation in the function. Also I am a professional consulting programmer adn I know both what to document, how to document and how to write code.
Someone came in and removed the documentation. At the time I voluntered to start putting some documentation together. I saw no interest. I agree with those who point out the dreath in OSS documentation and the fact that years after problems have been identified that the docs are still not upgraded and moreover I never found out HOW to do any documentation. Besides which when I contributed a function someone went to the effort to remove the documentation. I have ALWAYS written the documentation for a function before the code because it is much faster and one can design the interface in about 1/4 of the time that it takes to code it. Then if I come back to the function years later I can read the documentation and I know how the function should work! I keep the documenation and the code in the same source file. Then I have utilities which will read the source file and split out the documentation and prepare a printable manual if I want. I've had clients ask me how long to document a rather large system which I wrote and my comment was I can have the manual by noon - which I did and it was 3 cm thick. they were quite impressed. 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. 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. On Tue, Nov 13, 2012 at 01:33:48PM -0600, John Hascall wrote: > > > It's a GREAT product and I love it and am grateful but why after > > years and years do the man pages still say "under construction"? > > Because it is an open source project and the things that get done > are the things people volunteer to do. Most programmers would > much rather create cool things than write about them. > > That said, perhaps this is something that a Google Summer Of Code > project could help get off the ground (money being a pretty decent > motivator for poor students). > > John > > ------------------------------------------------------------------------------- > John Hascall, j...@iastate.edu > Team Lead, NIADS (Network Infrastructure, Authentication & Directory Services) > IT Services, The Iowa State University of Science and Technology > ______________________________________________________________________ > 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
