As I’ve announced here, we’ve recently taken the difficult decision to put development of Citrus in hold, indefinitely (let’s be realistic, probably forever). I’m now wondering what if anything we should announce about our new project.

Is openness a strength or a weakness? Is there value to the community in publicly documenting our design decisions, and how we’ve come to them? Is it something our competitors could and would use against us? Is there anyway to mitigate the effects?

I like what Jeff Atwood and Joel Spolsky have done with their series of podcasts on the Stack Overflow blog where they’ve released their design meetings as a series of podcasts and given us all an insight into how they’ve come to some of the decisions they’ve taken. But let’s face it I’m neither Jeff or Joel and I don’t get anywhere near their traffic. So the first obvious question I’m asking myself is if it’s even worth the effort of writing posts, let alone recording and releasing podcasts.

Next is the question about maintaining a competitive advantage, given the fact that our team is so small, just the two of us at the moment; I’m only working about half time on the project and Simon, who isn’t a coder is working even less. So giving someone a guide to competing with us could be downright foolish. Then again, nobody is really listening are they? So does it even matter?

The other question, which I think is equally important as the project grows - hopefully into a product is what if any level of openness is appropriate post launch? Will an open discussion of ongoing design decisions as they’re being taken before, or even as they’re released be of any benefit to the community? Communities can be some of the biggest supporters and can be some of your most passionate users - sometimes these passions can work both ways? What level of support ongoing will a public discussion of the decisions you’re taking, before users have all the prototyped interfaces to play with, be required? Is there an ongoing effort you’ll need to make to maintain the level of trust and confidence of the community?

I think I’ve talked myself out of a podcast of our internal discussions, for now - but I’m still keen to use community interaction to help us develop a product that meets the needs of the people who are interested in using it and to drum up support and interest in the project. I’ll no doubt return to this topic in the coming weeks as I develop a clearer idea of how I think we should accomplish that.

If any of the few of you out there listening have any questions or comments, please let me know your thoughts.

Related articles by Zemanta

• Does Good Tech Need PR?
• stackoverflow.com
• PR-less launch kicks off a stack overflow of praise

Don’t write spec documents, throw away any you have near you, they’re next to useless anyway. It might seem like a hearsay to some but it’s true and deep down even the most most anal planner in all of us knows it. Two of the biggest reasons for this are:

• size and scope: In order to address every aspect of your project a full specification document has to, well address every aspect of your project and it’s going to be huge as a result.
• lack of vision: For most people relating what’s written on paper to a vision of a design in their heads is difficult if not impossible.

Loose documents don’t work well either, because leaving the obvious unsaid just leads to problems, chiefly not everything is obvious to everyone. The devil is in the details and avoiding them until the end of a project is just going to cause trouble.

“Why haven’t we implemented x, that should have been obvious!”

create the interfaces

Prototype the interfaces and use them as your spec. Working this way has so many benefits, try it once and I promise you’ll be converted. Before you write a single line of backend code, sit down and work out your interfaces. Build each screen, put all the buttons, fields and elements on the page

I normally start with index cards and write a few simple requirements for each screen or page - just a few simple sentences listing what the page is expected to achieve.

My next step is to turn those requirements into interfaces.

in HTML, not photoshop

Photoshop is great, but let’s face it it’s no better for trying to work out a functional interface prototype than some paper and a pencil. It’s very easy to focus on making things look pretty over making them functional and you risk missing something important out.

The best way to avoid both of these traps is to write your interfaces in HTML, mark them up semantically as they will be marked up in the release and use them as your working spec.

I know good design but I’m no designer

Another benefit of coding up your interfaces in HTML before you start writing code is you can hand them off to designers so they can make them look pretty as you’re working on making them work. I have a pretty basic idea of design principals and the tools - but I find it hard work. So with interface first development I don’t have to think about it.

let the testing begin

Another thing which is made infinitely easier with interface first development is functional testing, because your testers don’t have to wait for a release before they can start developing a test suite. You are using an automated test suite aren’t you? By generating interfaces as developers add functionality testers can already have been through the interfaces and written a whole series of failing tests.

updating later

