Lots of people are saying that we need more documentation, and I agree. And clearly it would be an investment-with-payoffs for Varien to work on that sooner rather than later, because of the way it empowers the wider community to climb the learning curve, help each other and become gradually less painfully-dependent on the team. But I know there are other high priorities too.
I’ve been pondering the situation, and I want to make a particular argument about the specifics of what might be done right now, even while the team’s time is in short supply.
We have roughly three groups of people:
1. The team who wrote Magento and invented its concepts and structures.
2. Experienced people with PHP/MySQL smarts, but new to Magento and relatively unfamiliar with it.
3. Not so experienced (though basically competent) - are mostly going to have to wait for other people to provide bugfixes and how-tos.
(Of course the line between 2 and 3 isn’t a solid one, there’s a continuum of skills - this is a simplification.)
There’s a bottleneck in the flow of information between (1) the busy busy team and (2) the experienced people. Once the info is out to group 2, it can easily propagate further: group 2 can help group 3.
At the moment, it seems to me we have a few adventurous people in group 2 trying to deduce concepts/structures “backwards” by looking at code and database structure. Meanwhile, the people who thought up the concepts in the first place are still alive and in the virtual “next door house”, but too busy to explain! How frustrating and inefficient is that?! I mean you might want to do it as some kind of intellectual puzzle if you had a lot of spare time, but not when the interesting game is a project and the project is stuck!
If only we could telepathically tune in to the designers and extract from their brains how they designed Magento and what all the bits are meant to do
Here is the argument/suggestion I want to make:
Writing good documentation is time-consuming and not easy.
But I feel sure that the team must have lists and whatnot which they’ve used themselves to keep track of what’s what. (Can it really be possible that no-one’s ever made a note of what the different database tables are for? Is that really all only in someone’s head? (and if so, what happens if they go off sick?))
I would like to argue for the team looking at what of their own “working” documentation might have any kind of potential usefulness to the people with the smarts, and putting it out “To be going on with”.
Don’t think “Oh but this is not well explained” or “We really need to turn this into a proper tutorial”. It doesn’t have to be elegant. It just has to contain some data which would mean something to a fellow programmer. You can put a disclaimer on the top “To be going on with - please feel free to improve”.
Sure, that’s not the ideal situation, but we don’t have the ideal situation. And I feel sure that at least some stucknesses are waiting on that kind of injection of data. I can’t help thinking that there are frustrated but keen people who would seize upon it - or at least parts of it - to make progress which is currently impossible.
Even if there are minor mistakes in it, or incompletions, some of those people would be picking up on some of the mistakes and correcting them and beginning to fill in the gaps. Again, status descriptions / disclaimers are your friend - “Not checked yet”, “Was correct as of v0.9 - [such-a-part] now slightly different, principles the same”, “Only describes x/2 of the x methods - more to follow”.
I’d welcome thoughts from the team on the feasibility of something like this “as a start” or “as an interim measure”.
and thoughts from the non-team programmers on their top requests for data, and any caveats about how it would have to work.
but feel free to comment if you just want to say “Yes I agree” too
Thanks for listening