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

71–80 of 159 posts

Re: Architecture.md

#71

Post by closed »

steveklabnik wrote: post #37
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…

I like this idea a lot, but you will cause a lot of people to bounce at step 2. Or at least, that has been my experience over the years. No matter how much you reassure them that it is okay if stuff is confusing and in fact you'd like to know about it so you can fix it, they'll say "great" and then go radio silent 99% of the time.

I usually reach for a friend, or someone I've met before, since using the first version of a doc is asking a lot! (And they're often part of the target audience).

Re: Architecture.md

#72

Post by systemvoltage »

xyzzy_plugh wrote: post #65
baby wrote: 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 am afraid, this doesn't quite cut the mustard. Code just can't replace a human readable Architecture diagram + explanations of whys of choices and hows of the system. Programming language doesn't replace this no matter how clear and modular it is. While Go is nice, you're vastly under-appreciating architectural documentation.

Re: Architecture.md

#73

Post by michael_j_ward »

baby wrote: 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.

Re: Architecture.md

#74

Post by systemvoltage »

There is an important aspect of writing architectural docs (or any docs for that matter) that is often overlooked.

Write simply and clearly.

Too much verbosity and detail is difficult to follow. That's what the code is for. It is almost a superpower to be able to write succinctly and clearly. This isn't some contest to showoff your deep knowledge of a particular niche. I've seen developers get 'nerdy' with their docs for a lack of a better term.

Re: Architecture.md

#75

Post by j1elo »

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…

A question can be seen as a bug reported against the documentation...

Apart from answering them, I end up converting 15% - 20% of questions into some revised content of my docs.

Re: Architecture.md

#76

Post by xyst »

Yet another piece of documentation that will be out of date in ~1 year. I have seen and read too many pieces of internal documentation that is just outdated because it’s no longer maintained or the project changed too many hands and the internal architecture deviated from the original.

I guess it’s a nice touch, especially for personal projects that get abandoned and you need to refresh your state of mind after X amount of months/years.

Re: Architecture.md

#77

Post by brailsafe »

I this is absolutely crucial for almost any project where you can't necessarily directly instruct someone on how it works. This is after having failed to contribute anything to open source projects that I do know the language of, have read the docs, and couldn't for the life of me figure out how the bits came together.

Re: Architecture.md

#78

Post by mssundaram »

xyst wrote: post #76

Yet another piece of documentation that will be out of date in ~1 year. I have seen and read too many pieces of internal documentation that is just outdated because it’s no longer maintained or the project changed too many hands and the internal architecture deviated from the original. I guess it’s a nice touch, especially for personal projects that get abandoned and you need to refresh your state of mind after X amo…

The author addresses your concern

> Additionally, the shorter it is, the less likely it will be invalidated by some future change. This is the main rule of thumb for ARCHITECTURE — specify only things which are unlikely to frequently change. Don’t try to keep it synchronized with code. Instead, revisit it a couple of times a year.

Re: Architecture.md

#80

Post by mssundaram »

xyzzy_plugh wrote: post #65
baby wrote: 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.

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

Post reply on HN