I realize this documentation[1] is still in progress; yet, here are some comments, posted to the list to maybe encourage some kind of debate (since it's likely that there will be several consumers of this package in repoze.* in the future:
I find the introduction lacking; why do I care about indirection, what's the benefit. Next, I can't read through the documentation if it's going to be all "a" and "somecomponent"; can we have some kind of context, e.g. a story-line or some likely scenario. This would help a lot in motivating the package in the first place, too. <snip> Instead, components (such as “adapters” and “utilities”) are registered using marker “component types” </snip> This is a cool feature and it should probably be mentioned upfront (e.g. not in the last section of the documentation); because afterall, you can program more strictly by adapting to marker-objects. \malthe [1] http://docs.repoze.org/plugin/ _______________________________________________ Repoze-dev mailing list Repoze-dev@lists.repoze.org http://lists.repoze.org/listinfo/repoze-dev
