Architecture.md • Hacker News Board

Re: Architecture.md

#21

Post by syoc » Sat, Feb 06, 2021, 8:10 PM UTC

I really like this DESIGN.md[1]. Might not be as code specific as what tfa is talking. I find design decisions really helpful when evaluating if a tool or solution is useful for my needs. Especially if it elaborates on priorities made in the project.

[1] https://github.com/google/stenographer/blob/master/DESIGN.md

Re: Architecture.md

#22

Post by gorgoiler » Sat, Feb 06, 2021, 8:16 PM UTC

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.

Re: Architecture.md

#23

Post by kondu » Sat, Feb 06, 2021, 8:16 PM UTC

londons_explore wrote: post #13

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

That sounds a bit excessive. If your project is going through a lot of changes and refactoring, the multiple architecture.md files will be hard to keep up-to-date

Re: Architecture.md

#24

Post by jhund » Sat, Feb 06, 2021, 8:18 PM UTC

harikb wrote: post #6

Any word on supporting diagrams inside GitHub flavored markdown?

I've started using draw.io [1] for diagrams I want to embed in markdown files. The cool feature about draw.io is that it can embed the data structure describing the diagram in a png file. So you get a PNG file that is both source code for your diagram (so you can edit it later), as well as the presentation (you can embed png files and they will render fine in Github hosted md files).

Then I use the markdown-images package [2] for Sublime Text, and I can see those png images in my markdown files in the editor as well.

Benefits of this approach:

* Powerful diagram editor, free to use.

* Editable diagram and embedable image in one file.

* Diagrams rendered in text editor.

[1] https://github.com/jgraph/drawio-desktop

[2] https://packagecontrol.io/packages/Markdown%20Images

Re: Architecture.md

#25

Post by andrewflnr » Sat, Feb 06, 2021, 8:19 PM UTC

londons_explore wrote: post #13

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

Disagree. If I have a question about the architecture, I don't want to go hunting through your directory hierarchy for the right doc file if I don't have to. Not saying you shouldn't have some kind of design doc in each directory, but I'd say it's more important to have a single roadmap than lots of little interlinked ones. If links were enough, I would just read the code.

Re: Architecture.md

#26

Post by gjvr » Sat, Feb 06, 2021, 8:22 PM UTC

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…

Yep, feedback is valuable. And the earlier the more valuable (it's like NPV...).

I love coding so much, and find it really hard to express ideas in natural language, so that in the end documentation... doesn't happen as much as it should.

What I find that really helps is the following:

1. Write down architecture specs (with interface specs etc), before coding. Not bloated, but really minimalistic. 2. Review these ideas with peers. 3. Happy coding and refine the docs.

Re: Architecture.md

#27

Post by bezout » Sat, Feb 06, 2021, 8:26 PM UTC

Absolutely, I was just thinking about adding a similar document to my new project. Apart from contributors, it also benefits casual visitors who just want to browse around.

Re: Architecture.md

#28

Post by _hl_ » Sat, Feb 06, 2021, 8:27 PM UTC

ibraheemdev wrote: post #3

The specific rust-analyzer architecture document the author refers to was discussed here a couple days ago: https://news.ycombinator.com/item?id=26026309

I think it's funny how the blog post is essentially an architecture documentation of the rust analyzer's architecture documentation.

Re: Architecture.md

#29

Post by utborin » Sat, Feb 06, 2021, 8:29 PM UTC

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

Re: Architecture.md

#30

Post by notafraudster » Sat, Feb 06, 2021, 8:39 PM UTC

Even on relatively small projects (1k-10k LOC), I incorporate this, broadly, into my README file for my repo: what are the various use cases, which components do what, in one sentence what are the main functions contained in each of the source files, sometimes a flow diagram showing which functions call which other functions.