Over the last week, I have looked at the code for 4 projects. Each of these is for clients for my new consultancy, Platform Eight (more on that another time). There is a common thread I have seen across the projects and that is a complete lack of documentation.
Now I know that as developers we hate documentation and I get that. The dream of writing code that is so prose-like that no documentation is required is still just a dream. This post isn’t a rant about a lack of functional documentation or schematics. Agile rightly attempts to limit this.
What every project does need though is an up to date, relevant README
A README file is a file written using Markdown syntax. It is used to convey some basic information about your project. Details such as how to clone it, required software or libraries and how to build and get the project running. The README is usually found in the root of the project folder. Git-based source control systems such as GitHub use this content. They display it when you land on the projects hosting page.
Now stop and think about how you mentally feel when searching for projects on GitHub. Do you trust the projects that have no details on their page? Or do you find yourself more trusting of the pages with lots of helpful details and screenshots?
Private, commercial, projects are no different. Git allows me to see who has worked on a project. Their reputation to me is influenced in the same way as you are influenced when landing on a GitHub project. The impact of a reputation for software teams and dev houses is even greater. When being paid to start a project with a view to handing it back, the lack of a README or any basic project document is damaging. I would advise any client to demand this document in any agreed contract or agreement or withhold payment until it is produced.
Why? Well, there are a couple of trains of thought here. The first is developer productivity. If a developer takes over a project they want to be up and running with the code ASAP. They do not need to spend their time figuring out how they need to configure their machine. What version of the stack should they be running? Which libraries and versions need to be installed? Some frameworks make this a trivial matter. But some allow you to set up projects and environments in various ways. Again this matters if you transfer a project between developers or teams and you are paying a day rate. You are effectively doubling your costs. The other thought is that if the developer(s) can not be professional enough to add a README then what state is the code in? That might seem a harsh comment and is not always the case but it carries merit.
As always you might want to think of it from an investment point of view as well. If you have to go through a Due Diligence process with no basic documentation then you will need to defend that.
Here is a great template from GitHub. If you need to, go and copy it and fill in the blanks. Don’t be the developer or team that tries to hide or use your project knowledge for financial or reputational gain. It just makes you look bad.
If you have thoughts around this subject please contact me via twitter or email.
Five years ago today I joined Open Energy Market. The plan was to create a new technology-focused commercial energy buying platform. It was an industry that managed their data in spreadsheets. There was no transparency for clients in either costs or the value in their data. There was zero competition between the suppliers. It seemed like an opportunity to build something new in an industry that could still be disrupted.
Five years on and the company is still growing from strength to strength. At one of our regular company days recently we took the time to sit back and look at what we have achieved. The market is saturated with brokers of varying sizes but we now just sit outside the top ten. We manage a significant percentage of commercial consumption in the UK and have launched products new to the market which customers are keen to buy into. None of the ten top brokers is providing access for customers to their data in the way we have. They know that in doing so it will reveal the high costs and charges they have hidden for years.
I have been very fortunate to work with some great people over the last five years. As the company has grown we have brought in some very experienced people who have added real value. From the early days in a small, mouldy office in Surbiton to our current offices in Guildford and Bromesgrove change has been a steady constant, always for the better. Some of the early team have gone, some have even left to found their own companies.
Yesterday marked my last day at Open Energy Market. Five years is a long time to lead the development of one product. Taking the prototype through the early customer lead iterations through to the investment last year. Moving beyond the excitement of investment and into the next stage of the companies growth. I am proud of the technology we have built in such a changing environment. I am also aware of the opportunity in front of the company and the longer-term company plans. Now felt like the right time to pass the reins on to the right person to lead these second phase.
Personally, my proudest achievement is the technology team I built. A small team that grew over a few years and which seems like a second family. Some I have worked with before, all I hope to again in the future. A remote team that showcased all the benefits of such teams. Finding great people regardless of location that is so productive that collectively you can achieve great things. From my early compadre Saurabh through to Clare, Andrew, Irene, Liam, Paul, Manish and Reena I thank you all. You have made the last five years fun and rewarding journey for me. Our discussions, planning, realisations and technical achievements have made me think in ways I may never have. I hope you all got as much from me as I from you.
I wish Chris and the whole Open Energy Market team all the best for the exciting times that lay ahead. I will be following their progress closely.
I am going to take a small amount of time before embarking on my next roles. I am keen to continue working with small teams and early startups as the energy and excitement they generate is addictive. I will now have time to provide advice and support where needed and take up some of the opportunities presented to me.
If you wish to discuss an opportunity please contact me via twitter or email.
A super busy week (for reasons that will become clear in next weeks post) led me to almost not posting this week. But, I was on Twitter tonight and saw a Tweet gaining a lot of attention and I can see why.
By executing the following code in the developer tools of your browser (or in a script)
document.designMode="on"
you can directly edit the content of the web page you are on. Just like a CMS editor. The property defaults to “off”.
This may not seem a massive thing. I can think of many times this would have saved me so much editing via development tools when sat with a user.
The full feature details can be viewed here. I did read in a couple of associated articles that for IE the on/off values for the property need to be capitalised.
The changes you make can not be saved from what I can see and do not show up in the diff tools provided by developer tools. It is still really handy and I will make a lot of use of this.
If you have any great tips for front end development then please contact me via twitter or email.
Over the last month or so I have read two books that are polar opposites in their content. But, they both offer a positive and hopeful view of the future. The books are:
Enlightenment Now is an explanation of human progress since the Age of Enlightenment. A data-driven, extensive defence of scientific discovery and the adoption of humanism. Over two-thirds of the book uses data to show how better everyone is as time progresses. Pinker uses data covering area’s as diverse as the environment, world peace, democracy and personal health and wealth. There is a range of statistic’s which stand out against the onslaught of misinformation the world is currently experiencing. By looking at the data around threats from Terrorism, for example, it is clear that while there are genuine threats there are also politically-driven agenda’s at work as well. The book is not light reading but you find yourself really thinking through the idea’s he puts forward. I wholly recommend reading it.
Humans: A Brief History of How We F*cked It All Up is the counterpoint of view to Enlightenment Now. But, it is no way a heavy read. It is a light-hearted look at how as humans our brains allow us to make terrible decisions. It is full of funny, laugh out loud, stories from throughout history that prove his point. There are chapters on colonialism and environment damage but my favourite part was how he tells the life story of Thomas Midgley. He was the chap that was responsible for two of histories greatest bad decisions. I will not spoil the story but it will leave you speechless. This book is very much worth a read and makes you feel better about some of your own stupid mistakes in life.
If you have any views on the above two books or good read recommendations then please contact me via twitter or email.
I have recently been discussing the way we label developers with a few friends. The conversation started after a couple of deep discussions with team members. These discussions where around how and when a developer moves between perceived stages. For example for mid-level to senior. This lead me to looked back and reflected on my career and start thinking more deeply about the issue.
What follows is purely a brain dump around the question of:
Why do we often label developers based on seniority?
Junior, Mid-level, Senior. The dreaded “Rockstar”. These are typical labels applied to developers throughout various stages of their careers. The trouble with these kinds of labels is distinguishing when or how you move between them?
It is almost certainly related to the salary structures companies need. Rating and categorising creative professionals is hard as we have seen from the fall out of other industries. What makes one actor more valuable than another? Why is one artist more valuable than another? By creating labels to apply, it makes valuing a developer easier.
The trouble is that programming skills vary from one developer to another. Some people start programming earlier in life. Some do not start until later. The proliferation of schools and firms offering to teach programming has been staggering. Does that mean that graduates from somewhere like General Assembly are worth less than a graduate with a CS degree? These schools condense the teaching into smaller time frames than a typical university. But these courses teach a more modern and real world focused set of programming skills over traditional degrees. This raises an interesting point. If you compare two candidates, one self-taught and the other straight from university who is immediately more productive?
A junior developer, by title, said in their review recently that they have completed two years on the project so were no longer a junior. This developer had completed a minor amount of programming training before joining the team. No degree, no bootcamp. They had decided to move into programming for better prospects. When they interviewed they struggled to even get a Hello World style program running. The current project is the only project they have ever worked on. I discussed this statement with the developer and asked them some questions. These revolved around their ability to build a new project. “Could you develop X?”, “How long would you need to do Y?” type questions. Through the process, they realised that while they might not be a junior developer on our project they would struggle on another project. By their own admission, they would need significant time to get up to speed on other technologies and projects.
So the question then becomes am I only labelling this developer to fit within our salary bands? In the case of my project, yes. One other thought though comes to mind. If I change the developers title to Fullstack Developer does that mislead others in the industry when that developer leaves my team? He is a Fullstack on my team but that’s not a fair representation for other teams. We have all interviewed candidates that do not have the right skill set. Is this waste of interview time just caused by mislabelling of their real skills and experience?
Perhaps as an industry, we need to move away from labels. I think we should return to focusing on titles that reflect what people do and not their level. Developers are Developers and Product Owners are Product Owners. We should focus on the length of experience and previous projects undertaken. Salaries should be based on the value that a Developer can add to your project and team and not because they fit within a £5k salary band. Some companies have already gone down this route. They will have flat salaries based on technologies and years experience. For my next teams this will be the route I will investigate.
From talking to friends about this there is a lot of strong feelings within the community. The majority find the labelling currently applied pointless. Some point out that this might not just be about salary but about old style business career routes. You used to join as an administrator in an office and then get promoted to a senior administrator and so forth. Whatever the reason, labeling developers based on arbitrary stages of their career seems to be detrimental to both the developers and the industry as a whole.
If you have any comments on my thoughts above then please contact me via twitter or email.
Welcome to my site and blog. You can find out about me and read my thoughts on code and technology, start-ups and building things.
