arc42.org-site
backstage
Our great sponsors
arc42.org-site | backstage | |
---|---|---|
16 | 125 | |
6 | 26,317 | |
- | 2.3% | |
8.1 | 10.0 | |
about 1 month ago | 6 days ago | |
SCSS | TypeScript | |
MIT License | Apache License 2.0 |
Stars - the number of stars that a project has on GitHub. Growth - month over month growth in stars.
Activity is a relative number indicating how actively a project is being developed. Recent commits have higher weight than older ones.
For example, an activity of 9.0 indicates that a project is amongst the top 10% of the most actively developed projects that we are tracking.
arc42.org-site
-
A View on Functional Software Architecture
There a various standards for documenting software architecture, like arc42 or C4. While useful and somewhat well-known (there is certainly a correlation here), here architecture documentation can be further simplified, particularly due to the self-similarity of project and component. Following is a small template, that can also serve as a project's and component's README:
-
Architecture diagrams enable better conversations
I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/. It's very easy to embed a C4 diagram into a markdown document.
The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (for interactive diagrams and indexed search).
I also use https://d2lang.com/ for declarative diagrams in addition to C4, e.g., sequence diagrams and https://adr.github.io/ for architectural decision records. These are also well integrated into structurizr.
-
Documenting a software project
My general approach to documentation is a "software guidebook" (free e-book link) or arc42 ... complemented with diagrams and architecture decision records where necessary.
-
System Design How to?
In addition to a small number of diagrams, I'd recommend something like arc42 or my "software guidebook" (link for a free copy of my book describing this), plus some architecture decision records.
-
Solution Templates
Arc42 may give some inspiration https://arc42.org/
-
What's your process to create documentation for a new startup's application?
If you need more structure than ADRs then https://arc42.org is super useful.
-
Recommendations for an Online Introduction to Software Modeling
There are plenty of good resources out there for learning modeling languages and architectural documentation structures. For more lightweight methods, I'd recommend checking out resources like Simon Brown's C4 model for visualizing software architecture, Martin Fowler's UML Distilled: A Brief Guide to the Standard Object Modeling Language, Scott Ambler's Agile Modeling site, and the arc42 template for architectural documentation.
-
How to get good at writing design documents?
As you need to, you can get into topics like different modeling languages or documentation template libraries. These are going to be highly dependent on your organization, though, as different organizations have different standards for what and how to document design decisions. Personally, I've found that the arc42 documentation template plus the C4 modeling language plus the UML modeling language (see UML as sketch and UML as notes for more on lightweight UML) for the most detailed models (which are rarely needed outside of the most complex parts of a system) tends to be a good, agile, lightweight model for the kinds of things to think about when it comes to creating design documentation.
-
How to improve writing documentation?
We've started using Arc42 and C4 model & PlantUML for diagrams. Working out well so far.
-
About documentation
arc42 - arc42
backstage
-
# Enable Developers on SAP BTP with Terraform, GitHub Actions and Backstage
apiVersion: scaffolder.backstage.io/v1beta3 # https://backstage.io/docs/features/software-catalog/descriptor-format#kind-template kind: Template metadata: name: sample-btpsubaccount-remote-template title: Remote Template for SAP BTP Subaccount Setup description: A remote template that creates a basic SAP BTP Subaccount setup tags: - sap - btp - basic - javascript spec: owner: user:guest type: service
-
APIMatic SDKs in Backstage Developer Portal
Backstage is an open-source platform developed by Spotify for managing the entire lifecycle of developer infrastructure, including services, APIs, documentation, and more. Backstage streamlines the development process through its centralized and customizable platform, offering a unified dashboard that consolidates information on projects, services, and infrastructure. Acting as a service catalog enhances transparency by allowing teams to document and discover internal services easily. Backstage's extensible architecture supports a robust plugin ecosystem, enabling teams to tailor the platform to their specific workflows and preferences. The platform promotes collaboration, accelerates onboarding through standardized documentation, and integrates seamlessly with various DevOps tools.
-
The 2024 Web Hosting Report
It’s also well understood that having a k8s cluster is not enough to make developers able to host their services - you need a devops team to work with them, using tools like delivery pipelines, Helm, kustomize, infra as code, service mesh, ingress, secrets management, key management - the list goes on! Developer Portals like Backstage, Port and Cortex have started to emerge to help manage some of this complexity.
-
Ask HN: How do you organize software documentation at work?
We use Confluence and markdown files in GitHub. I think we are moving a lot of our docs to Backstage [0] soon.
One process that ends up being really valuable for documentation purposes is our "Architecture Review Documents". This is a standard document that team leads fill out before starting work on a new Saga/Epic/Feature/whatever. It includes the scope and business value of a new feature or large block of work, high level technical architecture of implementation, the impact on existing database schemas and service APIs, etc. This document is presented in a meeting with technical leadership in our organization who deep dive on the topic and explore potential pitfalls in the plan.
The document and recording of that meeting live on forever, and this information is very useful when getting acquainted with a certain part of our product/codebase. You are able to read and hear clearly the intention of a certain service or module, and you can identify several relevant points of contact to ask questions to.
[0] https://backstage.io/
-
Tools used by the top 1% of Platform Engineers and their Commercial Open Source Alternatives
Check the Backstage repo on GitHub
-
10 open source tools that platform, SRE and DevOps engineers should consider in 2024.
Backstage - An open platform for building developer portals. [Internal Developer Portal]
- Backstage: An open platform for building developer portals
-
Champion Building - How to successfully adopt a developer tool
So you've just bought a new platform tool? Maybe it's Hashicorp Vault? Snyk? Backstage? You’re excited about all of the developer experience, security and other benefits you're about to unleash on your company—right? But wait…
- Terraform Self-Service platform / Internal Developer Platform solutions
-
Developer productivity for fun and profit - Part 2
The idea is to have a central point where people can find standards, documentation, and designs. The team can do this with a specialized tool like Backstage, Confluence, Github, Google Docs, or some internal implementation. The software is not the most important thing here, but having an easy way to find what is needed for the person to be more productive.
What are some alternatives?
diataxis-documentation-framework - A systematic approach to creating better documentation.
cookiecutter - A cross-platform command-line utility that creates projects from cookiecutters (project templates), e.g. Python package projects, C projects.
jgmd - A directory of direct links to get your personal data from web services.
atlantis - Terraform Pull Request Automation
c4-notation - Technical resources for using the C4 model for visualizing software architecture.
api-management-developer-portal - Developer portal provided by the Azure API Management service.
architecture_decision_record - Architecture decision record (ADR) examples for software planning, IT leadership, and template documentation
C4-PlantUML - C4-PlantUML combines the benefits of PlantUML and the C4 model for providing a simple way of describing and communicate software architectures
architecture-decision
gitops-flux-helm
java - Structurizr for Java
Clutch - Fast iOS executable dumper