Any word on supporting diagrams inside GitHub flavored markdown?
I always just use ASCII art in code blocks.
Same here, simple works. I use this tool to help http://asciiflow.com/
Architecture.md
11–20 of 159 posts
Re: Architecture.md
#12The k8s project did this very well in the early days with their design docs. It made the codebase much more accessible than it ordinarily should have been. There are few projects that do this and I wish the JavaScript projects did this a lot more.
If anyone knows of other open source projects that do this, it would be particularly useful.
Re: Architecture.md
#13I would encourage people to have one ARCHITECTURE file per directory of source code files. Don't duplicate documentation in these files - if there is a well documented header file for some module, just link to that.
In a big project, when I'm hunting for code that does something and I have no familiarity of the codebase, I want to be able to follow a chain of ARCHITECTURE documents from the root of the project to the implementation of the feature I'm looking for.
If your documentation is poor enough that I resort to finding a string used in the feature and grepping the whole source tree for it, then your codebase will be tricky for someone new to get started on.
Re: Architecture.md
#14Any word on supporting diagrams inside GitHub flavored markdown?
I tend to prefer diagrams as code, so yoi can just embed an image that be updated, version controlled, etc, instead of ascii diagrams. Any reason in particular you want ascii instead of images?
Re: Architecture.md
#15Any word on supporting diagrams inside GitHub flavored markdown?
Looks like there is an open feature request on GitHub for supporting Mermaid charts: https://github.community/t/feature-request-support-mermaid-m...
Re: Architecture.md
#16I like the idea. I may do it for some (not all) of my projects.
Re: Architecture.md
#17So one thing we've done is write all of our applications the exact same way with well defined terms (on a wiki) and a commitment to no more than 4 layers.
* Initiators (things that receive, decode, and validate input)
* Controllers (Business logic containers. One function refers to one business action)
* Services (Used by controllers to effectuate commands. Services absolutely cannot call other services)
* Cross Cutting concerns (Common model objects, logging, top level error handling, etc)
This allows even a new person to pick up a project and orient themselves immediately.
Re: Architecture.md
#18I love architecture docs, but find they're often written using a funny process:
1. Spend a long time writing the doc.
2. Wait for a person to chance upon it.
3. Hope you anticipated their questions.
1. Say who the doc is for.
2. Find that person. Ask them to try a lil contribution.
3. Frantically write / revise the doc.
Re: Architecture.md
#19I've started doing this in my larger projects e.g. https://github.com/kstenerud/go-concise-encoding/blob/master...
An architecture document should be the code equivalent of a combined street map and tourist guide. Its purpose is to bring strangers up to a minimum level of familiarity with the code as quickly as possible. That includes where things are, why it was architected this way, things to look out for, and a few interesting points of weirdness perhaps.
Re: Architecture.md
#20So one thing we've done is write all of our applications the exact same way with well defined terms (on a wiki) and a commitment to no more than 4 layers. * Initiators (things that receive, decode, and validate input) * Controllers (Business logic containers. One function refers to one business action) * Services (Used by controllers to effectuate commands. Services absolutely cannot call other services) * Cross Cutt…
Why shouldn't a service call other services? One Service may extend the features e.g. network < encryption < http.