> That's exactly my question - why aren't they? Why should documentation
> be so much decoupled from the code itself? It has a much better chance
> of being better maintained if it is kept in the source tree.
I think it's a fair question, but if we head in that direction, I'd rather
see it done as part of an established policy change rather than on a
project-by-project basis. (PSARC is loaded with documents that are quite
useful in understanding the source. How many repositories of such things
do we want?)
On a related note, one thing that I find deeply frustrating about the
current PSARC[1] design document approach is that once-cohesive designs
suffer "death by a thousand fasttracks". That is, to understand the
design of a particular subsystem, one must often read the original design
document and then mentally apply the diffs to that design from the N
fasttracks that followed. (Not to mention that what got approved by PSARC
may include things that were never actually implemented.) Doing that
mental diff is quite tedious and error-prone, and may lead to important
design considerations being overlooked.
It would be nice to solve both of these problems. For instance, if a
given subsystem had current design/architectural documentation in the
source tree, then a PSARC fasttrack might consist of providing the
proposed updated design document (e.g., with changebars or the like to
call attention to the new content) and a short description of the changes
and their rationale.
Also, a practical concern: if we did put such documents into the source
tree, what format would be appropriate? Some requirements:
* Needs to be easily editable.
* Needs to be reasonably compact. (To ease remote development)
* Needs to have a reasonable facility for drawing diagrams.
[1] It's unfair of me to classify this as strictly a PSARC issue -- it's
really an issue with our current process.
--
meem
_______________________________________________
opensolaris-code mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
