please decrypt your manuals

[Peter Stuge]

Doru Georgescu wrote:
> Precisely because ssh is the work of a community, it is largely
> meaningless for me to write a manual alone, without tight
> cooperation with that community. The manual should transmit
> information from developers to users.

I disagree. I don't think this is the only way to produce a good
manual. Users can, and should, educate themselves, and then they
can write documentation with insight.

Not all users are good writers, but maybe one user here and there
(you!) is a good enough writer to feel strongly about the issue,
and make a contribution.


> For this to happen, a language (symbols, terminology, structure,
> logical implication rules) should be developed. The very idea that
> I can do this alone, outside the developers' community, is absurd.

So there is a bootstrapping problem. You mean that you need to know
more about SSH and OpenSSH before you can work on improving the
documentation for OpenSSH - and you can't learn enough from the
existing documentation.

I disagree again - you can always work on *parts* of the
documentation. And if you really want to bridge developers and users
then you need to drill down into particular points, to really learn
the high level aspects of the concept (but not all the details in the
code) - so as to distill it into user digestable format.

This is not trivial. Again, there aren't many really great technical
writers. :\


> Of course such a manual would be rejected, because it would not
> make any sense to the developers.

Oh I don't know. I think there are many opportunities for you to
publish material about OpenSSH. Even if your contribution does not
end up in a man page, maybe it will be hosted on a web server
somewhere as a tutorial.


> Plus, I completely lack the resources for such a work.

Aha. But you request resources of others to do it.

As you already pointed out - others also lack resources.


//Peter