Dear Steve,
I am pleased you found something useful in my comments.
Just to mention :
Yes I suggest something like you said "...three major divisions:
reference, programming, and
didactic.".
I would just add : "programming/...using", I am thinking about the
command line tools...
although, as they can be called in bash scripts, they can be seen also
as a kind of "system lib".
Ok, I will do my best to help. I already contributed a little to WCE
porting,
I will be pleased to contribute on the command line part of the doc set.
Following your suggestion I suggest something like this :
At the top of the organization, 3 chapters :
- didactic on cryptography and the interest of openssl
- the LIB(s) : then reference, and programmer's manual (a set of howto,
use cases...)
- the command line tools : then reference, and "usage manual" (eg to
produce certs & manage them (check validity, renew, revoke,
import/export...), sample scripts )
***
Something else : I also suggest that some expert, when dealing with
answers to the users list,
decide either to answer to the list as usual or to answer via the wiki
by opening another topic or updating an existing one.
Just to avoid that useful info be lost in the depth of the mails...
In fact I think that, today, we are all using the mails archives as a
wiki...
but it lacks organization as you said, and at a time, the info is lost
because it is not so simple to take many mails together to understand
clearly a pb and its solution.
With the wiki, I think that info will never get lost.
Yours sincerely,
Pierre
Le 19/03/2013 19:53, Steve Marquess a écrit :
On 03/19/2013 10:47 AM, Pierre DELAAGE wrote:
Dear Steve, I was wondering whether the wiki could be "fed" at the
beginning by all the Documents available at
"http://www.openssl.org/docs/";.
Very often people are able to comment, eg, a command page with some
samples or error comments, instead of rewriting from scratch a "man
page".
And this could be a way to only have one unique set of docs to
maintain, and to refer to, instead of having two...
That's an interesting suggestion; I'll kick it around and see what kind
of traction it gets.
...
Moreover, for the lib, I suggest to separate the "reference manual",
describing and commenting each api call, from a kind of
"programmers' manual", that could describe how to use the lib for
various purposes: such manuals were available for various programming
tools in the past, and I have always been happy with those 2
complementary set of docs.
For the command line set, and general config/install of the tool I
suggest to do the same : - reference doc of each command and conf
file - advanced users' manual covering install/config/and usage for
various purposes.
For example : I am using the command line tools as a very basic pki
system to create certificate for my company. Those certs are
produced by openssl to be used by openssl based applications such as
stunnel or Apache: those usage are very common and should be
documented in an advanced users manual. Sometime those certs have to
be imported in client apps such as Mozilla Firefox or Thunderbird, or
M$ Ie and outllook : I think the wiki/adv users manual could be a
good repository for all this.
And of course, although openssl is for advanced users, I think some
pedagogic material on cryptography and its usage, and the benefit of
using openssl to fulfill those needs, could be very useful.
So you're suggest three major divisions: reference, programming, and
didactic. Also an interesting suggestion.
Well, in fact I am wondering about the best way to structure the
chapters of the wiki : depending on that, we can hope to have
something as clear and useful as possible, instead of being a bazaar
of various things.
I think that is the major part of the challenge: organization. On the
other hand useful material can always be organized later.
Personnally I can contribute to some command line tools usage case,
although I have to admit that I feel a little bit intimidated to
publish something on this prestigious wiki...
^^^^^^^^^^^^^^^^
Now that made me laugh :-)
You're already contributed something with your thoughtful comments,
don't stop now.
-Steve M.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List openssl-dev@openssl.org
Automated List Manager majord...@openssl.org
