On 24 April 2014 00:21, Daniel Kahn Gillmor <d...@fifthhorseman.net> wrote: > On 04/23/2014 04:52 PM, Matt Caswell wrote: >> I am actively seeking people to help out on the OpenSSL Wiki. >> Documentation is an area where OpenSSL has frequently been criticized >> in the past and is an area where we can do something about it NOW. > > fwiw, i actually don't think that a wiki is going to improve the places > where OpenSSL documentation is legitimately criticized.
In my view there are three types of documentation that are required within OpenSSL 1) Documentation of the APIs 2) Documentation of command line usage 3) Tutorial/"How do I ...?" type guides and background information See my comments below with regards to the first and second types. With regards to the third type, I think (historically) OpenSSL has been very lacking in this type of information, and it is this need that the wiki is primarily seeking to address. We have already made a lot of good progress, and I believe there is some really good content on there. There are however some major gaps, which need to be filled. I believe the wiki is perfect for this type of documentation. > > historically, OpenSSL documentation (e.g. manual pages, etc) has > seriously lagged its implementation, and has in some cases been simply > wrong. Updates to the wiki won't improve the quality of documentation > shipped with the library, which will always seem more authoritative > (because it ships with the specific version of the software that is > installed; advice found on the web may be either older or newer than the > local version) > > A serious way to fix this is to have the documentation produced *from* > the code, so that it gets upgraded in sync. For example, neither > x509(1ssl) nor "openssl x509 -help" ever mention the -sha256 option, > but that option has been supported for years. > I agree with this (at least for the first type of documentation - documenting the APIs). In fact, by co-incidence, I installed and started to run some experiments on the OpenSSL codebase with doxygen a couple of days ago. Some questions remain for me: 1) How would we/Should we convert the existing API documentation into doxygen (or similar). I suspect some of it could be easily copied over, whilst other parts may not lend themselves to this "inline" style. I was planning to do some further experimenting with this to understand the feasibility. 2) With respect to the second type of documentation (documenting the command line) its less clear to me how well this inline documentation would work for the command line stuff. Again I was planning to run some experiments with doxygen and see how well it works. Matt ______________________________________________________________________ OpenSSL Project http://www.openssl.org Development Mailing List openssl-dev@openssl.org Automated List Manager majord...@openssl.org
