Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Architecture.md

matklad.github.io

Post reply on HN
Print view View original

141–150 of 159 posts

Re: Architecture.md

#141

Post by rapnie »

closed wrote: post #18

I 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. It seems like the most important thing a person can do is reverse this: 1. Say who the doc is for. 2. Find that person. Ask them to try a lil contribution. 3. Frantically write / revise the doc. IMO it's a lot like creati…

This is also the idea behind Readme Driven Development. See https://news.ycombinator.com/item?id=25222601

Re: Architecture.md

#142

Post by austincheney »

runeks wrote: post #137
austincheney wrote: post #97

My approach: 1. put a one line comment at the top of each code file. 2. The build extracts that comment and dynamically updates a readme.md for the directory that describes each code file. 3. The build also produces a master document that includes the same summaries in a single document. This provides a light indication of what each code file is and how they are organized into directories. It doesn’t provide any indi…

Interesting approach. Do you have an example repo?

https://github.com/prettydiff/share-file-systems

Re: Architecture.md

#144

Post by crabmusket »

Xunjin wrote: post #57

I read the title at HN and I was like "okay seems interesting" then I saw "matklad" and went "Holy shit, must be great stuff". I know I will sound another Rust evangelist, but people this person is the main maintainer of RA (Rust-analyzer), a LSP protocol implementation, anyone who tried RLS (Rust Language Server) then RA knows how great this tool helps you at learning and developing stuff with Rust. I use the nightl…

You've convinced me to chuck Matklad's RSS feed into my reader :)

Re: Architecture.md

#145

Post by crabmusket »

DyslexicAtheist wrote: post #5

what they suggest is very similar to Architecture Decision Records (ADR's). https://adr.github.io/ TL;DR: ADR's are a design choice for a lightweight process to store and manage the history over what architecture decisions have been made in the past and why. They should be tracked within git so that the history of decisions and how these evolved is provided for free . Just track all this within an `adr/` subdirectory…

It seems like ADRs are the deltas of architecture.md: they describe how it has changed over time. It's useful to have one document which just describes things as they are, but it's also great to preserve the history of how things came to be that way.

Re: Architecture.md

#146

Post by matklad »

matklad wrote: post #31
gorgoiler wrote: post #22

This is predictably unrelated but how can someone go to the effort of having such beautiful typeface selection and still have an unhyphenated ragged right? Great advice though, otherwise.

Yeah, I indeed spend some effort to steal the fonts from asciidoctor and https://www.teamten.com/lawrence/programming/ (highly recommend both). And yes, I myself am struggling with ragged right. I really wish to have proper text hyphenation and justification, to have a book-like feel. Sadly, justification without hyphenation looks ugly, and `hyphens: auto` doesn’t work well (and wasn’t supported in chrome last time I…

Actually, chrome added support for `hypthen: auto` not so long ago!

Re: Architecture.md

#147

Post by jlg23 »

baby wrote: post #109
jlg23 wrote: post #91

Earlier quoted context omitted.

This will help people browsing code in github, but folks browsing code in their IDE will most likely be lost, as the documentation you advice to put into "README.md"s should, IMHO, be in the module/package documentation in the source. One can still link to those from the global README.md

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 easily navigate when viewing docs.

> Documentation in the source is different from a directory organization documentation.

Is it, given that directories tend to be organized around code units (again: packages/namespaces/modules/classes)? It is thinkable to store code in databases (see Dylan's IDE, either implemented or it was on the roadmap, I don't remember) and all the architecture documentation not directly attached to semantic units of your code would be lost.

Re: Architecture.md

#148

Post by tejohnso »

FourthProtocol wrote: post #138
tejohnso wrote: post #86

Earlier 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.

Re: Architecture.md

#149

Post by hashhar »

jlg23 wrote: post #147
baby wrote: post #109

Earlier 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…

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.

Re: Architecture.md

#150

Post by pc86 »

If you're going to do this, you're probably going to use images. If you're going to use images, please keep in mind that GitHub now has a dark mode, so black text on a transparent background is almost entirely unreadable. Here's what the first image in the example document looks like in the markdown file, compared to the actual image: https://imgur.com/a/k2KWB57
Post reply on HN