The great thing about using HTML as your design and communication tool is that when it comes to making a change to a page you have the most up to date working copy there ready to modify in the form of your site. Just save the page, add the change to the HTML and you’ve got your interfaces ready for discussion and later implementation. What could be easier, faster or more clear for everyone?

it’s not a panacea

There have been times when I’ve been working with notoriously difficult individuals where nothing was going to satisfy. An exmaple that springs to mind is a multi month project where we produced an interface design early in the project. The design was a set of PDF images not HTML (see above), but the delivered product was a pixel perfect implementation of it. Only once the project was delivered was there any input on the design or functioning of the project - I’m not just talking things that a PDF can’t show you like what clicking a link looks like. I’m taking basic things like colours, layout and the size of elements!

Would a HTML mock up have made any difference, I actually doubt it. I take blame for miscommunication and resulting mistakes when it’s my fault but in this case even after the site was fully developed and deployed to a staging area for testing none of these issues were highlighted. It was only after the site was put into production that these “critical issues” were discovered.

After reading this post what Jamie said hit me as well:

This is when I realized how trained I was in the processes at my former workplaces. This email would have been delayed until it was perfect[...] After fixing this there would be another thing and then another thing. A 2-day project would drag on for a week of redesign, approval, and development[...] It’s one thing to read Getting Real [...] It’s another thing to actually practice the principles. [...] That part is trickier than you think.

I don’t think it’s just Jamie and I don’t think it’s just his former workplaces. We’re all trained to make excuses not to launch, it’s endemic in the culture of most organisations. We endlessly pay lip service to the principals of release early and release often, agreeing in principal
with the principals - but put very little of them into practice.

A manager’s role is to facilitate an organisation’s march towards better - all too often it’s a weak manager that needs constant input on projects and at the root it’s fear of inadequacy on their part that builds a culture of ass covering. It’s obvious that at 37 Signals they don’t suffer from being crippled organisationally when executive decisions need to be made but executives are absent. Their staff are trusted to make decisions and they’re empowered to release better features.

When your last change was ready to deploy, when it was better than what was there, did you release it? If not, how long did it take you to get from that point to actually releasing it and how many people had to give final approval?

Why not empower your staff with a simple test - Is it better than what we have? No flow charts, no organisational hierarchy; just a simple question.

I’ve read the excellent Getting Real by 37 signals online and haven’t been disappointed by their Defensive Design for the Web. In the real world things go wrong and you can’t prevent every error, but you can handle them properly. It’s not just a book for coders or webdesginers either, I’d recommend it to anyone making decisions about site design, layout or functionality. The book covers topics from usability to copy writing using easy to follow, real world examples of websites getting it right, and other getting it wrong.

Defensive Design for the Web from amazon.com
Defensive Design for the Web from amazon.co.uk

Coders, desginers even your support staff actually want to take pride in their work, the want to do a good job. As a manager you’re meant to make that easier, but what if you don’t want to - how would you go about breaking someone’s will and what would a completely demoralised staff member look like, want to find out?

Start by micromanaging them

Assume from the start that they’re incompetent, they won’t get it right and make absolutely sure they’re told every task they need to do. Make sure you tell your staff in minute detail how you want it to look, how big you want it, what colour and how they should discuss it with customers - because let’s face it, the fuckers aren’t capable of figuring it out themselves.

Free will is alright in religion, but not in this workplace!

Make sure you’re ever vigilant and make sure you’re giving each member of staff a list of things they need to do. Of course there are things that will crop up and they’ll need to address those as well, but don’t allow it to impact your lists - you are the boss and your will, will be done.

The key to true micromanagement lies in the process, or more to the point in creating a process. When something slips through, there is a failure or anything breaks down it’s because of a procedural failure, the only solution is to fix the procedure, with a new one. Creating a new process allows you to have complete control without requiring you to interact on a case by case basis; though that is highly recommended, because as we made clear earlier - the fuckers just aren’t capable on their own.

For the advanced, micromanaging further can be a worthwhile challenge; take a task you’ve assigned and make sure you’re staff are aware of each step that you need them to complete. Basically micromanage your micromanaging! Tell them what to do and how you want them to do it, tell them in detail and make sure they know you’re doing this because it wasn’t done right last time and we just can’t afford any more mistakes.

Documentation is key

