Ian Berry IT Blog

Documentation (2)


Software Delivery Estimate Guideline

I have used slightly differing versions of the below to outline what should be included in an estimate, please consider each business environment, team and delivery process will have differing contexts (i.e know your context – KYC). For an overview of different estimation methods and templates please my Software Development & Delivery Estimation article. Depending on the phase of the initiative / project (pre-discovery, discovery, delivery), delivery methodology and type of work at hand (ie small agile feature, initiative, or large project) will determine which of the below estimate method to apply.

Generally there are two types of estimates:

  • High-Level – i.e very early on, not much context, quick sizing based on little information
  • Detailed – i.e close to delivery, team involved, more detail, agile point based estimation

Our delivery estimates consider a person day to be 8 hours, however when scheduling work (assuming working outside a flow based agile delivery model here) we should consider a person day of 6-7 hours (not 8) which should cover non-delivery work such as meetings, lunch, learning, training, discovery, estimation, production support, backlog grooming, story breakdown sessions, unplanned leave etc. If working in an agile method, velocity based planning will naturally take care of these items.

What should be included in an estimate

  • Analysis effort
  • Technical design effort
  • Development effort
  • Unit testing
  • Manual testing of solution
  • Test automation (including functional, integration/API, E2E and smoke tests)
  • Refactoring tasks (if possible / agreed)
  • Story kickoffs, code/peer reviews and walkthroughs
  • Build pipelines, environment setup & configuration and deployment infrastructure
  • Defect fixing in system testing, end to end testing & user acceptance testing phases
  • Deployments through lower environments to production
  • Feature toggling / rollout strategy in production and support
  • Monitoring & alerting tasks
  • Production defect fixing
  • Documentation

What should not be included in an estimate

  • Buffer, fat or contingency (this will be added at an initiative / project level when putting together estimates to share and in delivery plan). We want to avoid layers of buffer/contingency at task, feature, initiative and program level etc.
  • Spikes / prototypes / proof of concepts – these should be estimated / played as a seperate time-boxed task (ideally to inform your estimation)
  • Formal UAT Support – scheduled as a seperate task in delivery plan on large projects
  • Formal Warranty period / Hyper-care – scheduled as a seperate task in delivery plan on large projects
  • Customer meetings
  • General development activities outside this feature
  • Learning time, training, guilds, conferences etc


Agile Documentation Manifesto

Agile documentation should:

  1. Keep it simple (KIS), keep it lean (KIL).
  2. Clear and unambiguous.
  3. Lightweight, dot points, single sentences, to the point.
  4. Consistent presentation with whitespace.
  5. Well designed, organized, structured.
  6. Prefer diagrams over words.
  7. Easily searched and navigated.
  8. Easily updateable.
  9. Just in time (JIT).
  10. Stable (dont document rapidly changing work).

Ideally documentation should convey information clearly, concisely, reduce information silos (i.e. knowledge only known by an individual/team) and reduce re-learning time across teams & organisations.

 

 

Reference Material

Extract from  Agile Modelling:

Agile documentation principles

  • The fundamental issue is communication, not documentation.
  • Agilists write documentation if that’s the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation.
  • Document stable things, not speculative things.
  • Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
  • Prefer executable work products such as customer tests and developer tests over static work products such as plain old documentation (POD).
  • You should understand the total cost of ownership (TCO) for a document, and someone must explicitly choose to make that investment.
  • Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
  • Travel as light as you possibly can.
  • Documentation should be just barely good enough.
  • Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.
  • Models are not necessarily documents, and documents are not necessarily models.
  • Documentation is as much a part of the system as the source code.
  • The benefit of having documentation must be greater than the cost of creating and maintaining it.
  • Developers rarely trust the documentation, particularly detailed documentation because it’s usually out of sync with the code.
  • Ask whether you NEED the documentation, not whether you want it.
  • Create documentation only when you need it at the appropriate point in the life cycle.
  • Update documentation only when it hurts.

 

When is a document agile?

  • Agile documents maximize stakeholder ROI.  
  • Stakeholders know the TCO of the document.  
  • Agile documents are “lean and sufficient”.
  • Agile documents fulfill a purpose.  
  • Agile documents describe “good things to know”.
  • Agile documents have a specific customer and facilitate the work efforts of that customer.  
  • Agile documents are sufficiently accurate, consistent, and detailed.  

 

 




Ian Berry IT Blog, 2025. Theme Material for Coders. Privacy Policy.