[OpenAFS-Doc] submission of architecture documents

[Steven Jenkins]

On Tue, Mar 11, 2008 at 9:48 PM, Russ Allbery <rra@stanford.edu> wrote:
>
> "Steven Jenkins" <steven.jenkins@gmail.com> writes:
>
>  > 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
>  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.