architecture_decision_record
arc42.org-site
architecture_decision_record | arc42.org-site | |
---|---|---|
22 | 16 | |
11,204 | 6 | |
- | - | |
7.7 | 8.1 | |
30 days ago | about 2 months ago | |
SCSS | ||
- | MIT License |
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.
architecture_decision_record
-
Ask HN: How to Translate Markdown Repositories?
I'm translating the Architecture Decision Record project to more languages. I'm seeking advice and guidance please: how are you all managing translations of git repos of content such as documentation and markdown files?
My experiments so far are here:
https://github.com/sixarm/locale-help
My work-in-progress is to create a top level directory `./locales`, then subdirectories per language using a ISO 639-1 two-letter language code, then content directories, for example:
./locales/en/hello/ (this is in English)
./locales/es/hola/ (this is in Español a.k.a. Spanish)
What do you use to track which content directories correspond to each other across languages?
The Architecture Decision Record repo is now mostly auto-translated into Spanish, French, Welsh, and Korean, in the top level directory `./locales`, using the program `slug-case` to help translate the markdown content file headlines into directory names:
https://github.com/joelparkerhenderson/architecture-decision-record
-
Show HN: Architecture Decision Record – Spanish Tranlsations
Link is https://github.com/joelparkerhenderson/architecture-decision...
-
Architecture diagrams enable better conversations
Hi, article author here, we supplement our architecture diagrams with Architectural Decision Records (ADRs) https://github.com/joelparkerhenderson/architecture-decision... in the ADR we capture:
-
Documenting your decisions using the ADR approach
Architecture decision record by joelparkerhenderson
-
Polar v1.0: Let’s Fix Open Source Funding
If anyone wants to see Polar in action on a GitHub issue, I'm experimenting with Polar on my Architecture Decision Record repo:
https://github.com/joelparkerhenderson/architecture-decision...
(I'm on the fence about the value of Polar for this kind of issue... see what you think)
-
How did you acquire confidence in system design?
This method is only slightly formalized as ADR (architecture decision record). What I personally like about templates that people share on the interned (https://github.com/joelparkerhenderson/architecture-decision-record) it that if force designed to actually consider cons of selected approach or honestly attempt to analyze alternatives.
-
A practical overview on Architecture Decision Records (ADR)
The GitHub repo joelparkerhenderson/architecture-decision-record is a good source to get an overview of tools, articles and examples.
-
Ask HN: How to do Git successors, in case of death?
GitHub is prompting me to add a git successor to my open source repo, in case I die.
Do people here have advice about how to do this, or experience in doing it?
Any brainstorms about how to do it across all the related repos, orgs, etc., such as a will, or well-known file in the repo, that donates to a nonprofit, or foundation, etc.?
Here's the repo:
https://github.com/joelparkerhenderson/architecture-decision-record
-
A Simple Framework for Architectural Decisions
Architecture Decision Records are a big help for teamwork. I have a bunch of notes and examples here, including from my time at ThoughtWorks with technology radars.
https://github.com/joelparkerhenderson/architecture-decision...
-
Documenting agreements
If you want to get started with ADR, I recommend looking at the repository, where you can find different ADR templates and examples of how to use them.
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
What are some alternatives?
backstage - Backstage is an open platform for building developer portals
diataxis-documentation-framework - A systematic approach to creating better documentation.
oasis-core - Performant and Confidentiality-Preserving Smart Contracts + Blockchains
jgmd - A directory of direct links to get your personal data from web services.
danger-js - ⚠️ Stop saying "you forgot to …" in code review
c4-notation - Technical resources for using the C4 model for visualizing software architecture.
rfcs - Specifications for Interledger and related protocols
architecture-decision
java - Structurizr for Java
log4brains - ✍️ Log and publish your architecture decisions (ADR)
swagger-ui - Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.