The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Making frameworks easy to learn

I work for a company that makes a lot of similar web sites. We started out with what you might call the "naive" web app approach, where each page has an HTML template and a script to populate it (in our case, PHP). There were some shared function libraries, but pretty much everything that happens on a page, happens in the script.

It was very easy for new developers to get started on that system, but as you can imagine, the code quickly became unmanageable. We would do the same thing 20 different ways, and it was impossible to make any useful changes without breaking something.

Since then, we've written our own application framework which does things in a much more organized fashion (think Struts, but less rigid and with more features). I think it's pretty well-designed, and once people learn it, they usually like it.

The problem is, it's difficult for new hires to learn. Well-named functions and classes only go so far, when you don't even know which classes to use when. So I'm wondering: does anyone have any advice for making a complex framework easy to learn?
Thursday, August 03, 2006
Have you considered documenting it? I'd recommend a intranet wiki in particular for doing so.
Art Wilkins
Thursday, August 03, 2006
Also, if you don't have one, this would be the perfect excuse to hire a good technical writer to come in and start documenting your code libraries, coming up with examples and tutorials, and even acting as code librarian. A lot less salary than an engineer  and if you're lucky prettier as well.
Art Wilkins
Thursday, August 03, 2006
"prettier as well"

Art! You pig!
Mike S Send private email
Thursday, August 03, 2006
A cook book on a wiki is a good way. Break down the common tasks programmers have to do and provide short deployable examples to illustrate the point.

Back that up with a complete example where someone can see all the parts work together.

All code should be product ready, don't say this is just an example so I'll write crap. Expect and encourage people to copy and paste.

Back all that up with a training class where you go through everything. Put the class online so people can watch it more than once.

Back all that up with an email list and designated go to buddy for problems.

Always have an accepting attitude of people who don't get it.

Use every question from a newbie as opportunity to improve both your documentation and you framework.
son of parnas
Thursday, August 03, 2006
I think the easiest way is to create a nice big poster that shows how all of the pieces fit together. Speaking from experience, the hard part of learning a framework is that you have to configure this piece over here, this piece over there and that piece yet over in that corner, just to get a basic "hello world" page up. Yet, most books focus on one piece at a time.
Thursday, August 03, 2006
Give the new developers access to a copy of the live system and give them 'exercises' - add new functionality, maintain what is already there. In my experience (three years as a contract IT trainer) people need to play with technology to understand it. Not having to worry about breaking the live system is good for morale.

+10 for documentation in a wiki.

I also recommend regular bathing, epsom salts and a trip to the country for picnics twice a year. Make sure your new hires are house trained or else they may chew the furniture.

Rock on.
A massive blob wobbling in hyperspace
Friday, August 04, 2006
Thanks for the suggestions. I like the big poster idea - I might try that. We did hire someone to write documentation, and she's lovely, but she doesn't really write documentation anymore, and none of the developers would have had time to work on it with her anyway. I also set up a wiki, so hopefully I can encourage people to use it.
Friday, August 04, 2006

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz