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
Architecture documentation
Infrastructure documentation
Requirement documentation
Marketing documentation
Help desk documentation
End user 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”
Endpoint
Service
Contract
Integration
Message
System
Enterprise Integration Patterns – Gregor Hohpe, Bobby Woolf
http://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 commandments
I.
Thou shall not manually document anything that can
be automatized
II. Thou shall keep it simple & make it look nice
III. Thou shall use a wiki based platform
IV. Thou shall use pictures whenever appropriate
V. Thou shall have well defined guidelines for your
documentation
VI. Thou shall have a well defined target audience for
your documentation
VII. Thou shall document continuously in your project
VIII. Thou shall have a common vocabulary and common
icons defined
IX. Thou shall test your documentation with target
audience
X. 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.co
m/downloads.html
Thanks for listening! 
?