I came across a book in Oreilly a few years ago called Living Documentation, but it was a dead end.

Alan had recently published a Chinese translation of the book, which reminded him of this fact… Just recently I had time to fill in this hole for several years.

In short, this book could be called living Java Doc. We can start by looking at what documents are involved in daily development:

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

There is quite a bit of type documentation to be written, and whatever it is, it is disconnected from the project code. So there are a lot of drawbacks to the way the software industry documents:

  • Documentation is easily outdated because it is separate from the code. It is common to forget to change the document when you change the code. The code is new and the document is historical
  • The documentation is misleading, because the previous feature changes are not reflected in the documentation, and readers of the documentation will be misled by error messages
  • The extra work, which engineers have to document again after writing the code (or document first and then write the code), is basically double the work
  • There is no uniform specification for how to write documents. People like to keep trying new tools, from Word to Markdown to Asciidoc to notion
  • Documents are disconnected from the actual code content. For example, business vocabularies often spoken in DDD may use different words in documents and code, requiring additional mental mapping when coding and viewing documents

To overcome these shortcomings, the book suggests ways to make code living. Since the separation of code and documentation makes it difficult to unify the two, the pursuit is to write code and documentation together and to generate 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, BDD tests can be used directly to generate these requirements documents.

The vocabulary

When doing business with DDD, you can usually annotate types and interfaces with words that make sense at a glance: @DomainService, @DomainEvent, @Businesspolicy, @AbastractFactory, @Adapter, @BoundedContext, @ValueObject.

In order to emphasize some business concepts, you can also use some custom words, such as @coreConcept, @coreBehavior, @statemachine.

These concepts can then be extracted directly from the project by scanning the code, generating the vocabulary of the business automatically every time the code is updated.

Automatic interface document

This is a swagger project that many people have seen before. Companies that do well with frameworks will have their own interface platforms based on swagger. Here’s an example of using swagger in Beego:

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

Business process document

Write corresponding process nodes and correlative nodes in the code:

Generate documentation by scanning code:

Cross-system interaction flow:

Scan to generate the corresponding document, in fact, the same as before:

In addition to the annotations in the style above, methods of generating documents from text already exist, such as Plantuml, Graphviz

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

For some business logic that is difficult to understand, @policy or @businessconvention can be used to explain the reasons for the corresponding business decision.

Release the document

Many open source projects on Github now automatically generate release notes based on commit Messages. This is due to the specification of the Commit message itself:

With a simple bash script, you can summarize the Commit messages between the two versions and write a fully normalized Release note.

Many open source projects in China are still written release Note by human flesh.

tutorial

Exemplar: @exemplar (” This order flow is a good example for learning ABOUT CQRS “). This becomes a tutorial document by scanning the code to find all @Exemplar annotations.

Stable document

Stable documents are those that do not change much. It is acceptable to separate documents from code. To make our documents stable, we should follow some basic writing principles, such as:

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

Report document

If something is related to project progress, use annotations like @wip or @pending.

If the case is for the boss, the boss is too busy for time, so you can use @keyExample to pick out the cases that need to be shown separately.

If it’s for beginners, in addition to tutorial, you can have @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:

If it is a cross-system document, such as CQRS, it is also in the form of Given(Event), When(CMD), Then(Output Event), so BDD can generate such a document, as mentioned above.

Runtime document

The author believes that Zipkin and Dapper tracing systems are also forms of documents. The service dependencies drawn in the service discovery system are also documents.

Declarative configuration

Declaration of system configuration, resource requirements, dependencies, can also generate documentation.

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

Architectural Panorama

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