Live data from Hacker News

Architecture.md

matklad.github.io

81–90 of 159 posts

Re: Architecture.md

#81

Earlier quoted context omitted.

Critical outcomes are defined by quality objectives (I mentioned some above, others are reliability, robustness and portability). People don't consider using my project. There's a client with a business problem, there's a vendor who solves problems for clients. The vendor produces an architecture document that describes how technology will achieve a solution †. There is no noping the fuck out, as this is a hospital a…

> Or an electoral district asking you to merge three emergency response systems into one. Or Nokia asking you to tariff calls going through a switch in real time. I’m well aware of what it is. I’ve been on real time telecom stuff (your last example) and know for a fact that engineers nope the fuck out of these huge ass architecture documents that include stakeholders, change control, etc. Inevitably there is some kin…

The people using my system never skim my document. Lawyers tend to scrutinize it. As for the document being a war-and-peace epic yes, this happens. Mostly because people cannot write technical documentation. The hugest system can be distilled down to a single diagram which should require no words of explanation.

By way of example - here's a conceptual design for an insurer wishing to participate in a panel of protection providers.

https://www.wittenburg.co.uk/images/consulting/conceptual_de...

If you're in this world all of it is self-evident, none of it a surprise, and you understand the flow. That document leads to other more detailed designs that each address one distinct rectangle in that image.

At some point all of this will become a specification. Again the immensity of that depends on the ability of the authors. On their ability to manage complexity, and their skill as technical writers.

Either way yes, when the wheels fall off that document becomes the truth, the one everyone goes to to settle disputes. And with a capable team it never gets to that because the documentation is succint and agreed to, and what is delivered matches what was specified.

Re: Architecture.md

#83
post #31

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…

I came to the comment section to compliment the choice of Garamond.

The web would look much more beautiful with proper justification. It's a pity technology is not there yet. TeX solved the problem for DVI/PDFs long ago, so maybe we should start blogging on PDFs!

Re: Architecture.md

#84
> Do not directly link them (links go stale).

This seems pretty easily fixed by appropriate linting which includes link checking. Perhaps it's overkill, but personally I like to validate anything I can automatically so I try to validate syntax and links in Markdown documents in my projects.

Re: Architecture.md

#85
I actually agree from my experience working with complex implementations of web analytics architecture in Adobe Launch. Especially the fact that nearly every rule (tags are called rules there) can contain custom JS code makes it sometimes hard to know when a specific change to the data happened between the data layer in the DOM and the tracking request being sent to the Adobe endpoint.

I had a client with custom code shortly below 7k LOC.

Split into many different rules.

To make a long story short: Now that I know the map (the architecture) I can find my way quite fast and am currently in the process of simplifying things as far as possible.

Re: Architecture.md

#86
post #2

Ah, we actually have one of these at Caddy: https://caddyserver.com/docs/architecture (The filename on disk is literally "architecture.md" -- it is a Markdown file rendered by Caddy's template handler: https://github.com/caddyserver/website/blob/master/src/docs/... ) It could use some improvement, but it's been really great for helping people learn how Caddy 2 works at a high level. Beyond our docs, I always encourag…

Thanks for putting that out there. It's super interesting to see what we consider architecture to be. Your approach appears operational, focused on how the completed system functions, i.e. getting a new team member up to speed on the codebase. Typically I try to start with tiers (1, 2, n-tiers...?) that show how the system might be deployed. I then list list layers (user/facade/business/data), interfaces between thes…

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?

Re: Architecture.md

#87
post #47

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md (or a README if it's not too long), but it's even more dope to be able to click through it and have submaps of how other components are structured. Displaying the folder/file structure and explaining what is what is a must. An example from Diem[1]: consen…

When I first started programming, I thought the description next to the folder / file name on github was actually describing the item - as you did above, and not just the message from the last commit that altered the file. Many years later, I still believe that's how it should be.

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 Github should do the same if you have a README in your folder, describing the folder with a certain syntax, then it should extract this info and show it next to folders.

If anyone at Github is reading this, pretty please :D?

[1]: https://www.youtube.com/watch?v=XfP862hCrDM

Re: Architecture.md

#88
post #47

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md (or a README if it's not too long), but it's even more dope to be able to click through it and have submaps of how other components are structured. Displaying the folder/file structure and explaining what is what is a must. An example from Diem[1]: consen…

> Like how the fuck am I supposed to understand anything in there? By reading all the code? This is one of the superpowers of Go: for most Go projects, this is exactly what I'd do. Just read the code. It's easy to follow, it's all formatted the same, very little implicit behavior, and I don't need an IDE to do it. Few languages were designed to be read by others. Thankfully Go is one of them.

I agree that Golang has the easiest code to read, and jumping into a Golang project (even massive) is always a happy experience.

But still, you can't replace documentation.

Re: Architecture.md

#89
post #29

As someone who is in week two of spooling up on a multi-million-line codebase where most of the original authors have moved on to other projects, please, I beg you to heed this advice. I spend the vast majority of my time figuring out where a change needs to happen. The patches themselves are no more than 10% of the work. (The other significant factor is running tests.)

Well, at least it sounds like you have tests :)

Re: Architecture.md

#90

Earlier quoted context omitted.

> Like how the fuck am I supposed to understand anything in there? By reading all the code? This is one of the superpowers of Go: for most Go projects, this is exactly what I'd do. Just read the code. It's easy to follow, it's all formatted the same, very little implicit behavior, and I don't need an IDE to do it. Few languages were designed to be read by others. Thankfully Go is one of them.

> very little implicit behavior Actually I find it quite implicit the way Go structures packages. You definitely need an IDE (I use neovim + coc.nvim) to jump to a definition unless you want to grep the folder for where a struct is defined...

There's one issue I can think of, if the struct is defined in the same package then it's a bit of a pain to find which file actually defines it (in Rust you have to be explicit, each file is a module).

But that's it I believe, if it's in a different package then you'd have to explicitly write the import

Post reply on HN