I saw a book called “Living Documentation” in Oreilly a few years ago, but it wasn’t finished.

He had only recently published a Chinese translation of the book, and had come to think of it… I just recently had time to fill in the stuff that’s been in this hole for years.

In short, this book could be called basically Living Java Doc. Let’s take a look at what documents are involved in daily development:

  • The requirements document
  • Interface documentation
  • Business vocabulary documents
  • Module business process document
  • Interactive documents between systems
  • System architecture document
  • System dependency documentation
  • Release the document
  • Sample document (Tutorial)
  • Project progress document
  • Case document
  • Report document

There is a lot of type documentation to write, and whatever it is, it is disconnected from the project’s code. So the way the software industry used to document had a lot of disadvantages:

  • Documentation is easily outdated because it is separate from the code, and it is not uncommon to change the code and forget to change the documentation. The code is a new version and the documentation is a historical version
  • The document is misleading because, because of the previous one, the functional changes are not reflected in the document and the reader is misled by error messages
  • Redundant work, engineers have to write the code and then write the documentation (or write the documentation first and then write the code), which is basically double the work
  • There is no uniform specification for document writing tools, and people like to try new tools all the time, from Word to MarkDown to Asciidoc to Notion
  • Documentation is disconnected from the actual content of the code, such as the business vocabulary often spoken in DDD, which may not use the same word in the document and code, requiring additional mental mapping between coding and looking at the document

To overcome these shortcomings, the book suggests ways to make code live. Since the separation of code and documentation makes it difficult to reconcile the two, we pursue writing code and documentation together and generating documentation from the code through technical means.

Take a look at each of the documents mentioned above:

The requirements document

Because requirements eventually become BDD tests, you can use BDD tests directly to generate these requirements documents.

The vocabulary

When doing business with DDD, you can generally annotate the types and interfaces with words that you can see at a glance: @DomainService, @DomainEvent, @Businesspolicy, @AbAstractFactory, @Adapter, @BoundedContext, @ValueObject.

To emphasize some business concepts, you can also use custom terms such as @coreConcept, @coreBehavior, and @statemachine.

By scanning the code, the above concepts can then be extracted directly from the project, and each time the code is updated, the business vocabulary can be automatically generated.

Automatic interface document

I think a lot of people have seen this, it’s like Swagger’s project. The best companies in the framework have a swagger-like approach to their interface platform (which is rare). Here’s an example of using swagger in Beego:

Since the Go language does not support annotations, annotations written inside annotations do not have syntactic checks and constraints, which may be a disadvantage compared to other languages that do.

Business process document

Write corresponding process nodes and contextual nodes in the code:

Generate documentation by scanning code:

Cross-system interaction flow:

Scan to generate the corresponding document, which is actually similar to the previous one:

In addition to the above style annotations, there have been previous ways to generate documents from text, such as Plantuml, Graphviz

The text of Plantuml, like the one above, can itself be managed in the same repository with the code.

In some business logic where difficult logic is involved, @policy or @businessConvention can be used to explain the reasons for the business decision.

Release the document

Many open source projects on Github can now automatically generate release notes based on commit messages. This is due to the fact that the Commit Message itself has a specification:

A simple Bash script can sum up the Commit messages between the two versions and write out a fully canonical release note.

Many open source projects in China still write release note.

tutorial

For starters, there are code examples to look at. If the project has written canonical code, Exemplar can be used as an example: @exemplar (” This order process is a good example to learn about CQRS “). Scan the code to find all of the @exemplar annotations to become a tutorial document.

Stable document

Stable documentation refers to documents that rarely change and are acceptable to separate from the code. To make our documentation stable, we should follow some basic writing principles, such as:

  • Don’t bring information about your company that can change easily: company name, subsidiaries, brands, logos, etc
  • If you include links in your documents, you should go from unstable documents to stable ones. For example, you can post a link to Wikipedia from your blog, but if you edit a wiki and post a link to your own independent blog, it may not be appropriate
  • Don’t copy and paste. Use links to refer to existing content

Report document

If it’s project progress related, use an annotation like @wip or @pending.

If it’s a case to show to the boss, the boss is too busy to have time, so you can use @keyExample to pick out the cases that need to be shown separately.

In addition to the tutorial mentioned above, @normalcase, @Specs, etc.

Architecture documentation

Architecture is a single module, is common in the DDD hexagon structure, can be introduced to key words in the DDD, and generate the final document, such as @ HexagonalArchitecture. DomainModel, @ Adapter, the resulting document is the following:

For cross-system documents, such as CQRS, they are also Given(Event), When(CMD), Then(Output Event), so BDD can be used to generate such documents, as mentioned above.

Runtime documentation

The author believes that zipkin and Dapper tracing systems are also a form of documentation. The service dependencies drawn in the service discovery system are also a document.

Declarative configuration

Declare system configuration, resource requirements, and dependencies, and generate documentation.

In this sense, K8S’s YAML is both documentation and code.

Architecture Panorama

When all documents can be generated by scanning code, it is best to manage these documents in a unified architecture panorama, which may also be generated with annotations such as @layer (LayerType.infrastructure), @ Repository (aggregateRoot = Customer. Class).