Docs

There, I said it. A four letter swear word. Something worse than the F’ word if the horror on the boss’ face is anything to go by.

We don’t do “documentation” anymore and besides, the agile manifesto says it’s immoral to write a word of documentation. The code is the documentation. That you have to get inside the twisted maze of my mind, and work out what drug infused insanity I was trying to convey at the time and which may or may not result in what was intended regardless… that’s your problem.?

Such nonsense pervades software development today. Although…

It’s not the lack of documentation per se but the lack of demonstrable thought that bugs me. A critical explanation of why things are the way they are.

Why has solution design been so poorly treated?

The answer to that lies in what design is trying to achieve.

Solution design aims to address the needs of the system, communicates how these needs are met and enables testing of the solution when the cost of change is lowest.

This testing is achieved by static walkthroughs and peer review.

However, in an agile world where we breakdown features and stories into small chunks that can be delivered rapidly and iteratively, the hefty tombs of yesterdays solution design documents are equally shrunk to focus on the few features and stories in scope.

Taken far enough it ends in a combined whiteboard design and review session with a handful of developers. And beyond taking a photo and circulating to the team, what's the point in doing anything more?

Firstly there's the supporting teams who are going to care for your solution through its early teething days, rebellious teenage years, into maturity and all the way to the grave – death being one of the few certainties in life. Making these guys bump their way around a darkened room trying to figure out how things hang together is unfair if not sadistic.

These guys don't work in scrum teams or story by story. They work from incident to incident, from shit-storm to fan-splattering shit-storm. They need a concise and holistic view of the solution for which a few poorly framed holiday photos doesn't cut it. Honestly, these guys are too nice to you.

Then there's the not insignificant matter of consistency.?

You can argue the marginal benefits of any technology but you need to justify any change which runs counter to the inherent design patterns of a system as contributing significant value to overcome the increased complexity and costs it brings.

Do things consistently and you get paybacks in terms of proven reliability, easier maintainability, reduced cognitive load, faster delivery and so on.

Do things inconsistently and whilst you may get to play with the latest?tech you're being pretty selfish - if that's your motivation. And if it's not then see above re justifying the increased complexity and costs.

Which brings me to my point on solution design.

Solution design is about more than addressing the needs of a few stories on a sprint by sprint basis. It's about addressing the broad needs of the system and providing a vision for the longer term. Defining the patterns which will be used time and again and which (should) enable that payback through consistency.

This isn't an argument that technological progress isn't a good thing or that we should never have crawled out of the sea. Or that your resident architect has all the answers. It's an argument to think about the broad needs, key decisions, responsibilities, patterns, principles, policies and costs - immediate and long term - that provide the foundation on which any system is based.

At times it may seem futile and time consuming but it's cheap to change this stuff early on rather than late on when it's most expensive.

And the way we do that best is through reasoned discourse. Discourse best expressed through quality documentation - words, diagrams and matrices.

Matt Phipps-Taylor

Chief Information Officer at Peermusic

3 年

Excellent piece, Kevin.

回复
Chris Gilbert

Senior Software Engineer and distance runner

3 年

I've been thinking the same thing lately and my answer is a great readme that explains the design ethos, the thought process, why things are as they are, maybe some usage. We all use open source software and that is the first place I go to understand what it is all about, we often don't treat our readmes the same as our expectations of those provided by others

David Orrock

Senior Engineering Manager at Sedna Systems

3 年

Depends if anyone uses the docs ?? I get your point, there’s a real focus on solution design at a feature-level which isn’t very practical at times (particularly in greenfield or MVP initiatives). I’m not sure swathes of unread tomes is the right answer though. Discourse sounds right but you’ve got to get people out of their iterations first, which they won’t appreciate.

回复

要查看或添加评论,请登录

Kevin Barclay的更多文章

  • Pictures v Diagrams

    Pictures v Diagrams

    A picture is worth a thousand words, words which come down to interpretation. A diagram is not the same as a picture.

  • Road Maintenance

    Road Maintenance

    I live and spend most of my time cycling in the south east of England. I ride on a combination of dedicated cycle…

  • Off to see Nessie

    Off to see Nessie

    This weekend I’m off to Inverness for a ride around Loch Ness and a chance to spot the monster. I enjoy these events…

    4 条评论
  • Design Reviews

    Design Reviews

    Though I try, I suspect I'm as guilty as anyone. People in glass houses etc.

  • The internet is down, all is well

    The internet is down, all is well

    A few weeks ago I switched from Zen internet (stable enough; a touch more expensive than the big boys; excellent…

    6 条评论
  • We can't go on like this...

    We can't go on like this...

    I'm sitting here in the sun - yes, it's sunny in south London - and for the past 30 minutes I've been trying to buy…

    6 条评论
  • Don't treat people like serverless functions

    Don't treat people like serverless functions

    When I were knee high to a grasshopper we didn't have all this new fangled cloud infrastructure and we certainly didn't…

    4 条评论
  • The Con of Agile (or why agile reductionism is hard…)

    The Con of Agile (or why agile reductionism is hard…)

    Agile is, to a large extent, a radical breakdown of function into small incremental features delivered in a prioritised…

    3 条评论

社区洞察

其他会员也浏览了