We all know that documentation is important, but only a gifted few are able to take it to the next level. If you’re in charge of anyone for the love of god, cover your ass. As in the wild if you’re the alpha male (or female) you need to defend that position, show any weakness and someone will certainly try to unseat you - make them document their worth, then use it against them!

As you micromanage processes and create new ones you’re handed a golden opportunity for documentation, new spreadsheets, new flow charts and new forms to fill in!

Make it pointless

It’s not meant to be about something that is easy for the staff - this is about you. Make sure the documentation is unweildly at the very lest - shooting for downright maddeningly pointless is of course the ultimate goal if you want to truly demoralise people.

Timesheets are a great starting place. But they should never list time on task - they lying bastards always just add them up to make a full week work, even when you know they’re bunking off. Make they list the time they started, then the time they finished a task and make them do it in a separate document for each task. Another great place is a call logs and error reports - make them document it all!

Make it feel like they’re justifying themselves

Make sure that when someone is filling out documentation, especially things like timesheets, they’re aware the true intention of the activity is to justify themselves. Make sure you say, and repeat, things “They’re kept on file for management review, internal accounting and cost/benefit analysis”. That’ll keep ‘em on their toes.

Make them justify themselves

Use the documentation in meetings - they knew you were going to even if you said you wouldn’t. Haul them out during a performance interview and you’ll have everything you need to keep costs down.

Advanced documentation

• Make sure it’s on paper, as we can’t trust these computers
• Even better, mandate they fill in a spreadsheet, print it and then file it
• Even better, mandate a more detailed format, update a communal spreadsheet (stored on a shared drive and only accessible by a single user at a time), print it, then file it.

That was fun, where to from here?

Now that you’ve moved away from the traditionally held position that lower level tasks should be delegated down the chain of command so you can focus on the higher level tasks, start complaining that your staff are useless. Tell them that they can’t seem to accomplish anything without you hand holding them. Put pressure on them, make them sure that THEY are holding up business development.

Hire them a new boss

You need help, your staff are useless so create a new tier of management. Hire someone from outside to help you better manage your staff. Even better, bring someone from a different division into the team and put them above the team members.

The above is satire, I wouldn’t actually suggest you do any of that if you want to have a happy productive workplace. To a greater or lesser degree I or people I know have been guilty of some of them but it isn’t based on any real concrete experience.

Too many times I’ve seen businesses slam the wheel hard to the left and change course chasing money. You know the drill, if only our product could do something else we’d sell so much more. Or worse a customer or potential customer suggests a feature that would clinch the deal.

Let’s face it just because one person wants it doesn’t mean you’re on to a winner, success just isn’t that easy - someone won’t just walk in the door and give you all the answers. The hard reality is that talk is cheap and it’s easy for someone to say they would certainly buy something if only it did something else as well, it’s quite another for them to actually drop their current system to replace it with yours when the feature happens.

Focus

Focus on what is important, delivering a product that long term meets your vision and accomplishes the goals of your users.

You know your market, focus and stick to that

You should be, as 37 signals put it, hiring the right customers, figure out your core target market and target them. A common fault I see with businesses that end up in a position where they’re chasing cash is generally that they’ve refused to figure out a core market, and refused to focus on it.

They argue that by adopting too narrow a focus they’re cutting themselves out of a potentially lucrative market. It may sound like a compelling argument, unfortunately most of the time, it leads to spreading yourself too thin, or not being agile or focused enough to truly serve any of your “target” markets.

Find a core market, where you can make a difference and focus exclusively on that market.

Branch your product from a strong trunk of core users, just like a tree if you branch too early the trunk won’t be able to support the weight.

You have a vision for your product, focus and stick to that

It’s very tempting to listen to every feature request from every passionate user and fall in love with it. That’s why a vision is important, knowing what it is your product is meant to accomplish helps immensely as a filter for “good ideas”.

An example of a product vision is goroam’s citrus. Our vision is simple “estate agent tools that don’t suck” and the filter for new features is a simple set of questions

• will it help sell more properties?
• does it give users valuable information?
• does it save users time?

If a feature doesn’t have a compelling answer to any of these questions, it’s a non starter. Most importantly though the answer has to affect most of our customers. We’re not in the business of worring about edge cases or selling features.

Adopt a pragmatic approach to feature requests

