On Dec 15, 2007 5:46 PM, Allison Randal <[EMAIL PROTECTED]> wrote: > 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.
ok, seems to be a good 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. I think this is a good idea. We shouldn't overdo it, by creating a dir. if there's only 1 file to be put in (sure, if this would happen once that'd be fine, but there are several files like that); I think it's best to also have 'general' implementation notes directory that contains these singular files, and if the documentation on a certain subsystem gets bigger, move it into a separate subdir. > > It looks like docs/dev/wranglers.pod should be moved to > docs/project/ticket_wrangler_guide.pod. good idea. done. > > 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 Some files seem to be superfluous; docs/ops/*.pod contain pod files describing all ops. The exact same info (as far as i checked) can be retrieved by running perldoc src\ops\*.ops. Is it necessary to keep these pod files? It's a bad thing to have duplicate stuff, especially to maintain. I can see the advantage of having documentation in a docs/ subdir instead of users having to search in the src/ directory, but it'd be better to generate the .pod files from the source, imho. (does parrot have a "make docs" target?) The same is true for docs/pmc2c.pod; I think this file contains slightly more info than tools/build/pmc2c.pl; maybe it's an idea to put the docs into the source file, and have the .pod file generated? (it also seems arbitrary that pmc2c.pl has a separate .pod file, while the other tools don't, such as ops2c.pl and such). kjs
