[OpenAFS-Doc] submission of architecture documents
Russ Allbery
rra@stanford.edu
Fri, 14 Mar 2008 11:43:23 -0700
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/>