Documentation ”done right”

“Efficient system integration documentation“

BUGS presentation Sthlm 2012-10-03

Richard Hallgren – iBiz Solutions

True or false?

• Documentation usually has low priority and pushed to the end of projects.

• 20-30% of an average project should be spend on documentation – it rarely is …

• The majority of all documentation is never read and updated properly once completed!

• ”Good” documentation is useful.• Documentation is fun!

What is ”good” documentation?

• Complete, correct and up to date• Easy to understand, well scoped and at right

level of detail• Easily accessible, easy to share, searchable

and nice looking• Consistent and according to guidelines

Types of documentation

End user documentation

Help desk documentation

Infrastructure documentation

Architecture documentation

Requirement documentation

Marketing documentation

Levels of documentation in a integration project

System overview

Integration/process specific

Technical

Example system overview documentation

• Instant overview

• Non-technical• EA –

information flow

Example integration/process specific documentation

• Implementation details

• Complements textual description

Find a common “language”

Message

System

Service

Contract

Inte-gration

Endpoint

Enterprise Integration Patterns – Gregor Hohpe, Bobby Woolfhttp://www.eaipatterns.com

Technical documentation

Demo

Why MS Word sucks for documentation

• Built to reflect a “print” paradigm– No linking, no deep linking– Hard to access– Hard to share– Hard to update– No built-in versioning and commenting

10 commandmentsI. Thou shall not manually document anything that can be

automatizedII. Thou shall keep it simple & make it look niceIII. Thou shall use a wiki based platformIV. Thou shall use pictures whenever appropriateV. Thou shall have well defined guidelines for your

documentationVI. Thou shall have a well defined target audience for your

documentationVII. Thou shall document continuously in your projectVIII. Thou shall have a common vocabulary and common icons

definedIX. Thou shall test your documentation with target audienceX. Thou as the developer of an integration should document

it

True or false?

• Documentation is fun!

Resources

• https://github.com/riha/btswebdoc• http://btswebdoc.com• http://biztalk2010autodc.codeplex.com• http://

www.enterpriseintegrationpatterns.com/downloads.html

Thanks for listening!

?