Klaas-Jan Stol wrote:
First of all, I certainly agree with this POV (even though I myself tend to
put in details in stuff that i update, for instance PDD19. The thing is, I
don't have a better solution where to store these details. I could leave
them out, but then the info is lost except for people who knew this stuff
already. Newcomers are certainly not included.).
As an example, I'd say PDD 19 should have the level of detail needed to
create an implementation of PIR, but shouldn't outline all the guts of
the internals of IMCC. (Especially since that level of detail would be
entirely irrelevant to PIRC, and the PGE-based PIR parser.) It's not a
hard rule, just a general guideline.
Indeed, docs/dev/ contains several documents about implementation details.
However, docs/dev doesn't seem to be much structured yet.
Agreed, it's a mess. The top-level docs directory is also a mess. At
least docs/project is sane.
Moreover, docs/
also contains docs with impl. details. (should the go into docs/dev/?)
Yes. Or be merged into the relevant PDD and deleted.
Of course, it is a good thing to have docs at all, but IMHO, it would be a
good thing to have more clarity or a standard way for organizing this, just
as PDDs are organized well.
Three cheers!
I merely want to mention this and see how
other people feel about this, and maybe trigger some discussion on how to
manage documentation properly.
Some thoughts:
We might create a series of subdirectories in docs/dev that correspond
to each subsystem. Something like docs/dev/gc, docs/dev/oo,
docs/dev/imcc, docs/dev/config, docs/dev/build, docs/dev/install, etc.
Then a README file in docs/dev explaining what people will find in each
subdir.
It looks like docs/dev/wranglers.pod should be moved to
docs/project/ticket_wrangler_guide.pod.
Also, we need a check for what's implemented. It looks like
docs/dev/fhs.pod is a proposal for making Parrot's install directories
compatible with a standard directory structure, but I suspect it was
never reviewed, approved, or implemented.
Allison
