Project Proposal

[AlannaBurke]

Proposal Title

Overhaul Lagoon Technical Diagrams

About your organization

Lagoon is an open-source application delivery platform for Kubernetes. Lagoon allows developers to locally develop their code and their services with Docker and run the exact same system in production - the same container images, the same service configurations and the same code. Its primary focus is as a cloud-native tool for the deployment, management, security and operation of many applications. Lagoon greatly reduces the requirement on developers of those applications to have cloud-native experience or knowledge.

Lagoon was originally created and open sourced by the team at amazee.io in August 2017, and powers their global hosting platform.

Lagoon is largely maintained by the Lagoon team, who are employed by amazee.io, along with a handful of outside contributors. Our community has been slowly growing over the past few years, and we have seen increased adoption of Lagoon.

Your project's problem

As an open-source project, we aim to have the most comprehensive documentation possible for users, administrators, developers, and contributors. We have a variety of technical diagrams that are currently out of date and very difficult to update and publish. Having up-to-date and easy to update diagrams will make it much easier to understand the architecture of the Lagoon project, which is essential for many personas interacting with Lagoon. For example, a new contributor to the project benefits from being able to have a visual representation of all of Lagoon’s components and how they interact.

Your project's scope

This project will:

• Evaluate potential solutions for creating and updating technical diagrams. In our introductory research, we think Structurizr, mermaid.js or draw.io might be good solutions, but we’d like to work with a technical writer who has experience with diagramming and can help choose the most appropriate solution for the project.
• Work with the Lagoon maintainers to recreate and update our infrastructure, architecture and process-flow technical diagrams with the chosen solution.
• We have identified several documents that need to be created:
  • High level overview of Lagoon core/remote services and their interactions/links
  • Flow diagram of the build/deploy process
  • lagoon-core architecture - detailing microservices and their interactions
  • lagoon-remote architecture - detailing microservices and their interactions
  • lagoon-core <> lagoon-remote communications and process flow
  • additional component integration - Harbor, OpenSearch, k8up, Prometheus
  • Lagoon deployment scenarios - combined core & remote, separate core & remote, separate core & multi-remotes
• Document the process of updating and maintaining the new diagrams.

We have not yet identified potential technical writers for this project. The chosen technical writer will work with Alanna Burke, documentation writer for the Lagoon project, and Toby Bellwood, product owner.

Measuring your project's success

Lagoon is a complex project with a lot of moving parts, and it’s essential to the project to have an up-to-date technical diagram to give a visual explanation of how all of the various parts connect and interact.

Questions about Lagoon are fielded by the Lagoon team, mostly in the community Discord. Many questions could be answered or avoided altogether by having robust diagrams explaining how the system works and how the moving parts interact. Our goal in this project is to see a decrease in questions related to the overall functionality and architecture of the Lagoon project. We will track how many questions are asked per week, how many could be answered with updated technical diagrams, and continue to track after the diagrams are completed, published, and promoted to the community, ideally seeing a decrease in those questions.

Timeline

Duration	Action Items
16 hours	Orientation
24 hours	Evaluate potential solutions
104 hours	Create technical diagrams
16 hours	Document update process
160	TOTAL

Project budget

Budget Item	Hours	Hourly Rate	Amount
Technical writer to evaluate solutions, create diagrams, and document the update process.	160	$50	$8000
TOTAL	-	-	$8000

Required skills

Creating, updating, and maintaining complex technical architecture and infrastructure diagrams in a system like Structurizr, mermaid.js, draw.io, etc. The first phase of this project will require analyzing potential solutions and presenting the best options for the project.

[yashpandey06]

Hey, @AlannaBurke ! The project idea seems interesting. I've gone through the entire repository, including its docs, and I'm really interested in finding a way to facilitate transparent communication. Could you please guide me on where I can send my brief introduction?

[AlannaBurke]

#3699

[AlannaBurke]

Update - our project was not selected, so i'll be closing this discussion and we'll try again net year!