call for doc requests

[mark]

Hey --

I realize that there's a lot of things that would be useful to disseminate. Stuff about the way the code works, some conventions, why things are the way they are, and more advanced topics like database handles and stuff like that. I'd love to get some requests -- see what people are really the most curious about, so I can prioritize writing the docs. But here are some things I've thought of:

* What is a database master, slave, when should I call "get_db_writer" versus "get_db_reader" and what is this "get_cluster_def_reader" thing anyway?

* What are database clusters, what is the global database, what goes where?

* What is TheSchwartz/Gearman, how do I use it, when should I?

* What should be stored in memcache, what are the best practices?

* ...

Crap, I had a bunch more when I was thinking about this before bed last night. Should have written them down then... oh well. Is there anything you are curious about that you think might make a good bit of documentation?

Comments

[denise]

Seconding ESN and how it works. It is great voodoo to me. (Well, much of this is great voodoo, but you know what I mean.)

Things that I am still incredibly fuzzy on:

* Object references -- the way I've been teaching myself has been by looking at surrounding code, but the places I've been working have been totally mixed-coding-style, so I still don't get it. (I know that a lot of this might have to do with me being a beginner, but we have a lot of beginners.)
* Speaking of coding style: what to do if a file you're working in is really old, style-wise. Do you match style, update the whole file, or just update the bit you're dealing with? I've seen all three answers given from time to time, and getting one answer in writing would be really good.

Seconding allen's mention of the standard libraries. If nothing else, a list of all the files in which libraries live and what kind of stuff goes in each file, so people can know exactly where to go to look over them. I've been bitten a few times by the fact that User.pm mixes two namespaces, for instance. (Long-term I'd like each function documented in-code. Bits and pieces of them are, but a lot of them aren't.)

Something about how the user capability/account type system works, and how people can make their functions/features/etc aware of multiple levels of ability (ie, how they can make things paid-user-only or have higher limits for paid users).