Continuous Documentation
-
Upload
networkedassets -
Category
Software
-
view
169 -
download
0
Transcript of Continuous Documentation
Open Automated Documentation for the Age of DevOpsTools4AgileTeams, Wiesbaden, 2. September 2016Joerg Mueller-Kindt
Introduction
2. September 2016
Tools4AgileTeams, Wiesbaden 2
• (Almost) everything – including infrastrcture – is turning into software.
• Agile is „IT“ – IT is Agile (or at least pretends to be)• We live in the Age of DevOps
= Lots of challenges for IT
This is about one of those Challenges: Documentation
Agile Manifesto
2. September 2016
Tools4AgileTeams, Wiesbaden 3
• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiations
• Responding to change over following a plan
www.agilemanifesto.org
Principle No. 3 (of 12):Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.
DevOps Cycle
2. September 2016
Tools4AgileTeams, Wiesbaden 4
Source: http://www.kensvalley.com/wp-content/uploads/2016/03/DevOps-cycle-PPT-COLOURS-Copy.png
So, DevOps
2. September 2016
Tools4AgileTeams, Wiesbaden 5
• Agile• No barriers between Dev and Ops, one continuous
cycle. • Short release cycles (down to days and hours) • High Degree of Automation, Testing, CI/CD• Ever Higher Degrees of Virtualization– Bare Metal -> VM (OpenStack) -> Containers (Docker) ->
Serverless (AWS Lambda)– Infrastructure as Code
Documentation Today- Manual Labor and ….
Veeery exciting
Why Documentation? Good Documentation:
2. September 2016
Tools4AgileTeams, Wiesbaden 8
• Collects distributed information about a project in an easy accessible place and format• Involves every stakeholder• Is the basis for operations and
maintenance processes, compliance and much more.
Agile Documentation
2. September 2016
Tools4AgileTeams, Wiesbaden 9
Problem: Speed is God and Time is the Devil
My Code is my documentation!
2. September 2016
Tools4AgileTeams, Wiesbaden 10
Agile Developers Everywhere
No, it isn‘t!
2. September 2016
Tools4AgileTeams, Wiesbaden 11
Everybody Else
But it could be…
2. September 2016
Tools4AgileTeams, Wiesbaden 12
Continuous Documentation
Agile Automated Documentation in the Age of DevOps
2. September 2016
Tools4AgileTeams, Wiesbaden 13
• Document Continuously – Continuous Documentation• Apply best practices (Clean Code, Clean Architecture,
TDD and Domain Driven Design (DDD), etc)• Use the dynamic Event Sources from Continuous
Integration and Delivery Processes• And the static data (=code) from testers, sysadmins
and, yes developers, to extract documentation
Hundreds of Tools
2. September 2016
Tools4AgileTeams, Wiesbaden 14
Our Toolset
2. September 2016
Tools4AgileTeams, Wiesbaden 15
Focus on:
2. September 2016
Tools4AgileTeams, Wiesbaden 16
• OpenSource– Everything Available under Apache 2.0 on Github– We are moving to public (community) development in QIV
2016• Java Applications running on Linux• „Cloud Deployments“ on OpenStack and Containers
OpenShift (Docker). • The toolsets provided by our partners Atlassian and
RedHat.
Architecture and Roadmap
2. September 2016
Tools4AgileTeams, Wiesbaden 17
Repos
Admin UI
AnyDocConvert• JavaDoc• ASCIIDoc• Markdow
n
Present
CI/CD
Deploy
• JavaDoc• Class Diagramm• Code Flowers
• Jenkins/Saltstack• Deployment
• Spock
COREFRONTEND SOURCE
Project Evolution
2. September 2016
Tools4AgileTeams, Wiesbaden 18
Collect Correlate Enable
Production
Staging
DevCHANGE
QIV: FriendsofDevOps.org
2. September 2016
Tools4AgileTeams, Wiesbaden 19
• Community Home: Start developing and discussing best practices together.
• Expand to different languages (C#, Doxygen, etc., etc.) and toolsets
Recommended Reading
2. September 2016
Tools4AgileTeams, Wiesbaden 22
• Scott W. Ambler: Lean/Agile Documentationhttp://www.agilemodeling.com/essays/agileDocumentation.htm
• Cyrille Martraire: Living Documentationhttps://leanpub.com/livingdocumentation
• Eric Evans: Domain Driven Design Referencehttp://domainlanguage.com/ddd/reference/
• Github pages of R.D. Müllerhttps://rdmueller.github.io/
Public Demo Server:
2. September 2016
Tools4AgileTeams, Wiesbaden 23
http://atlasdemo.networkedassets.net
THANK YOU FOR YOUR ATTENTION! Joerg Mueller-KindtMail: [email protected]
Twitter: @Joerg1968
Linkedin: https://www.linkedin.com/in/jörg-müller-kindt-984b6a3
condoc.networkedassets.comwww.networkedassets.com/opensource