listo factor listofactor at mail.ru
Fri Mar 25 21:50:25 CET 2016

On 03/22/2016 09:21 PM, Peter Lebbing wrote:

> ... writing good documentation is hard, very hard. In
> fact, it turned out to be easier to write academical papers on why it is so
> difficult to make crypto easy to use than to write documentation that makes
> crypto easy to use.

It ~is~ hard, but only when the documentation is written ~after~
the software has been built, based on the functionality definitions
derived from the program itself; instead of being based on a-priory
functionality specifications, that both the program and the
documentation must equally conform to.

But even when that is the case, the documentation is hard to
understand for the user if there is no separate "Concepts and
Facilities" document, one that does not address or even mention
any interface or procedure detail, and unless the user understands
that a firm grasp  of its content is an absolute requirement before
he or she can get to the interface and procedures documentation
(i.e., the "User Manual").

To perform tasks that GPG is designed to accomplish in a safe manner
is *very, very hard*, and even the best documentation could not change 
that fact. The efforts which concentrate on making it easy might
indeed increase the number of people that use it, but at the expense
of their safety. That, to me, appears to be behind a lot of projects
similar to the one discussed here.

More information about the Gnupg-users mailing list