Documentation â€‌done rightâ€‌

  • View
    62

  • Download
    0

Embed Size (px)

DESCRIPTION

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. - PowerPoint PPT Presentation

Text of Documentation â€‌done rightâ€‌

PowerPoint Presentation

Documentation done rightEfficient system integration documentation

BUGS presentation Sthlm 2012-10-03

Richard Hallgren iBiz SolutionsTrue 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 dateEasy to understand, well scoped and at right level of detailEasily accessible, easy to share, searchable and nice lookingConsistent and according to guidelines

Types of documentationEnd user documentationHelp desk documentationInfrastructure documentationArchitecture documentationRequirement documentationMarketing documentationLevels of documentation in a integration projectSystem overviewIntegration/process specificTechnicalExample system overview documentation

Instant overviewNon-technicalEA information flowExample integration/process specific documentation

Implementation detailsComplements textual descriptionFind a common language

MessageSystemServiceContractInte-grationEndpointEnterprise Integration Patterns Gregor Hohpe, Bobby Woolfhttp://www.eaipatterns.com Technical documentationDemoWhy MS Word sucks for documentationBuilt to reflect a print paradigmNo linking, no deep linkingHard to accessHard to shareHard to updateNo built-in versioning and commenting

10 commandmentsThou shall not manually document anything that can be automatizedThou shall keep it simple & make it look niceThou shall use a wiki based platformThou shall use pictures whenever appropriateThou shall have well defined guidelines for your documentationThou shall have a well defined target audience for your documentationThou shall document continuously in your projectThou shall have a common vocabulary and common icons definedThou shall test your documentation with target audienceThou as the developer of an integration should document it

True or false?Documentation is fun!Resourceshttps://github.com/riha/btswebdochttp://btswebdoc.comhttp://biztalk2010autodc.codeplex.comhttp://www.enterpriseintegrationpatterns.com/downloads.htmlThanks for listening! ?