[OpenAFS-Doc] submission of architecture documents

[Russ Allbery]

Jeffrey Altman <jaltman@secure-endpoints.com> writes:
> Russ Allbery wrote:

>> I think that basically makes sense.  Everything that's in the pdf
>> directory is also architecture documentation, too, so if we do this
>> going forward, we should probably just move the stuff in pdf into the
>> new arch directory.

> I disagree.  The PDF docs we have are protocol documentation not
> implementation architecture documentation.

Good point.  Never mind me.

We might want to move it to a protocol directory at some point instead of
naming the directory after the format, which I agree doesn't make a
tremendous amount of sense.

> More importantly there should be documentation that describes the
> DAFS. The state diagram is nice to have but it is not sufficient as
> architectural documentation.  The point of the documentation is so that
> someone who is not familiar with the work can get up to speed quickly.

> Personally I do not believe that we should accept any significant
> architectural redesigns of our code base without documentation of the
> implementation.  It doesn't have to be separate from the code.  In many
> ways it would be better if the documentation was actually submitted as
> part of the source modules.

Yeah, I agree with this principle.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>