Systems (2)


Principles Of Software Development

A set of guiding principles for software development, applying rule of thumb over strict governance.

P1:    Build in the simplest way possible (KIS).

P2:    Prefer working in smaller increments, build for fast feedback, refactor as necessary. Apply the rule of 3.

P3:    Be a commercial developer (consider build cost, support cost & total cost of ownership) and provide regular updates on progress.

P4:    Be flexible in your approach depending on problem at hand – prototype / spike / hack for early customer or technical feedback and build solid, testable, maintainable, clean & quality code once feature/concept proven.

P5:    Apply the Testing Pyramid approach to quality assurance

P6:    Pick the best tool / technology / approach for the job at hand. Consider optimising for the whole; globally rather than locally.

P7:    Apply 12 factor app design, with architecture emerging. Consider the *ilities, make trade-offs visible as shouldn’t necessarily design for all – see fitness function fit.

P8:   Collective (collaborative) code ownership – the sum of all experiences leads to better software.

P9:   Follow Robert C. Martin’s ’the boy scout rule’: leave the code better than you found it.

P10:    Follow the Agile Documentation Manifesto. Prefer working software over documentation.

P11:  Replace manual processes with automation – automate all the things, reduce waste, improve throughput.

P12:   Be disciplined – taking shortcuts / taking on technical debt can be an option short term, but left unpaid almost always leads to poor longer term outcomes; a reduction in team productivity, cost-effectiveness and increased risk.

P13:  Work at a sustainable pace, limit work-in-progress (WIP), stop starting and start finishing.

P14:  Design for failure (error driven design); consider all the things that could go wrong such as hardware failures, network failures, database failures, system slowness, upstream & downstream system failures, cancellations, time-outs, non-happy-day user flows 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.