Architecture Documentation of UCS as example for iterative writing

The documentation family for Univention products grew by a new member, the Univention Corporate Server Architecture. You can find the document online and for download as PDF. It is the first iteration of a much larger documentation project that covers the technical architecture behind Univention Corporate Server (UCS) on different detail levels for different audiences.

For whom is the documentation for?

The first iteration addresses consultants, administrators, solution architects, software developers and system engineers who want to get an overview about the positioning of UCS in the IT world and the various concepts behind UCS about for example the domain, roles and permissions.

The goal is to provide a comprehensive understanding of the technical architecture of UCS, so that consultants, administrators and solution architects can better cover their IT use cases, plan and operate their IT environment with UCS. The document also wants to enable software developers and system engineers to faster dive into software development for UCS.

The content covers the following aspects:

• Origin and history of UCS as a Linux distribution derived from Debian GNU/Linux. UCS uses the same package manager and package format as Debian to distribute software packages and updates to UCS.
• Identity management is the most important functional pillar of UCS. Administrators complete daily tasks around user identity management more efficient with the help of UCS.
• Connection to the world around, because administrators and users interact with UCS through web with the Univention Management Console (UMC) and services through various protocols like HTTP, LDAP, DHCP, DNS, SMTP and IMAP.
• Readers learn about the fundamental concepts that characterize UCS, like domains, user identity replication, computer system roles, user permissions and security certificates.

Publish when ready: Our iterative writing process experiment

We decided to use an iterative approach to the writing process for several reasons:

• We publish content as soon as it is available to support onboarding of new team members at Univention and new channel partners. If you are interested in a new challenge, see our vacancies.
• We split the necessary work into smaller chunks and publish them instead of depending on the project to complete. We adhere to one important open source software principle: Release early, release often as made popular by Eric S. Raymond in his 1997 essay The Cathedral and the Bazaar.
• We can include feedback on the published content into the next iterations.

The usual approach for writing documents like the architecture for UCS divides into several process steps like plan, write, review and publish. Unfortunately, the resulting content needs quite some time until publication when the document goes through the all steps as a whole. Potential readers can’t benefit from the content until the project completes. This approach is similar to the waterfall model in software development.

For agile software development we use the Kanban framework at Univention to work in self-organizing and cross-functional teams, and to use adaptive planning and continual improvement. Why not applying the same principles from software development to create product documentation?

With the UCS architecture documentation we experiment with a different approach and at the same time deliver reviewed content early. Before the project started, we already automated the publish step, because it also applies to other Univention documentation. At the beginning of the project we planned the structure of the whole document. With the automation we can repeat the publish step as often as needed without additional work time.

The steps write and review include the work on the content that generate benefit to the reader. They belong together. But how can we deliver benefit to the reader earlier? We looked at the audiences and the planned content. We decided to divide the content into chunks matching the different audiences, so that each iteration delivers benefit to another audience of the document.

Next iteration: UCS product components and services described for administrators and solution architects

We planned two additional detail levels for the document. The second detail level will focus on administrators and solution architects. It will cover the UCS product components and the numerous services UCS offers to IT infrastructures. The third detail level will address software developers and system engineers and will cover the software libraries, internal systems and storage.

With the increasing detail level, the knowledge needed by readers will also change from information technology in general, building blocks for computer networks and software to Linux operating systems and their administration to knowledge about software architecture and software engineering.

As soon as we publish more content, you can find the announcement in this blog and on our communication channels. You can be curious about what is still to come for you.

Your feedback to the UCS architecture documentation is welcome and highly appreciated. If you have comments, suggestions, or criticism, send us your feedback, so that we can improve the document in one of the next iterations. Thank you.