Identifiers are for look-up. Names are for search.

We know from the principles of the world-wide web that every URL identifies a specific entity. It's fairly apparent that "https://ebank.com/accounts/a49a9762-3790-4b4f-adbf-4577a35b1df7" is the URL of a specific bank account. Whenever I use this URL, now or in the future, it will always refer to the same bank account. You might be tempted to think that 'https://library.com/shelves/american-literature/books/moby-dick' is the URL of a specific book. If you think renaming and relocating books could never make sense in a library API, even hypothetically, then you can perhaps defend that point of view, but otherwise you have to think of this URL differently. When I use this URL today, it refers to a specific, dog-eared copy of Moby Dick that is currently on the American Literature shelf. Tomorrow, if the book or shelf is moved or renamed, it may refer to a shiny new copy that replaced the old one, or to no book at all. This shows that the second URL isn’t the URL of a specific book — it must be the URL of something else. You should think of it as the URL of a search result. Specifically, the result of this search:

find the book that is [currently] named "moby-dick", and is [currently] on the shelf that is [currently] named "american-literature"

Here’s another URL for the same search result, where the difference is entirely one of URL style, not meaning:

https://library.com/search?kind=book&name=moby-dick&shelf=(name=american-literature)

Understanding that URLs based on hierarchical names are actually the URLs of search results rather than the URLs of the entities in those search results is a key idea that helps explain the difference between naming and identity.

Martin Nally, in API design: Choosing between names and identifiers in URLs.

The use of diagrams and flow charts

The flow chart is a most thoroughly oversold piece of program documentation. Many programs don't need flow charts at all; few programs need more than a one-page flow chart.

Flow charts show the decision structure of a program, which is only one aspect of its structure. They show decision structure rather elegantly when the flow chart is on one page, but the overview breaks down badly when one has multiple pages, sewed together with numbered exits and connectors.

The one-page flow chart for a substantial program becomes essentially a diagram of program structure, and of phases or steps. As such it is very handy.

Frederick P. Brooks, Jr., "The Other Face", in The Mythical Man-Month (Anniversary Ed.), 167-168.

Had I not been writing a book, I would have draw these diagrams by hand on a scrap of paper or a whiteboard. I would not have taken the time to use a drawing tool. There are no circunstances that I know of where using a drawing tool is faster than a napkin.

Having used the diagrams to help me evolve the code, I would not have kept the diagrams. In every case, the ones I drew for myself were intermediate steps.

Is there value in keeping diagrams at this level of detail? Clearly, if you are trying to expose your reasoning, as I am doing in this book, they come in pretty handy. But usually we are not trying to document the evolutionary path of a few hours of coding. Usually, these diagrams are transient and are better thrown away. At this level of detail, the code is generally good enough to act as its own documentation. At higher levels, that is not always true.

Robert C. Martin, "Observer - Backing into a Pattern", in Agile Software
Development: Principles, Patterns, and Practices, 315.

Diagrams are a means of communication and explanation, and they facilitate brainstorming. They serve these ends best if they are minimal. Comprehensive diagrams of the entire object model fail to communicate or explain; they overwhelm the reader with detail and they lack meaning. This leads us away from the all-encompassing object model diagram, or even the all-encompassing database repository of UML. It leads us toward simplified diagrams of conceptually important parts of the object model that are essential to understanding the design.

The vital detail about the design is captured in the code. A well-written implementation should be transparent, revealing the model underlying it. Supplemental diagrams and documents can guide people's attention to the central points. Natural language discussion can fill in the nuances of meaning. This is why I prefer to turn things inside out from the way a typical UML diagram handles them. Rather than a diagram annotated with text, I write a text document illustrated with selective and simplified diagrams.

Always remember that the model is not the diagram.

Eric Evans, "Communication and the Use of Language", in Domain-Driven Design: Tackling Complexity in the Heart of Software, 36-37.