Category: Technology

This will be the first in a series* of articles on web applications development – not the specifics about programming, but more tips on the infrastructure and processes that can make life easier, more productive, successful and better aligned with best practises. Its based on my experiences of being in development teams and leading development teams.

I see these articles as being useful to a development team thats growing from a 1 or 2 man operation to a larger team and is perhaps using Open Source development tools such as PHP/PERL/Python and perhaps aren’t in a very processes driven environment…

Documentation

Most developers won’t generally document their work as a matter of course – either they simply forget, overlook it or its just not that exciting for them. So 3 things:

• Illustrate the value of documentation
• Build it into the development process
• Make it exciting (oh okay you can never make documentation that exciting – so lets settle for a bit more interesting!)

Illustrating the value – most developers are already sold on documentation being a generally good idea but others aren’t. Some fear that by documenting they loose control over the project or the work that they primarily work on (in fact the reality is that is the opposite…) or they just really don’t see the point. Highlight the facts that it enables team work, improves quality, makes support and changes easier etc. Also that holding all the knowledge up in your head means that you are stuck in your current role as its not easy to bring others in to do what you do so you can be promoted.

Another great benefit is inducting new team members – it allows you to point new team members at the wiki site to help them get up to speed quickly – and you can also use that process to fill in any gaps in the documentation (and get the new start to include their tips and findings as they learn the ropes…

Build it into the development process – obviously you need to have a development process if you haven’t got one but once you have it just becomes part of the steps:

• Requirements Gathering – document
• Spec/design – document
• Build/development – document

So ensure that documents are required for each step in the process – and make time for that documention. The nice thing is that documentation is a lot easier if done throughout the project life cycle rather than all at the end (then it is just really daunting) – as generally what you plan to do is what gets delivered (and if things deviate from the spec during development you can just adjust it)…

Make it more interesting – its more that just that in reality as its picking a documentation tool that supports the above points and works for the team. For me development documentation seems to works well with an internal/Intranet Wiki (something like MediaWiki for example). The main benefits (over office docs for example) it allows easy collaboration, allows for a geographically disbursed team and is generally nicer than using word processing software. It’s made more interesting by feeling very “Web 2.0” (as much as I hate the phrase!) and has some great tracking features – like the recently edited articles page. Once the team have seen the advantages and you bore you colleagues to death with “the W word” then you’ll find that you have a healthy wiki site and documentation, documentation, documentation (with any luck with minimal pain!)

Categorising the Wiki – here are some ideas on some categories that work:

• Projects – Pages under here relate to discrete projects the team is working on
• Infrastructure – documentation on the dev, staging and production server environments (eg Server configs, IP addresses, SLA details)
• Process – Reference guide to the development and other IT processes so the team can refer to them and also make contributions and feedback on what is working.
• Meeting Notes – Agendas and minutes for meetings – if you get this right then these allow for team communications when needed (rather than at forced meeting dates) and are links to other pages on the Wiki where the full details of a proposal or a project is available.

Blogging

Another option (which has some other positive side effects including marketing) is blogging about development projects – and this is something I am considering for my current team. The Wiki will be for the more technical and internal documentation aspects and the blog for what the project actually does. The added benefit of the blog is that it can do some link / SEO stuff for your projects and raise the profile of the development work that your team is doing to a wider audience. This is particularly useful if you develop an Intranet system for your company – where you are adding new features or enhancements over time.

To make MediaWiki easier to use (for those who aren’t familar with the syntax used on Wikipedia) we enabled a WYSIWYG editor – FCKEditor. There is a whole range of great Wiki software out there if you don’t like the look of MediaWiki – just do a Google or have a look at wikimatrix.

The next articles will more than likely be about:

• Project Management tools (eg FogBugz) –
• Development Meetings and Communication
• Using a Framework (eg Zend Framework)

… watch this space!

*I don’t know how many there will be yet but if they are received well then heck there might be as many as 3 or 4!