Removal of documentation section (title)?

[dirkgroot]

Hi @simonbrowndotje,

Following the latest couple of releases, I have a question about the support for documentation sections.

In version 1.22.1, you removed the title argument from the Section constructor. In the release notes you suggest that the title is unused. In the release notes for version 1.22.3 you seem to suggest that documentation sections will be removed altogether.

The removal of the title from documentation sections is a breaking change for Structurizr Site Generatr, as we use it for links to documentation sections in the menu, and in the "Documentation" overview for a software system (example).

Removal of documentation sections entirely would be a breaking change as well, because we would either have to remove the documentation feature from the site generator, or find another way to include documentation in the generated site.

So my question is: Could you clarify what your plans are, regarding support for documentation in Structurizr?

[dirkgroot]

PS: You also deprecated Enterprise and Location. What are your plans regarding those concepts?

[simonbrowndotje]

The enterprise/location concepts were introduced years ago, but don't support describing software systems across multiple enterprises. So I've deprecated those concepts, and added support for nested groups -> https://github.com/structurizr/dsl/tree/master/docs/cookbook/groups#nested-groups

[dirkgroot]

Thanks for the clarification! Seeing how nested groups work, it makes sense to remove the enterprise concept, as groups are a more generic mechanism for partitioning the model. They can be used to depict the enterprise boundary, and add more partionioning based on other criteria as well.

[simonbrowndotje]

Nested groups are supported by the PlantUML renderers now too, although the C4-PlantUML version doesn't support group styling yet (this should be added later today though).

[simonbrowndotje]

When I first added the documentation support a few years back, I envisioned a nice structured approach where people would write one section per Markdown/AsciiDoc file. In this situation, having a title property made sense. But that isn't the reality of how many people want to use the tooling.

The Structurizr renderer also depends on titles (e.g. https://structurizr.com/share/31/documentation), but those titles are now just extracted from the content at runtime. This is a much simpler approach, and removes the 1 section = 1 file restriction.

In the release notes for version 1.22.3 you seem to suggest that documentation sections will be removed altogether.

That was a typo - sorry! It should read "documentation section titles" rather than "documentation sections". 😀

[dirkgroot]

Thanks again! I'm relieved that documentation sections aren't slated for removal 😅. I really like that feature!