Posting in the Magento forums has been disabled pending the implementation of a new and improved forum solution which should better serve the community.

For new questions please post at magento.stackexchange.com, the community-run support site for the Magento community. We will be providing updates on the new forum solution soon. For questions or concerns please email community@magento.com.

Magento Forum

Suggestion for a next move on documentation
 
Jennifer M
Jr. Member
 
Total Posts:  21
Joined:  2008-02-18
 

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.

==

Analysis first. 

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 grin

==

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 grin

Thanks for listening

Jennifer

 
Magento Community Magento Community
Magento Community
Magento Community
 
ODB
Sr. Member
 
Avatar
Total Posts:  142
Joined:  2008-02-06
London
 

That was good. Really good.

I totally agree. There’s a chasm between the programmers and the developers on the forums. Re: the elegance and ‘incompleteness’ of it all - I think everyone should make a big push to update and organise the Wiki. It’s a mess!

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jennifer M
Jr. Member
 
Total Posts:  21
Joined:  2008-02-18
 

Thanks :-)

Actually, by way of update/revision to my earlier post, there is more on the wiki already than I’d realised before.  I just went poking around to see what you meant, and found some documentation of the database structure there.  Don’t know why my previous searches of the site didn’t turn that up - I did search, but maybe I just didn’t persevere far enough down the results. 

Seeing that diagram hasn’t actually enabled me to solve my problem yet (think I’d need to understand EAV first, and I’m definitely in the aforementioned “group 3” on that at the moment :-) ), but it did give me a little bit more sense of the architecture. 

so yes I agree, definitely worth sorting out the wiki some more. 

I wonder what else is on there which most people haven’t discovered yet…

 
Magento Community Magento Community
Magento Community
Magento Community
 
ODB
Sr. Member
 
Avatar
Total Posts:  142
Joined:  2008-02-06
London
 

Adi is looking into sorting out some problems with the wiki.

I’m game for trying to straighten it all out but it’ll have to wait until they’ve sorted it out.

 
Magento Community Magento Community
Magento Community
Magento Community
 
Jennifer M
Jr. Member
 
Total Posts:  21
Joined:  2008-02-18
 

Pondering this some more…

I should probably add for clarification that this wouldn’t be a substitute for the team also roaming round the forums and answering at least the difficult questions there - the ones where a thread develops “Me too - I don’t know either”, and any that are still un-responded to after a few days.  And solving the bugs.

 
Magento Community Magento Community
Magento Community
Magento Community
Magento Community
Magento Community
Back to top