On Dec 16, 2007 1:02 PM, Klaas-Jan Stol <[EMAIL PROTECTED]> wrote: > > > 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 > > woops, I was sleeping while I wrote this stuff below; the docs/ops/*.pod __is__ generated from src/ops. Never mind my rant :-)
> > 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?) >
