documentation ”done right” “efficient system integration documentation“ bugs presentation...
TRANSCRIPT
![Page 1: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/1.jpg)
Documentation ”done right”
“Efficient system integration documentation“
BUGS presentation Sthlm 2012-10-03
Richard Hallgren – iBiz Solutions
![Page 2: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/2.jpg)
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!
![Page 3: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/3.jpg)
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
![Page 4: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/4.jpg)
Types of documentation
End user documentation
Help desk documentation
Infrastructure documentation
Architecture documentation
Requirement documentation
Marketing documentation
![Page 5: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/5.jpg)
Levels of documentation in a integration project
System overview
Integration/process specific
Technical
![Page 6: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/6.jpg)
Example system overview documentation
• Instant overview
• Non-technical• EA –
information flow
![Page 7: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/7.jpg)
Example integration/process specific documentation
• Implementation details
• Complements textual description
![Page 8: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/8.jpg)
Find a common “language”
Message
System
Service
Contract
Inte-gration
Endpoint
Enterprise Integration Patterns – Gregor Hohpe, Bobby Woolfhttp://www.eaipatterns.com
![Page 9: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/9.jpg)
Technical documentation
Demo
![Page 10: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/10.jpg)
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
![Page 11: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/11.jpg)
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
![Page 12: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/12.jpg)
True or false?
• Documentation is fun!
![Page 13: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/13.jpg)
Resources
• https://github.com/riha/btswebdoc• http://btswebdoc.com• http://biztalk2010autodc.codeplex.com• http://
www.enterpriseintegrationpatterns.com/downloads.html
![Page 14: Documentation ”done right” “Efficient system integration documentation“ BUGS presentation Sthlm 2012-10-03 Richard Hallgren – iBiz Solutions](https://reader030.vdocuments.mx/reader030/viewer/2022012910/56649d0c5503460f949e0a4a/html5/thumbnails/14.jpg)
Thanks for listening!
?