please decrypt your manuals

[Peter Stuge]

Hi Doru,

Doru Georgescu wrote:
> > Really, to get the details of the SSH protocol, you should
> > look at the RFCs.
> 
> I believe that we can reach the conclusion that you consider the
> ssh manuals as a support for ssh developers, while I consider that
> the ssh manuals should be a support for the users of ssh.

You have been asking questions all over the map here.

For your questions about the use of OpenSSH I've mostly tried to
answer and point out how you might benefit from existing
documentation.

For your questions about very low-level aspects of the SSH protocol
I told you that you should not expect to find answers in OpenSSH
documentation, but that you should rather go to the canonical
specification for the SSH protocols, namely the RFCs.


> From your point of view, the ssh manuals should contain sketches of
> ideas that a ssh developer would need to remember,

Please don't put words in my mouth.


> while I expect a coherent and self sufficient (but not complete)
> functional description of ssh. As a user, I need to use it, so I
> expect to see its functions described in the manual.

ssh user at host allows you to log in as user on a host.

Since you need more detailed information you have to spend some time
with the documentation, and I would recommend doing so when your are
feeling focused, ready to analyze and eager to learn.

OpenSSH does many more things for many others than you and me, and it
tries to document everything. In some places the documentation is not
as good as the implementation, but I'm sure you also prefer that over
the opposite.

If the documentation does not explain something sufficiently well
then you can always experiment, or even read the source code, to
learn what the programs are actually doing. When you've done so,
please send patches for the documentation, maybe first to mailing
list for review, then into bugzilla.


> As a developer, you need to remember some name of a configuration
> option in the sshd_config file. 

There are several manual pages. Some document programs, other
document configuration options.


> It looks strange to see such an important application like ssh
> without a user's manual, but I understand that the developers are
> not motivated to write it, so this is an economical problem, not a
> technical one.

Maybe you already know how difficult it is to find excellent
technical writers.

And again - if I have to choose between a developer producing working
code and one producing documentation, I will always go for the code.

People can run *and* study code. Documentation is simply less
important.


> Thank you all for your support, which I fully appreciate, and it
> did help me very much.

Since I'm discussing with you in "spare" time you should be prepared
for very high jitter in the response times.


//Peter