And by pragmatic, I mean ruthless. Make absolutely sure it focuses on your market, your vision and affects most of your customers. Don’t keep feature lists, the good ideas will come back again and again the bad will just languish there anyway. Have a roadmap, but execute it quickly and only look as far as the next release. Don’t be rude, be positive about good ideas but make no promises.

Your product has a vision, a roadmap and you’re in control of it. You’ve worked hard to build a niche and now you’re faced with the dilema that faces too many small companies: Company X wants your product to do something else - but unlike the other tire kickers, they’re willing to pay for it.

Here there be dragons!

Bootstrapping is hard work, and sometimes you’ll have to do other work to pay the bills but resist the urge to allow customers to pay for features in your product. It makes a very subtle change in the relationship, suddenly the feature is now your customers and they’re paying for it, so they’re dictating how it should work; not just today, but tomorrow as well.

the devil is in the details

Even if you’re in the rare situation that the next big feature on your list to implement is the feature you’re being paid to build, beware. While you might agree on the feature in principle, you might not see eye to eye on the implementation details. They will more than likely want things to match their internal processes. Which isn’t likely to match that of your other customers, or your vision.

When a user sits down to plan out a feature they’re paying for they have specific goals in mind, those goals aren’t going to be keeping things simple and they’re not going to be looking at how to achieve most of the needs of all your customers. They’ll be looking to achieve all of their own and wont care a jot about anyone else’s. They may pay lip service to caring but in the end why should they? They’re paying to have the feature developed and if someone else wants it to do something else - let them pay.

no control

So in the end you’ve developed the feature, been paid for it but probably compromised your vision for the product in the process. You’ve also painted yourself into a corner, because now that someone has paid for this feature updates, changes and even taking it away at a later date isn’t really going to be at your discretion.

Compound this when the strategy works the first time and you try it out again. Now you’re totally loosing control of your product and your vision is a thing of the past. Your nice simple product is growing tentacles and doesn’t quite work the way an average user would want it to work. Your edge cases are taking over and your vision is becoming bloated with £10,000 buttons one person clicks once a week that confuse everyone else.

rules must have exceptions

I have seen selling features actually work in practice a few times. There have been some notable examples of open source software developers doing this.

The difference here is the features have already been requested by the community and a bounty is paid or the customer is paying to fork the code. Forking code is an option, even for a company developing closed source software or a service offering, but it’s not really an attractive one. You want to keep things as simple as possible and trying to maintain more than one product is orders of magnitude harder than just maintaining one.

it’s not worth it, just don’t do it

My very strong recommendation is to keep it simple, one code base, one product, one vision - keep it simple and don’t sell features.

In my last post I promised I’d write another about subversion and how to set things up to work with contractors. I was supposed to post this the next day, but I got caught up with other things.

Anyway, let’s just jump right in…

We run all our projects out of one big subversion repository, some people create a repository per project or group projects into a number repositories. In all honesty it really doesn’t matter how you group things, I think that one repository works better for us, I can move things around and I can allow people access to all or parts of the repository. You may feel differently, but for the time being I’m going to assume you’re working with a single repository like us.

getting started: installing apache, subversion and mod_dav_svn

I recently upgraded to Subversion 1.5, there wasn’t a package available for the version of Fedora we’re running on our server so I had to build it. It was a relatively painless process of simply making sure dependencies existed and following the instructions in the INSTALL file.

http://subversion.tigris.org/getting.html

Go do that now, get subversion and mod_dav_svn installed. There are more than enough resources out there on how to install subversion that I’m not going to go into too much detail about building from source or installing on any specific platform.

In fact since the steps and concepts I’m going over in this post don’t require a specific version I’ll just throw up some common defaults.

If you’re on a Red Hat based linux system try:

# yum install subversion
# yum install mod_dav_svn


If you’re on a Debian based system try:

# apt-get install subversion
# apt-get install libapache2-svn


In your apache configuration file, near the module declarations make sure you have the following lines.

LoadModule dav_module /usr/lib/apache2/modules/mod_dav.so
LoadModule dav_svn_module /usr/lib/apache2/modules/mod_dav_svn.so


setting up a repository

Again moving quite quickly here, there are tons of other better resources for getting started with Subversion on the web, better than I could hope to write. The basic command you need to run simply creates the directory structure that subversion needs.

