[OpenAFS-Doc] submission of architecture documents

[Steven Jenkins]

There is an architecture documents for Demand Attach that I think
would be appropriate to place in, say, docs/arch (ie, instead of
classifying them by format, classify them by content). Specifically,
I've attached a diagram of the state machine for Demand Attach, in Dot
format.

Does it make sense to put this document in doc/arch? If not, what is
'the right' place?

Thanks,
Steven

[Russ Allbery]

There is an architecture documents for Demand Attach that I think would
be appropriate to place in, say, docs/arch (ie, instead of classifying
them by format, classify them by content). Specifically, I've attached
a diagram of the state machine for Demand Attach, in Dot format.
Does it make sense to put this document in doc/arch? If not, what is
'the right' place?

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.

Is there more Demand Attach architecture documents coming that should all
be committed together, or are you ready for this one to be committed as-is
now? It would probably be a good idea to have a README or something
explaining dot -Tsvg file.dot > file.svg for people who haven't used
graphviz before.

[Steven Jenkins]

Post by Russ Allbery

There is an architecture documents for Demand Attach that I think would
be appropriate to place in, say, docs/arch (ie, instead of classifying
them by format, classify them by content). Specifically, I've attached
a diagram of the state machine for Demand Attach, in Dot format.
Does it make sense to put this document in doc/arch? If not, what is
'the right' place?

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.
Is there more Demand Attach architecture documents coming that should all
be committed together, or are you ready for this one to be committed as-is
now?

There are some other man page updates that will be coming (Tom has
already made the drafts; I just need to review them before throwing
them over the wall to you). If you want me to save them all and put
them in one batch, I can certainly do that.

Also, I put some general notes up on the AFSLore wiki:
http://www.dementia.org/twiki/bin/view/AFSLore/DemandAttach, as there
didn't seem to be a better place for generic information (e.g., "what
is DAFS and why do I care? how does it work? etc). In that, I
mentioned Tom's presentation at the AFS workshop (which contains
further information). I'm open to suggestions as to how to better
organize/collect/disseminate this kind of information.

It would probably be a good idea to have a README or something

Post by Russ Allbery
explaining dot -Tsvg file.dot > file.svg for people who haven't used
graphviz before.
--

Good idea:

$ cat README

dafs-fsa.dot is a description of the finite-state machine for
volume states in the Demand Attach fileserver in Dot
(http://www.graphviz.org) format. An invocation like

dot -Tsvg dafs-fsa.dot > dafs-fsa.svg

will convert the description to SVG formatted file.

[Esther Filderman]

Post by Steven Jenkins
http://www.dementia.org/twiki/bin/view/AFSLore/DemandAttach, as there
didn't seem to be a better place for generic information (e.g., "what
is DAFS and why do I care? how does it work? etc). In that, I

actually that's something for the FAQ. I'll summarize and put
something there, with a link to the more detailed information.

[Steven Jenkins]

On Wed, Mar 12, 2008 at 10:13 AM, Steven Jenkins
<***@gmail.com> wrote:
...

Post by Steven Jenkins

Post by Russ Allbery
Is there more Demand Attach architecture documents coming that should all
be committed together, or are you ready for this one to be committed as-is
now?

There are some other man page updates that will be coming (Tom has
already made the drafts; I just need to review them before throwing
them over the wall to you). If you want me to save them all and put
them in one batch, I can certainly do that.

The batch is attached.

- README is be doc/arch/README
- salvageserver.pod is doc/man-pages/pod8/salvageserver.pod
- the bos_create.pod.diff just need to be applied against 1.5

This should wrap up the DAFS documentation.

Please let me know of any further changes that need to be made. Also,
if there are any omissions, let me know.

Thanks,
Steven

[Russ Allbery]

Post by Steven Jenkins
The batch is attached.
- README is be doc/arch/README
- salvageserver.pod is doc/man-pages/pod8/salvageserver.pod
- the bos_create.pod.diff just need to be applied against 1.5
This should wrap up the DAFS documentation.
Please let me know of any further changes that need to be made. Also,
if there are any omissions, let me know.

Thanks, applied.

[Jeffrey Altman]

Post by Russ Allbery

There is an architecture documents for Demand Attach that I think would
be appropriate to place in, say, docs/arch (ie, instead of classifying
them by format, classify them by content). Specifically, I've attached
a diagram of the state machine for Demand Attach, in Dot format.
Does it make sense to put this document in doc/arch? If not, what is
'the right' place?

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.

Part of the reason it is so hard for developers to come up to speed with
our code base is the significant lack of documentation of the
implementation.

Post by Russ Allbery
Is there more Demand Attach architecture documents coming that should all
be committed together, or are you ready for this one to be committed as-is
now? It would probably be a good idea to have a README or something
explaining dot -Tsvg file.dot > file.svg for people who haven't used
graphviz before.

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.

[Russ Allbery]

Post by Jeffrey Altman

Post by Russ Allbery
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.

Post by Jeffrey Altman
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.