Download
1 / 14
140 likes | 366 Views
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.
E N D
Documentation ”done right” “Efficient system integration documentation“BUGS presentation Sthlm2012-10-03Richard 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 Inte-gration Message System 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 commandments • Thou shall not manually document anything that can be automatized • Thou shall keep it simple & make it look nice • Thou shall use a wiki based platform • Thou shall use pictures whenever appropriate • Thou shall have well defined guidelines for your documentation • Thou shall have a well defined target audience for your documentation • Thou shall document continuously in your project • Thou shall have a common vocabulary and common icons defined • Thou shall test your documentation with target audience • 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