$ svnadmin create /path/to/repo

It’s usually best to create this somewhere near, but not in the document tree for the webserver.

Open you’re apache config file, or the config file that stores the details for the virtual host you’re using and add the following lines:


DAV svn
SVNPath /path/to/your/repository
AuthType Basic
AuthName “Subversion repository”
AuthUserFile /path/to/your/passwdfile


Now create the htpasswd file and add a user or two using the following commands

# htpasswd -cm # htpasswd -cm /etc/svn-passwd andrew
New password:
Re-type new password:
Adding password for user andrew

# htpasswd /etc/svn-passwd -m simon
New password:
Re-type new password:
Adding password for user simon


Restart apache and that’s it all done. You should now have a running subversion repository with two users, andrew and simon, they should be able to view and commit anywhere. We’ll assume these are staff members who can view and commit on any project.

Setting up for an external contractor

Now you want to bring a contractor in on a project, so let’s create them a user:


# htpasswd /etc/svn-passwd -m john
New password:
Re-type new password:
Adding password for user john


The next thing you need to do is to setup svnauthz to control access to the repository. Back in your apache config file, add the following line into your svn config:

AuthzSVNAccessFile /home/goroam/dev.goroam.net/user/repos/svn-authz


So that it looks something like this:


DAV svn
SVNPath /path/to/your/repository
AuthType Basic
AuthName “Subversion repository”
AuthUserFile /path/to/your/passwdfile
AuthzSVNAccessFile /path/to/your/repository/svn-authz


I tend to keep my svn-authz file within my repository path, you may wish to place it elsewhere - whatever works best for you.

The next step is to create the svn-authz file. That’s as simple as this:

[groups]
staff = andrew, simon
contractors = john

[/external-project]
@contractors = rw


The file is pretty simple and self explanatory but the first block starting with [groups] defines the groups. In this case we’ve got two one for staff with andrew and simon and one for contractors with john as the single member. The usernames to use here are the same as you set in your htpasswd file. Authentication is controlled by the standard basic authentication, subversion is only controlling access.

The next two blocks are paths within the repository. The first:


[/]
@staff = rw
* = r


Tells subversion to give all members of the staff group read and write access to everything under the / path - basically the whole repository. The next line * = r tells subversion to give everyone else, read access to everything.

Again this may not work for you, but we tend to allow read access to everything to everyone with a password. If we trust them enough to give them a password, we trust them. Also it allows contractors to build dependant libraries from the head, which is required at times and saves us the trouble of working out dependencies in our svn-authz file.


[/external-project]
@contractors = rw


In the next block, above, we’re giving everyone in the contractors group read and write access to everything in the /external-project path of our repository. This of course is the project they’re currently working, so your path will be different.

That’s it. Contractors hired, up and running in your subversion in minutes.

Slightly more complicated, but easy now that you know how

Let’s just complicate things a little bit by adding two external contractors from the first company and a third from second working on two different projects.

Let’s say that CompanyA Limited are working on project-x. They’ve asked us to create accounts for Dick and Jane. Then we hire Dave from CompanyB to add a feature called zing-bang to project-y. You could, of course just create two accounts, one for each company - but we tend to avoid that. We like to know WHO committed what code. Not just where they were from, we work closely with our contractors and it helps us when we’re communicating with them.

We know how to create the users, but just to recap here we go again:


# htpasswd /etc/svn-passwd -m dick
New password:
Re-type new password:
Adding password for user dick

# htpasswd /etc/svn-passwd -m dave
New password:
Re-type new password:
Adding password for user dave


Assuming, as above we have andrew and simon as staff users we should make our svn-authz file look something like this:


[groups]
staff = andrew, simon
companya = dick, jane
companyb = dave

[/project-y/branches/zing-bang-feature]
@companyb = rw


We’re only building slighty on the previous file with the groups entries, and that should be clear. The entry here for project-x should also look familiar - Both dick and jane, members of the companya group have read and write access to the path.

For the next entry we’ve created a branch and we have company b working on the branch. I’m really just throwing that out there, mostly because I can, but also to show that you can go to any depth in the repository tree granting access as you see fit.

