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: jmk@networkedassets.org

Twitter: @Joerg1968

Linkedin: https://www.linkedin.com/in/jörg-müller-kindt-984b6a3

condoc.networkedassets.comwww.networkedassets.com/opensource