Welcome in the second part of this workshop. Here you are going to switch gears.
Documentation should be written for your stakeholders. This can be a product owner, a customer, your team, yourself in 6 months, etc.
What exactly is good documentation, and how it fits your situation is not something I can write down for you.
As every code base is different and the right form of documentation should be tailered for the right audience, I can only show you techniques you can use. It is not possible to provide you with one tool that will produce everything you need or want.
Ideally you would generate documentation based on a project your are familair with, but that is not an option for this workshop. That is why this workshop will use the open source Pitstop project.
You will be using LivingDocumentation as part of the workshop. This is not a requirement to generate documentation in your own projects. But it is build on experience of doing this in a couple of projects and will save a lot of time to get you started.
As LivingDocumentation is also open source, you can replace any method with your own version to tailor the documentation to your needs. Of course, issues and pull requests are always welcome if you see something to improve.
-
Quickly start acting on your code by generating an intermediate file with all relevant parts extracted from the syntax trees.
-
Get familiar with the types and start querying relations between classes, methods, invocations, etc.
-
Build a document describing components based on the parts of you code.
-
Build a class diagram from an aggregate.
-
Build a sequence diagram from services interacting with each other.