Documentation ”done right”
description
Transcript of Documentation ”done right”
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 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
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
Resources
• https://github.com/riha/btswebdoc• http://btswebdoc.com• http://biztalk2010autodc.codeplex.com• http://
www.enterpriseintegrationpatterns.com/downloads.html