I just made one of these.
What a good idea.
Architecture.md
151–159 of 159 posts
Re: Architecture.md
#152Thanks for the prompt – we had a rough version of this at Outline in the README but I've gone ahead and pulled it into it's own document with a pointer from the README and fleshed out the docs:
https://github.com/outline/outline/blob/main/ARCHITECTURE.md
Re: Architecture.md
#153I find it useful to include an architecture diagram in the README for small projects, and the best way is to use the VSCode DrawIO extension. You can directly edit .drawio.svg files and embed them into the README. You get live editing and up-to-date images at the same time!
I recently used plantuml to sketch out a component diagram. Drawing via code is even more convenient
I've been recently using pic to draw any kind of images for documentation purposes.
Pic is a language Brian Kernighan created for troff toolchain. It's very versatile and has macros, even! Manual: https://pikchr.org/home/uv/pic.pdf
Contemporary implementations (pic2plot, dpic, pikchr) can output SVG so the results look very nice and are repository-friendly and diff-friendly to some extent.
I've bolted it to Emacs for "interactive" editing: https://iki.fi/newcup/cons-trained/2021-02-03-neat,-simple-v...
Re: Architecture.md
#154Earlier quoted context omitted.
I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Documentation in the source is different from a directory organization documentation IMO. Rust has a lot of tools to write good documentation in source, and it is here to help produce good documentation for users of a library, not to explain how to contribute to the code or understand how…
> I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Of course one can see the files. But I rarely deal with "files" in my IDE, I deal with packages/namespaces/modules/functions/classes/methods. The natural place to put architecture documentation would therefore be the top-level code unit (e.g. package/module/namespace), to which one can…
I still don't think this is a good idea, after having worked a lot with Golang and Rust doc, the documentation generated from comments is targeted to users of the library, not contributors.
(And Rust/Golang have the best documentation system out there of any language I have ever seen).
For example, documentation in Golang does not follow your file structure, it just pulls up any public API comment and displays it. It makes sense, why would I care about how these functionalities are implemented and architected as a user?
Second point: a system has different types of languages and ways to organize things, so it’s not always clear where to look for doc. Whereas a README is always obvious.
Re: Architecture.md
#155Earlier quoted context omitted.
> I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE? Of course one can see the files. But I rarely deal with "files" in my IDE, I deal with packages/namespaces/modules/functions/classes/methods. The natural place to put architecture documentation would therefore be the top-level code unit (e.g. package/module/namespace), to which one can…
100% agree. A very good implementation of your ideas can be found in the Redis codebase. Most important files have a long doc comment in the beginning. See https://github.com/redis/redis/blob/unstable/src/ziplist.c for an example.
your example is a comment of the code/implementation, related to the actual file, not to the architecture
Re: Architecture.md
#156Asking to clarify
> Nothing in the model layer specifically doesn’t depend on the views.
is there a typo or this is intentional?
Re: Architecture.md
#157Earlier quoted context omitted.
Your approach seems like it would reduce the likelihood of implementation-time surprises. It also seems like different sections would satisfy different audiences. Do you have any book recommendations?
I do indeed. Here's a complete list of books I recommend when asked - https://www.wittenburg.co.uk/Work/Books.aspx The one that made the biggest impact on my approach to architecture is "Designing Solutions for Your Business Problems: A Structured Process for Managers and Consultants" by Betty Vandenbosch. The one that made the biggest impact on me in ever is "Wicked Problems, Righteous Solutions" by Peter DeGrace an…
Thank you for the book recommends
Also i read your home > work articles
They are excellent
Re: Architecture.md
#158Really good point. In my first job, I spent quite sometimes to figured out where I need to change the code.
Re: Architecture.md
#159Earlier quoted context omitted.
Agree! I gave that feedback many times, who cares about commit message? I want documentation here! I think Github should really start taking a stance on convention, and come up with project structure conventions that would help project navigation. For example, youtube does that with chapters in videos, if you write a description with timestamps it will display these chapters in the timeline of the video[1]. IMO Githu…
This makes me think we should be able to put something like a standard tag for a 1-line summary (maybe embedded in some markdown in a comment) in a fashion the VCS's can detect & extract and then render in their UXs. e.g. something very simple would probably work like the first line found that matches something like: [Ignore_Non_Words]Summary[IgnorePunctuation&Spaces](Capture)
I think you could get a lot of mileage from using existing formats in code and comments.
So for instance, if save_parser.py starts with
""" Parse content loaded from save files
...
"""
//! List of data structures necessary for maths operations
//!
//! ...
src
├── save_parser.py # Parse content loaded from save files
├── math_backend.rs # List of data structures necessary for maths operations