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

[exor674]

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

I've seen this (and tried to help) multiple times, so for what I've sen this might be the most popular, however.

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

seems to interest me.

[adalger]

Style system!

[animone]

I'd like to see a good document outlining the data flow through the entire DW system. Anything from what different sections of the DW code handle, to when/how a chunk of data is shipped off between servers/clusters. I can certainly see a use for this in the future, especially when designing and implementing new large features, as well as scaling decisions.

[janinedog]

Maybe process vs. request cache and when to use each?

[allen]

Thirding the caching system.

I'd really like to see some of the standard libraries documented. Simple things like Storable and LJ::eurl() and such that a lot of people are likely to want to use, but might not know about if the bit of code they're editing doesn't use them already.

Some other potential topics:

JavaScript and the AJAX system

An overview of the Entry/Comment data model and API

The Event/Notification system

[liv]

Documenting the styles system is kind of separate. The styles people are working on it, we know it urgently needs doing... Have a poke around the Wiki, there are pages there like http://wiki.dwscoalition.org/notes/S2_functions and http://wiki.dwscoalition.org/wiki/index.php?title=Category:S2_Properties which represent early stages in the genesis of styles documentation.

[kareila]

+1

[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).

[pauamma]

Apache::LiveJournal *whimper* *cringe*