In this case it’s been determined that the work CompanyB in engaged to complete only needs to take place in this branch, so while they can read the whole repository they cannot write anywhere except here. This would allow you to continue internal development, or indeed external with some more entries on project-y making point releases while zing-bang feature is developed and CompanyB could merge the trunk in at will, since they have read access to it.

a lot of words

It was a lot of words, but the concepts are pretty simple. It doesn’t take long to set subversion up and even with basic auth and htpasswd files it’s not complicated to administer. So go on, get your contractors under control. I promise the dividends paid through increased accountability, visibility and communication will more than offset the time spent administrating the system.

Related articles by Zemanta

• Collaborate and Connect with Subversion

In a recently conversation I was told of a situation which I’ve experienced in the past and I’m sure others have as well.

While on holiday the code I’m responsible for has been modified by an external contractor. Before my holiday I pointed out that we should make sure version control is used by anyone making any change. It wasn’t. Now I’m frustrated and pissed off.

The problem isn’t that someone else was editing the code, or that I somehow lost control of a fiefdom or anything like that. It’s that I’ve just spent hours I could be using to do something else tracking down file modification dates and then diff’ing them against my versions out of version control. Time I shouldn’t have to had spent doing anything

The bigger issue is now I’m under pressure by my boss to deliver some changes at the same time as I have to deal with this, and no extra time has been allowed for it.

You pay contractors to do work for you, a large part of that should be to insist they do it in a way that is consistent with your working practices. You wouldn’t let them commit changes to a PHP website in ASP, Perl or Python and equally you should insist that changes are delivered consistently and in a manageable format.

Warning flags get raised if someone tells me they don’t use version control. Not knowing how and asking questions is one thing; I have no problem helping someone, a contractors included, learn our version control system and practices because I see our relationship as a long term one, so any investment in that relationship is worthwhile. If a contractor tells me they cannot or will not use our version control system though, we have a problem and usually we end the relationship then and there. It may sound like a hardline call based on a single criteria but it is a deal breaker for me.

For a contractor there could of course be some concern that they’ve submitted the work and may not be paid. Version control is not the cause of this - it’s dishonesty, plain and simple and if the person you’re working for is that dishonest submitting code via email before the cheque clears is equally risky.  

Some ground rules

Our most basic rule is commit at least once a day while you’re working on the project. This is especially the case if the work is being done on a day rate, but also if the project was quoted on a fixed rate basis. We use the data to judge if a project is on time, we’re completely upfront about why we want this: Knowing the current velocity for changes gives us a really good indication of where we are in the development cycle. With a current version committed to our repository we can just checkout, deploy and see. It removes the chances of miscommunication, misunderstandings and estimate errors.

Committing early and often by contractors is much like releasing early and often to users. It allows us to make regular builds and run QA on the project. The benefits of this are that we can start to run our testing regime long before we would otherwise be able to test. We try to encourage external developers to follow similar methodologies to those we use internally, the primary goal of any new project is to make a deployable release as quick as possible, then add features to it in a sensible manner. This coupled with regular commits allows us to test features as they’re added, not weeks down the line days or hours before the project is to go live.

Once bitten, twice shy

We’ve had a few projects in the past where we outside contractors for a variety of reasons failed to deliver on time. This has lead to our losing a follow up contract on at least one occasion we’re aware of. By getting code committed to our repository we can see where a project is, and if necessary step in early with concerns about the deadline.

Both daily commits and QA help immensely with this and all but eliminate estimate errors because we can have an honest objective conversation about how far we’re going to miss milestones very early in the process because a miss becomes obvious when you can see the velocity. The earlier you can do this, the better your chance delivering on time.

Rules for some, but not others

Sometimes it doesn’t make sense to go the whole forcing version control down someone’s throat route. For some projects and changes we’ll just bang a few files into an zip archive, email it and get the same back, then integrate it ourselves. It usually depends on the scope of the changes and how long they’re likely to be working on the project in question. We would only work with someone familiar or willing to learn version control though, even in the above scenario they’d would have to be willing to use it if we’d asked them to.

How have your experiences using version control with contractors gone? Post a comment and tell us about it!

I think tomorrow I’ll post a bit of more hands on article on setting up version control for contractors. I’ll try to focus a little more on how to build, install and implement subversion with access controls. See you then.