I really like the one-time-setup-howtos/regularly-occurring-howtos dichotomy.
That said, your list looks very how-to centric. How-tos are awesome, but the very first thing I want to know when I start working on something is an orientation to how its organized and why, and a glossary of in-house jargon (e.g. "in dw/lj-ese a 'post' is called an 'entry'"). I love things like ER diagrams, layer schematics, and class inheritance illustrations, for quickly getting oriented to how things are organized. I want references and explanations, not processes to follow. Right now pretty much all of Dev Getting Started is "Do this, then this other thing", which I find not very helpful.
I find documentation organized in parallel with the structure of the actual code (e.g. "here's a list of directories and what they all hold") to be marvelously useful when I'm staring at the code puzzling, "What does this do?". But they're much less useful if I'm trying to figure out where in the code to find something I already know about from the user interface, and don't know where to start looking, which is a more common case for me.
A thingy which if you don't have it might be a powerful addition is a discussion of/reference to what I'll call the Core User Inspectable Assets, which for dw would be things like "Journals" and "Users" and "Posts/Entries" and "Communities" -- the kind of entities which end users experience of the application. The discussion of "Journals" would explain how journals are represented in the db, how they relate to other CUIAs such as Users (which is interestingly close to identity in dw, but not quite -- and useful to disambiguate for developers coming in from some other world like WP where there is a strict division of Blog from User), what resources do what as part of instantiating the "Journal" asset to users. Yes, this would be a pretty big document, and massively crosslinked to other stuff. And it would be seriously redundant to parts of "Users" and "Entries" and "Communities" -- and that's okay. The point is to present an asset-centered view of the project so someone coming in saying, "I want to do something to 'journals'," can get a journals-centered view of the code for rapid orientation. It's a way of meeting the developer where they are.
Another way of putting it is that documenting the Core User Inspectable Assets is documenting a slightly higher abstraction layer, the systems the code and db objects are organized into. This middle abstraction layer is actually how we mostly think about code, both what is most useful to learn and what is least often documented.
![[site community profile]](https://www.dreamwidth.org/img/comm_staff.png){kind=small}
(no subject)
Date: 2013-01-11 10:09 pm (UTC)That said, your list looks very how-to centric. How-tos are awesome, but the very first thing I want to know when I start working on something is an orientation to how its organized and why, and a glossary of in-house jargon (e.g. "in dw/lj-ese a 'post' is called an 'entry'"). I love things like ER diagrams, layer schematics, and class inheritance illustrations, for quickly getting oriented to how things are organized. I want references and explanations, not processes to follow. Right now pretty much all of Dev Getting Started is "Do this, then this other thing", which I find not very helpful.
I find documentation organized in parallel with the structure of the actual code (e.g. "here's a list of directories and what they all hold") to be marvelously useful when I'm staring at the code puzzling, "What does this do?". But they're much less useful if I'm trying to figure out where in the code to find something I already know about from the user interface, and don't know where to start looking, which is a more common case for me.
A thingy which if you don't have it might be a powerful addition is a discussion of/reference to what I'll call the Core User Inspectable Assets, which for dw would be things like "Journals" and "Users" and "Posts/Entries" and "Communities" -- the kind of entities which end users experience of the application. The discussion of "Journals" would explain how journals are represented in the db, how they relate to other CUIAs such as Users (which is interestingly close to identity in dw, but not quite -- and useful to disambiguate for developers coming in from some other world like WP where there is a strict division of Blog from User), what resources do what as part of instantiating the "Journal" asset to users. Yes, this would be a pretty big document, and massively crosslinked to other stuff. And it would be seriously redundant to parts of "Users" and "Entries" and "Communities" -- and that's okay. The point is to present an asset-centered view of the project so someone coming in saying, "I want to do something to 'journals'," can get a journals-centered view of the code for rapid orientation. It's a way of meeting the developer where they are.
Another way of putting it is that documenting the Core User Inspectable Assets is documenting a slightly higher abstraction layer, the systems the code and db objects are organized into. This middle abstraction layer is actually how we mostly think about code, both what is most useful to learn and what is least often documented.