WritingAndReviewingTechnicalDocuments

From SPA Wiki

This session was run by Andy Longshaw and Nick Rosanski on Monday morning.

Contents 1 Document review 1.1 Group 1 1.2 Group 2 1.3 Group 3 2 Selling Documents 3 Improvements 3.1 Discuss diagrams 3.2 Examine Formats

Document review

We asked the groups to review the Jerusalem document (File:WritingAndReviewingTechnicalDocuments1.doc) and this is what they came up with.

Group 1

  Goal and Audience

• Unclear
• We are reviewing under the assumption that
  • Purpose = architectural proposal
  • Audience = Peer architects
  • (reviewers should assume a role)
• Recommend produce other docs for other groups
  • E.g. business stakeholders
  • (Reviewers should provide specific examples)

  Introduction should explain context clearly

• What we replace and why
• Constraints on project
• E.g. state perf problems not marketing stuff!

  Near top

• Explain "RT" & "Jerusalem" & "Mothership" & "USS Enterprise"
• Explain what's different to previous systems

  References
  Restructure

• • Start with diagram 2
  • Label diagram
  • Explain parts of diagram
    • Services table
  • (Useful pattern to restructure text around diagrams)
• Focus and inconsistent level
  • Remove "Users" section and 2nd part of "Data".
• UI diagram %2b explanation
  • Include relationships
  • Split diagram?

  Technical objections

• We don't bellieve this works!

  Structure and consistency of diagrams

• Remove "silverlight" on diagram
• Separate business objects from UI
• Add proper description
• (consistency of level & topic important both in diagrams and text)

Group 2

• Business case unclear
• Audience too broad
• More sales pitch than blueprint
• Undefined abbreviations - too much jargon
• Too many for sign-off and review - take too long
• Document history suspicious: why not version 1? Vague/non-specific mods
• Assumed audience knowledge
• Implementation date inconsistent with doc date (2007/2008)
• Colloquialism - "Mothership" - jargon
• Overview could have "marketecture" diagram
• Inconsistnet formatting style and diagrams
• Disorganized
• Mismatch between text and diagram
• Confused arch - card swipe used - why? - authentication *and* logon?
• Inappropriate detail (too little/too much)
• Unclear how technology supports arch
• Incomplete (e.g. list of users)
• How does system address needs of users?
• Symbols unclear

Group 3

• Who for?
• No purpose
• Full of How
• How is inconsistent
• Refactor
  • Objective
  • Structure
  • Match to draft
• Good for author
• Not convincing

Some of our own thoughts on this document are included in an annotated version File:WritingAndReviewingTechnicalDocuments2.doc

Selling Documents

• Are all documents selling documents?
• All have selling aspects to some extent
• Writing documents that are timeless is really hard
• Important to get the right style
  • Write all documents so "your mother" could understand them
  • Tech people could get impatient with this
  • Use Powerpoint for this style of document?
• Replay back to people what we think they think
• Bring in tech authoring skills
• Change process is important
• Benefits/costs/risks
  • Mitigate risks %2b illustrate benefits
• Business touchpoints, e.g. interface, business process
• How important is a demo/prototype?
  • Managing expectations
  • Prototype != system
  • Key selling points/mitigations
  • Use a different technology to build prototype?

Improvements

Discuss diagrams

• More than one diagram
  • Complexity
  • Levels
  • Audiences
• Consistent

Examine Formats

• MHT
• Google Docs
• DocBook %2b Subversion