Ask HN: Is there a better way to document complex software architectures? - <AUTHOR> Despite having the 'architect' title for about five years now, I still sit for hours in Visio & Powerpoint to painstakingly drag boxes and lines around to describe systems.
While the system definitions themselves have arguably improved as my skill as an architect has increased, there's been no such improvement in the speed or method I use to describe them. My visuals are perfunctory, powerpoint-fu is lacking, and the end result always has plenty of room for improvement. It then gets saved as PDF and shelved as an artefact that is disconnected from all the other architectures, and the system boundaries are inevitably out of date by the time the next person looks at it.
So much craft has been put into better languages, better compilers, and better IDEs for the software developer, I'm absolutely confused - where is the modern 'IDE' for the Software Architect? <comment><USER2> Quick question that I only ask because of my 30-odd year history as a corporate contractor...

Does anyone here really use those UML-based docs to actually learn the systems? Or do they do what I always did and use the trusty step-debugger for a few days and come up with your own mental model of them?

Inevitably, unless someone is working full time on them, they are incomplete and several months out-of-date, and that makes them worthless really.

That's my anecdotal evidence against generating them. I'm at least somewhat sure someone has a conflicting story of how UML "saved the day", but it would be so rare to my experience that I would love to hear it.

<comment><USER3> I've been developing software professionally for 25 years. I've never found them to be useful. Even if you have them, they're usually out of date, and anyway they don't really help answering the questions you have. None of the places I have worked at have put a lot of emphasis on UML diagrams.

<comment><USER4> I tend to write up (not necessarily formal UML) diagrams in 2 cases:

1\. I'm brainstorming with myself about how I want the software to behave

2\. The software is basically done & tested, it's unlikely to change, and communicating the behavior to other people is of value, especially when describing a system that spans multiple components

<comment><USER5> I'll add (3) When I'm learning a new system, especially if it's big and/or old.

The idea is that if I go to the trouble to document it then the next person won't have to; this is seldom the case because as stated above the get out of date so fast. It's still a great way to learn and confirm your understanding though.

<comment><USER6> (4) Security audits

</comment></comment></comment></comment></comment><comment><USER7> "Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won't usually need your flowcharts (source code): they'll be obvious."

~ Fred Brooks, "The Mythical Man Month"

Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql), more expressive type systems e.g. rust, haskell, typescript perhaps (though I am not completely sold on typescript yet myself) nix/nixos (or more mainstream, hashicorp products/ansible/puppet/docker) kubernetes and co. (most people probably don't need)

<comment><USER8> But my domain model is

        Store
        =====
        Id int
        Col1 varchar
        Col2 varchar
        Col3 varchar
        ...
        Col134 varchar
        foreignKey1 varchar
        foreignKey1Type varchar
        foreignKey2 varchar
        foreignKey2Type varchar
        ...
        foreignKey10 varchar
        foreignKey10Type varchar
        validFrom varchar
        validTo varchar
        isActive boolean
        deleted boolean

<comment><USER9> Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.

<comment><USER10> This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.

<comment><USER11> The database was meant to be the CMS and SQL was designed to be human readable.

<comment><USER12> Counterpoint: If small design decisions require global SQL schema changes, it slows you down. And small barriers to change will, in aggregate, kill you.

Eg, over a month of iterations: "Can we add another field to user registration? It should be free text. Oh, they should select from a list. No wait, make it a date. Actually a date and a text field. No wait, dump the text field."

Sometimes slowing down these changes is a good thing. But often, being able to ship each iteration along the way will help your design team converge on the best solution. If you need to write a schema migration for every iteration, it kills the ability of your team to experiment and explore the space of "what should our product actually look like".

Faster iterations = more iterations = better product in the long term. Sometimes the best long term result requires some random stuff getting crammed into a big JSON field in your database in the short term.

<comment><USER13> Sounds like the real problem is that there's too much friction with schema migrations.

</comment></comment></comment></comment></comment></comment></comment><comment><USER14> Well, you need to use an architecture modelling tool to work [efficiently] with architecture models.

Here are some I know of:

Sparx's Enterprice Architect

NoMagic's MagicDraw

Qualiware

Achimate (the tool, not the standard)

There are surely more out there. I know both Sparx and MagicDraw have the possibility to write your own custom plugins for the tool. If you are in a big enough shop that will become very handy at some point. Qualiware have better publication options than the others, as far as I know, but not completely sure. The Archimate tool probably only supports the Archimate notation standard, where as the others support BPMN, UML, DMN etc. So I'd go for those, unless you are really heavy into TOGAF, then Archimate may make sense.

Edit: these are "big" tools that can do alot of differnet stuff and you wont ever need all of the features in one of them. But also means you need to dedicate some time to learn how to use it (alot more time than you needed to learn PP or Visio)

<comment><USER15> These recommendations are a time capsule from the 90s.

<comment><USER14> Would be interesting to hear your thoughts on whats good 2018 recommendations?

</comment></comment></comment><comment><USER16> Dia/visio for general diagrams and ArgoUML/plantUML for sequence diagrams. I found that the only useful UML diagram is the sequence diagram, that really needs a dedicated tool to draw.

PlantUML has simple text markup to describe diagram. It's easier than drawing and it can be integrated in documentation and generated on the fly (sphinx, wiki, doxygen).

And last but not least, ascii diagrams with [http://asciiflow.com/](http://asciiflow.com/) . The ASCII art diagram is the only format that can be integrated flawlessly into any email or documentation.

[https://en.wikipedia.org/wiki/ArgoUML](https://en.wikipedia.org/wiki/ArgoUML) [https://en.wikipedia.org/wiki/Dia_(software)](https://en.wikipedia.org/wiki/Dia_\(software\)) [http://plantuml.com/](http://plantuml.com/)

<comment><USER17> > The ASCII art diagram is the only format that can be integrated flawlessly > into any email or documentation.

Certain email viewers like to ... "re-format" even fixed-width plain text and thus mis-render even ASCII art (looking at you, Outlook). Of course, every time I've received such reports, I've been able to brush the problem aside by simply asking people to use a different email viewer, or view the docs in a browser proper.

<comment><USER16> I use Outlook all the time. Format the text with Courier New to have fixed width.

<comment><USER17> > Format the text with Courier New to have fixed width.

This succinctly captures a common problem with the MS ecosystem of products, from ages ago: the belief that "everybody uses MS". Yes, Courier New may be a fixed-width font, but I don't want to force the recipients of my emails to have Courier New, nor do I want the content _I 'm_ writing to show up in Courier New and Courier New alone, on someone else's computer. I want it to show in whatever font _they_ have set as their monospace font. Same goes for when I view my own mails on my own computer.

</comment></comment></comment></comment><comment><USER18> The Art of Visualising Software Architecture by Simon Brown is an interesting presentation on this topic:

[https://www.youtube.com/watch?v=zcmU- OE452k](https://www.youtube.com/watch?v=zcmU-OE452k)

He references this other talk by Adam Tornhill on a similar topic:

[https://www.youtube.com/watch?v=XzsXvsHcjc0](https://www.youtube.com/watch?v=XzsXvsHcjc0)

<comment><USER19> Along with this, Simon has developed Structurizr, which uses code to describe architecture and then visualize it at different levels:

[https://structurizr.com/](https://structurizr.com/)

</comment></comment><comment><USER20> Full disclosure: I am one of the developers of a product which does the below, also known as model driven architecture.

For about 5 years now, the teams I have been on have found great success in the use of DDD. Towards this we have used a tool which not only allows us to visually model the domain using UML, but also performs what we call "code management" (smarter code-gen which doesn't get in your way, or produce ugly code) which turns the UML into code for our ORM of choice.

All members of the team are required to use the tool and UML to create new domain entities which then automatically become (beautifully formatted) code.

The enormous advantage of this approach is that the documentation (in the form of UML in this case), never goes out of date and lives with the code, it's literally checked in to our Git repo in an SCM friendly format next to the normal code.

We are always able to talk around these visual models when planning a new feature or strategising a technical solution for a requirement.

An architect can at any time reason about the domain without having to first build up a mental model of it from code.

When juniors ask questions of seniors, they can both talk around the UML so that they quickly get clarity on the best way forward.

I would never go back to building business software any other way.

<comment><USER21> If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

<comment><USER22> I can envision two reasons. The first is that, in truth, the code generated from the UML, isn't good enough and people still actually work on the output.

The second guess is that humans occasionally rewrite the code for optimization. It might then be easier to source controll the code rather than patches.

<comment><USER23> There's also the reason of not wanting to generate all the code every single time someone new retrieves the repo or needs to revert back to a previous commit.

<comment><USER21> This reason doesn't make sense. Again, do you checkin the bytecode of your java? I'd expect you, instead, to recompile the java every time you do a build.

Now, I would expect you to have an artifact repository. To that end, you would be able to easily get the generated sources. But, they would decidedly not be in the source repository.

<comment><USER20> I don't feel the bytecode comparison makes sense, because the generated code is human readable, bytecode is (to almost all intents and purposes) not.

We feel that code generation is something one does explicitly while modelling, not something done every time you build.

</comment></comment></comment></comment></comment></comment><comment><USER24> >where is the modern 'IDE' for the Software Architect

It's the same one the software developers use, 'architects' don't stop coding, the system architecture doesn't exist in Visio or PP. It's evident from the structure of the codebase and the accompanying documentation, your role is to collaborate and work with the senior devs to ensure this design vision is realised and to explain in documentation why this architecture solves the business requirement it pertains to.

It's not something you wash your hands of and walk away from, having handed it over to the dev team. You're in it for the long haul, same as them.

<comment><USER25> If the project is very large architects don't have time to code. Sometimes they can test something before taking decisions but all the production code is written by somebody else. Their role is more about meeting people and help the organization making the correct decisions.

<comment><USER26> What is "very large"?

<comment><USER25> In my experience, a multi country mobile operator bootstrapping when 3G was a new thing 15+ years ago.

</comment></comment></comment></comment><comment><USER27> Currently my Favorite tool to Diagram Sofware Architectures is the C4-Model [1]. For the static view and use a normal Sequence Diagram for the Dynamic View. In both cases I like to use Plant UML, so that the text get's converted to the diagram[2]. That way the diagram can be stored together with the code.

[1] [https://www.infoq.com/articles/C4-architecture- model](https://www.infoq.com/articles/C4-architecture-model) [2] [http://plantuml.com/sequence-diagram](http://plantuml.com/sequence-diagram)

<comment><USER28> C4 is my goto as well.

</comment></comment><comment><USER29> I'm hearing two things:

1\. You want to build these diagrams faster and perhaps semi-automatically instead of dragging around boxes and lines.

2\. You want them to look better and not so perfunctory. To communicate better.

There is kind of an oddball option here which I fell in love with. There's a tool called Monodraw which is magic for making old school ASCII art diagrams. It's surprisingly very visually compelling, easy to update and it's just text so it can be embedddd in source code comments (no PDFs).

The best reason you might consider this over a "big" IDE-type solution is that ultimately good cogent communication requires making choices about what to highlight. An exhaustive auto generated architecture diagram in the same generic style of everything else can make one's eyes glaze over. When you choose what to show and emphasize you can tell a better "story".

Yes you have to keep the diagram up to date with major changes, but that's not a problem if you lower the cost of updating and raise the visibility of the diagram by putting it in code. They even have a CLI now so you can export it in your build process.

</comment><comment><USER30> Try PlantUML. For system architecture, you can check this PlantUML extension [https://github.com/RicardoNiepel/C4-PlantUML](https://github.com/RicardoNiepel/C4-PlantUML)

<comment><USER4> Plant UML is good. If you find it a bit constricting at times, I believe you can drop DOT graphs into the PlantUML diagrams, too. DOT is the language used by graphviz. You can of course use graphviz directly, too!

</comment></comment><comment><USER31> > where is the modern 'IDE' for the Software Architect?

Generally architecture is about imposing constraints on the system. If you think about it that way, what you really want is not to be treating Visio and PowerPoint documents as the primary artifacts. You want to define the modules (in Parnas's sense) and their interfaces and executable specifications. You want tooling that lets you constrain what modules may use other modules, automatically test modules, automatically mock modules, and be alerted when the constraints are broken.

Now, most of the tooling for this probably doesn't exist, or exists in partial, widely scattered forms. For example, you can define a Java package with the interfaces of a module and then have some kind of hook in the build system that checks that it is not being imported in places it shouldn't be. You can mark the interfaces that should be considered architectural constraints with a custom annotation and build a tool to extract out all uses of them and plot connections.

But I am unaware of any toolkit that will do what you want.

</comment><comment><USER32> Know that the two dimensions of a diagram are insufficient to express the confluence of logical data flow, physical data flow, dependencies, the infrastructure stack, the users and their use cases, commercial arrangements, legal entity boundaries, concurrent change initiatives, and boxes for the systems themselves and their fractal decomposition of modules and submodules.

Basically, pick your battles and just draw what helps communicate something.

</comment><comment><USER33> After the System Design Primer by Donne Martin got quite popular on Hacker News, I contacted Donne to find out which tools he used to draw those system architecture diagram and he was kind to respond my twitter message ( that is why twitter is so great ) to tell me it it is Omnigraffle ( only available in Mac and ios. )

10 years back I used to draw UML diagrams using Visio or one of the eclipse plugins for building systems diagram. However, the software landscape has changed quite a bit. On one of the podcasts of Martin Fowler recently, he also agreed that UML is now less favored standard in the software community.

Although I use Windows on my work but for the demo of the product I was working I built the system architecture diagram using my personal mac book and transfer to my work laptop to made a presentation. There was a good feedback and no-one raised any concern with UML or (any-)standards.

So, tool or IDE is less important these days, as we tend to use multiple tools/IDE based on the technology / framework / programming languages. I use intelliJ for Java, Sublime for Ruby / Rails + Angular + Others, Visual Studio for NodeJS, Vim for scripting, etc. etc....

</comment><comment><USER34> I think the best tool is still the old fashioned well written technical reports.

This book has many examples: [http://aosabook.org](http://aosabook.org)

</comment><comment><USER35> It's not a tool (though there is the Structurizr tool), I like the c4model: [http://c4model.com](http://c4model.com)

C4 provides an approach with multiple layers, which is good for talking about architecture at different levels with different people. I also happen to like the Container diagram approach.

</comment><comment><USER36> Gaphor ([https://github.com/gaphor/gaphor](https://github.com/gaphor/gaphor)) is an open source UML tool written in Python. The goal is to create a simple, easy to use modeling tool not a big enterprise tool like the ones already mentioned. I would like to soon support SysML which is for modeling systems design and requirements. We are finishing up converting it to Python3 and Gtk+3 now. We would love more involvement or input if there are things you would like to see supported.

<comment><USER37> Side remark: A few screenshots and/or video would be a great intro to get a feel of the program

</comment></comment><comment><USER38> You can use TLA+ -- it's what Amazon and Microsoft uses.

TLA+ is a formal specification language, plain-old maths, and the tool suite includes a model checker and a pretty printer. The model checker verifies properties of your specification that you want to hold true such as liveness. And it also includes a pretty-printer for exporting your specifications into well-formatted PDF documentation.

The nice thing about writing specifications this way is that they are specific, at the correct level of abstraction for the problem, and can be verified.

I think Lamport's analogy is apt: specifications are like blueprints. If you're building a shed in your backyard then a sketch will be sufficient. There's no need to have a blueprint. If you're building a house you'll need some kind of blueprint. The software equivalent of a sufficient blueprint for building a house is a strong, static type system, unit, integration, and property-based tests. If you're building skyscrapers you need something much more formal and I think this is where TLA+ and Lean are useful.

<comment><USER39> > it's what Amazon and Microsoft uses

That's not true. TLA+ is very useful but only few services adopt and benefit from it. Also it's not very readable and cannot document many design aspects e.g. the reasons behind technical decisions.

<comment><USER38> Ok, some teams at Amazon: [https://lamport.azurewebsites.net/tla/formal- methods-amazon....](https://lamport.azurewebsites.net/tla/formal-methods- amazon.pdf)

      Also it's not very readable and cannot document many design aspects e.g. the reasons behind technical decisions.

Not very readable? How so? I'd rather read a concise mathematical definition rather than three pages of prose and diagrams. It is most definitely readable although it does require some training to understand the mathematics if you're not used to reading it. Just as reading a blueprint requires a bit of training.

You can write prose into your specifications and integrate the outputted PDF specifications with the rest of your documentation.

<comment><USER40> > Not very readable? How so? I'd rather read a concise mathematical definition > rather than three pages of prose and diagrams. It is most definitely > readable although it does require some training to understand the > mathematics if you're not used to reading it. Just as reading a blueprint > requires a bit of training.

You glibly toss off "a bit of training" as if it's an afternoon's work over a cup of coffee. Understanding, intuitively, the systems that mathematical models like TLA describe is _extraordinarily_ difficult. Reading that 1-page model description for comprehension could be the work of days. Reading a 10-page prose and illustration description of the same system is likely to be the work of 10 minutes, and result in a much more thorough practical understanding of the system.

<comment><USER38> For some of the Amazon engineers mentioned in the paper that training took 1 to 2 weeks.

The trade off for that training is that you know the those properties it describes are correct. For some systems the trade off is worth it and for a few, required.

I didn't say you should use TLA+ for simple projects. It is incredibly useful for specifying systems where correctness, liveness, etc matter greatly and the complexity of the project is sufficiently high that you'd be uncomfortable describing it with boxes and arrows.

I think it's rather reckless to design a complex system of the sky-scraper magnitude without some sort of verification tool like TLA+.

It's a matter of degrees.

<comment><USER40> > For some of the Amazon engineers mentioned in the paper that training took 1 > to 2 weeks.

That's obviously a lie.

</comment></comment></comment></comment></comment></comment><comment><USER41> I like Arc42. It is aimed at documenting technical architectural decisions, the whys and constraints (budgetary et c) that lead to a particular design.

It also outlines the main boundaries, the key interactions.

Architecture should not be about the details. Rather it should be like a guide so that the developer can look at the source and see for themselves.

</comment><comment><USER42> GraphViz. Store the graphviz code in repo to track changes.

</comment><comment><USER43> Pencil & Paper, take a picture scan it in. Then type up descriptions.

<comment><USER44> This is why I agree with other commenters who say that there's no good way to do this: with pencil and paper, you can't make changes / expand / remove parts so easily, it's harder to make big documents, it doesn't look that good, and yet... it still is one of the best ways to do it.

P.S. I don't have anything against paper, and in fact I think it should be used more frequently while designing / prototyping / trying to understand or come up with algorithms, etc, it's a very useful tool.

<comment><USER45> Is there any software that translates a picture or scanned doc into a powerpoint? Seems like that could be useful: quickly churn out lots of boxes/arrows/text by hand, scan them, modify as necessary when translated.

</comment></comment></comment><comment><USER46> Great question. I too like diagraming and Im going to check out some of these tools.

Do you have any examples of your work? I can publish some of mine later today (have to remove specific details) if interested. I always love comparing and learning from different diagram styles.

I have found that spending a bit of time building some proficiency in Google Slides was well worth it. You have to do it without a real presentation in mind though, as it distracts from learning g the tool. Another big time saver came when I created a template presentation with colors, line weights, fonts and font sizes that were to my liking. The Polish, if you will, that we often don't want to go back and touch once the technicals are on the page.

</comment><comment><USER21> This is a loaded question. Is there a better way? Maybe. It is almost certainly not any easier, though. Likely takes longer and requires as much investment from the reviewers as it does from the authors.

I confess I'm fond of Literate Programming for this, though, I have never tried introducing it in a company. My hunch is it would take too long. By far.

Even documented software often takes too long. Same reason you don't plot out how you are going to win a ballgame. Outside of "score more points than you allow", the plans are almost all exploratory and reactive. Solidifying that into a document is dangerously slow.

<comment><USER47> I've long dremead of a architecture view that was zoomable, zooming in enough would end up on the actual code, but zooming out a lot would show you app server +database basically.

<comment><USER48> This would be incredible. No reason zooming out can't also show you stuff like load-balancers, message queues, firewalls, and their config/infrastructure code.

</comment></comment></comment><comment><USER49> If you're on AWS, consider CloudCraft. [https://cloudcraft.co/](https://cloudcraft.co/)

Disclaimer: not affiliated with and cannot vouch for them. I just think they look cool.

<comment><USER50> Looks interesting. Anyone used it before and can share the experience?

It seems to fill a gap nicely. When there are more than a few apps up in AWS it's easy to lose track.

<comment><USER48> If you use infrastructure-as-code like Terraform or Cloudformation you will find it harder to lose track, because the design, and hopefully some comments, are checked into source control.

Cloudcraft is good too, but not the whole answer.

</comment></comment></comment><comment><USER51> Suggestion: There is none.

Start writing a blog in Git using Markdown and some basic images (export diagram as PNG). Use HTML where necessary, for instance, tables.

Use dotty/sphinx/doxygen for autogenerated stuff. If your architecture changes too often, you are doing something terribly wrong.

Do not worry about extraneous things such as mobile form factor, jazzy visuals, image DPI or things like that. Instead, focus on making the text more readable or the diagrams easier to understand.

If you want to not be disconnected, write/use a relatively simple script to export a document as PDF (RelaxedJS or Prince).

</comment><comment><USER52> > "I still sit for hours in Visio & Powerpoint to painstakingly drag boxes and > lines around to describe systems."

I much prefer to skip the painstaking messing with Visio and instead use tools like [https://www.websequencediagrams.com](https://www.websequencediagrams.com)

Simple to update and no faffing around with formatting.

I normally then do a screen/audio recording whilst talking about the diagram. These have received very positive feedback from developers and non-developers.

</comment><comment><USER53> I've recently moved all my (new) diagrams to plantuml (my perso al workflow is actually orgmode + plantuml generation using babel).

I also asked my team if they are making new diagrams they should be made with plantuml.

The biggest benefit in my mind is clarity of design and most important of all: diagram as code, you can diff what's new in the latest version and everyone can comment/make pull requests to update the diagram if needed.

plantuml: [http://plantuml.com](http://plantuml.com)

</comment><comment><USER54> I developed an interactive visualization just for that purpose a few years ago. It's called ArchitectureTree.

[https://github.com/marmelab/ArchitectureTree](https://github.com/marmelab/ArchitectureTree)

The tech stack is a bit outdated (it used Angular.js), but the idea (using JSON to store the architecture) and the UI (powerful search, "bush" look) are still a good answer to the requirement of vizualizing complex software architecture.

</comment><comment><USER55> Take a look at cargo's contribution and architecture docs. [1] That project was hands down one of the easiest for me to get into and learn. I am a firm believer in a nice architecture document that points to interesting code sections. To date, I have never encountered a UML in the wild and been satisfied.

[1]: [https://github.com/rust- lang/cargo/#contributing](https://github.com/rust-lang/cargo/#contributing)

</comment><comment><USER56> Wikipedia has page on Architecture Description Languages - [https://en.wikipedia.org/wiki/Architecture_description_langu...](https://en.wikipedia.org/wiki/Architecture_description_language)

I've looked at Wright and Acme that are linked from that page. I came away with the conclusion that you need to use a formal language to describe relationships between the entities in your system. The language should be flexible enough to define new entities, and new kinds of relationships. All of that points to the need for an API/library to describe software architectures, probably using parameterized types in Scala/Java or relying on features in more dynamic languages like Ruby. The language need not be Turing complete, though.

An added benefit of using a formal language is that you can verify whether the invariants of the system are maintained when you make changes. For example: If you try to connect two components which support different protocols, the program won't validate.

These ideas may also have overlap with software specification languages - [https://en.wikipedia.org/wiki/Specification_language](https://en.wikipedia.org/wiki/Specification_language) . I didn't dig too much into that aspect.

Generating diagrams with suitable layouts from this description is a separate problem. Perhaps something from the field of graph drawing could help? [https://en.wikipedia.org/wiki/Graph_drawing](https://en.wikipedia.org/wiki/Graph_drawing)

<comment><USER57> We plan to try Structure101 [0] next year to verify invariants. I would love to see comments from people who have experience with it.

[0] [https://structure101.com/](https://structure101.com/)

</comment></comment><comment><USER58> I like to link our source code to enterprise architect so the sources you pull in a view are automatically populated based upon the source code. The eap can be checked in with the source to have an additional trigger to keep it updated. Also EA. can work with relative source code paths so others can use the same file. There is also a versioning system build in which works quite well. Some things I still dislike:

\- Enterprise Architect is a great tool but produces diagrams that look dated. This means I sometimes copy in another tool for certain types of meetings that require fancy powerpoints (pitch like presentations, customers, ex. Management etc.

\- if the source isn't there I create from scratch. I have to link post-source creation to update and link my diagrams to source code. I do not generate source code from enterprise architect because we do not work model based and usually my diagrams that I create in advance are not detailed enough to generate the source. (Nor should they be)

\- Sometimes the right diagram type is just not there in EA. I created my own templates for our department with all AWS logos and services, Azure, docker, and many others. That's a pain..

* I work in a global enterprise. Size of source about 6 million LOC. EA does handle that without hickups.

</comment><comment><USER59> "Document" is a bit of a troublesome word. It implies that you can communicate out into the void, and whoever reads it will understand a series of perhaps complex choices.

You probably want a model, not a picture. Visio is useful for making pictures -- diagrams. You want something that is a purposefully-simplified version of a much more complex system for purposes of communication/decision-making. Something that can be manipulated. Something to help facilitate conversations around certain narrow issues in a complicated system. That's a model.

There is a great post right now on HN about MVC. In it, there are some UML models. Check it out. They're not documentation of a system. They're isolated "cut-outs" to facilitate discussion around one area.

There are a bunch of great modeling tools. Many are being mentioned here. Go check them out!

The big thing to understand is the difference between a diagram and a model -- and making deliberate decisions both about what to include and exclude in each thing you share.

BTW, you can also use physical materials to model. The secret to good modeling is the simplification-mapping, not necessarily the model substrate being used.

</comment><comment><USER60> I like to use DrawExpress when I'm on the go, have an idea, and a phone or tablet.

[https://play.google.com/store/apps/details?id=com.drawexpres...](https://play.google.com/store/apps/details?id=com.drawexpress.full)

Gestures and drawing shapes are where the big speed improvements come from. Typing is eh since it's a touch screen but a keyboard fixes that.

</comment><comment><USER61> It does not exist. This isn't just for the software architect, but systems architects as a class don't have a generalized IDE to build diagrams (static or time-series) that allow them to think, demonstrate or iterate on systems in any meaningful way.

My workflow right now is hand-drawing diagrams in Paper and pulling them into a Notion page. Notion is amazing, the Paper workflow is not.

</comment><comment><USER62> I used to "draw" ER/Flow/Activity/Sequence diagrams through various DSLs that would output PNG files with Graphviz but for quite a while now I like to marry "hand-drawn" ASCII diagrams with a README-driven-design-and-development process.

Embracing the constraints of a simple README for particular sub-systems lets me also put together general systems overview documents very easily after.

That said pencil & paper / whiteboard almost always comes first of course.

[http://tom.preston-werner.com/2010/08/23/readme-driven- devel...](http://tom.preston-werner.com/2010/08/23/readme-driven- development.html)

[https://monodraw.helftone.com](https://monodraw.helftone.com)

[http://asciiflow.com](http://asciiflow.com)

Good non-ASCII alternative (for hyperlinked sharing in wikis etc):

[https://www.lucidchart.com](https://www.lucidchart.com)

</comment><comment><USER63> I've never been a system architect. But this reminds me of the principles of comments.

Obviously, one principle is "use as few comments as possible but no fewer".

But another principle is "don't spend extra-time formatting or otherwise prettifying a comment". Not only is that time not spent on development but it makes the comment seem more credible than it deserves and it can make other programmer looking at the comment hesitate to change it when they otherwise should.

Like comments, architecture draws may be fated to be often out-of-date. Like comments, that doesn't mean they're useless. Like comment architecture draws probably actually benefit from not looking more integrated into code than they actually are. They're a starting point, you have to read the code still but a starting point can be very important.

Perhaps your only real problem is finding a draw program you can use faster.

</comment><comment><USER64> I've found that writing pseudocode with doxygen formatted comments to generate sharable diagrams is _generally_ sufficient.

I actually got into that habit back when I was working with the insanely expensive suite of Rational IDEs. At that point, and later with the Eclipse Modeling Framework, the goal was to generate code from diagrams.... but that took more work than it was worth in my opinion.

With those tools, or with doxygen, you can get pretty far writing skeleton classes and method stubs, with exogenous systems represented the way you might mock them. Then just drop the generated SVGs into your slides, and profit.

 __This also answers your question about the lack of tooling: whenever a promising architecture /modeling product shows up they get acquired and then just fade away.

</comment><comment><USER65> I work in between policy and the actual scientists writing code and running experiments. I use Visio and LucidChart to make sure I've figured out how the decision flow in policy space can map to some realizable version of meat space and network space, and demonstrate to actual policy makers where their policies may not work (e.g. there's a pocket of bureaucrats who we know will squeeze the time out of our clocks, here's some software or infrastructure that will require additional authorization because it exists inside or outside a policy boundary, etc).

Some of those documents I never look at again. Some of those documents I show to other people and it's like watching lightening strike: "Oh, I like this, I like this a lot."

</comment><comment><USER66> Taking the Edward Tufte seminar will probably get you further faster than poking around in 5 different applications for the next few months.

[https://www.edwardtufte.com/tufte/courses](https://www.edwardtufte.com/tufte/courses)

<comment><USER67> Whoa thanks a lot for this suggestion. It looks amazing.

</comment></comment><comment><USER68> I used MagicDraw in a previous job, it's decent. We had it setup so that we actually generated C++ class's from parts of the UML. As well as generating powerpoint and word/pdf documents from it. MagicDraw also comes with its own version control system so that everything can live centrally on the companies server.

I do wish that it integrated with Git, and that the app was slightly faster / less bloated, but all in all; it was a much better experience than Visio & PowerPoint. These days I'm unfortunately back on PowerPoint architecture.

Enterprise Architect and MagicDraw are as far as I know the two most popular UML diagramming tools.

</comment><comment><USER69> It would be nice to see graphics representation of the software architecture in a README.md

> It then gets saved as PDF and shelved as an artefact that is disconnected > from all the other architectures, and the system boundaries are inevitably > out of date by the time the next person looks at it.

Personally, I think documentation should be stored into source control like git. Any changes needs to go thru this document first. Specification by Example is one I think would be beneficial. However, all of these takes human willpower and disciple and business buy-in... and is probably why I'm stuck reading an ultra-slow confluence that is not updated.

</comment><comment><USER70> I do do feel that this is an unsolved problem, because capturing structure, behavior and temporarily in any sort of meaningful visual drawing is difficult. Even structure itself alone with its deep nesting is complex to depict.

</comment><comment><USER71> As a tool, I find LucidChart fantastic for mapping architectures. It's a much easier to use, nice version of Visio, IMO. It is simple enough to use that other people adapt and maintain LucidCharts pretty well.

</comment><comment><USER72> I had an idea and made a proof of concept for a framework based on ontology language that generated both cloud resources (AWS cloud formation, with the plan to target similar infrastructure description languages) as well as a set of code snippets for CRUD operations to be deployed to those resources. The nice part was that you'd have all your types and data flow modeled in a source-controlled set of repos, and you could generate and publish up-to-date system diagrams at any level of granularity you wanted. Seemed cool but I never got around to doing much with it.

</comment><comment><USER73> I use LucidCharts and then export to SVG, pretty print, and embed that SVG in the repo. This gives versioning, use of an easy tool, and the ability for me to include it in markdown texts in my internal repo.

</comment><comment><USER74> I spend a lot of time in python land and as of late I've been using Sphinx mixed with django-extensions graph_models and some hand edited graphviz. This allows the lion share of my documentation to live in actual code and for all documentation to be version controlled, architectural docs can reference real classes and code documentation can reference architecture docs, stir in the ability to hack simple Sphinx plugins in python and it's been suiting my needs for everything from architectural overviews to operational "run books" and how-to guides.

</comment><comment><USER75> I guess there are many suggestions and tool offering here, they are very helpful to software ARCH, I can offer one alternative option here, which is mind map tools, it can help you make your thought of ARCH become very clear, in some sense, it will save you a lot of effort afterward: xmind and mindmanager.

[https://www.xmind.net/](https://www.xmind.net/) [https://www.mindjet.com/mindmanager/](https://www.mindjet.com/mindmanager/)

</comment><comment><USER76> I personally found that the most useful diagram to help me understand a Rails project I don't know is the E/R automatically generated from this tool: [https://github.com/voormedia/rails-erd](https://github.com/voormedia/rails- erd)

Being automatically generated, it's always up to date. As many others noted, I never had luck with written docs because it never happened to me to find good ones which were in sync with the project.

</comment><comment><USER77> I have found that a modelling tool (such as Sparx Enterprise Architect or Archi) as opposed to a drawing tool is useful. With a modelling tool there are increased opportunities for reuse and for the information to be presented in different ways (with differing levels of detail) depending on what needs to be communicated. It's not ideal, but I do however often still use both Visio and Powerpoint to better communicate the information in a more visual manner.

</comment><comment><USER78> > where is the modern 'IDE' for the Software Architect?

I have had success with [http://staruml.io/](http://staruml.io/)

</comment><comment><USER79> maybe have a look at [https://mermaidjs.github.io](https://mermaidjs.github.io). it's markdown for diagrams

<comment><USER80> I used mermaid in the past. Now I use nomnoml: [https://github.com/skanaar/nomnoml](https://github.com/skanaar/nomnoml)

</comment></comment><comment><USER81> This is a problem that I struggle with. I proposed what in my IMHO is a fairly comprehensive system for documenting architecture. It starts from stakeholders and goes on till it reaches instrumentation. Here is a video that explains this. Would appreciate comments on this. [https://www.youtube.com/watch?v=UCoXgafOyMw](https://www.youtube.com/watch?v=UCoXgafOyMw)

</comment><comment><USER82> Piggy backing on your post, I have a very large and complex systems of architectures (both hardware and software). I'd love to take that documentation and run analyzation on the data/node and their relationships (maybe via a graph DB in the backend and some rich search capabilities). Anyone know of any tools that not only help you draw and document, but interface with the diagrams via API?

</comment><comment><USER83> I wonder how useful it might be to try sketching cartoon technical explanations of the type that Julia Evans or Lin Clark do. Then again, how long does it take to develop the manual skill to produce these?

[http://jvns.ca/zines/](http://jvns.ca/zines/)

[https://code-cartoons.com/](https://code-cartoons.com/)

</comment><comment><USER84> Try using a modelling tool rather than a drawing tool.

</comment><comment><USER85> I have been a little out of the game lately but I remember that things like ArchiMate [1] try to solve or at least improve your situation. But this may very well be out of date. There is some research into improving IT architecture management going on all the time.

1: [https://www.archimatetool.com/](https://www.archimatetool.com/)

</comment><comment><USER86> I tend to use Confluence with the Draw.io plugin. I have a custom template for specification and requirements along with a business process. Changes are captured in the history and highlighted as part of the business process.

It is a much better system for my team compared to getting changes by email or phone.

It does take some discipline to execute, but it is worth the effort in my opinion.

</comment><comment><USER87> Use mediawiki, the software that runs Wikipedia, to document. It doesn't easily go into book format, but hypertext is really powerful and easy to use. You can also embed powerpoints in it. Best of all, updates and versioning are easy as it's a living breathing hyperlinkable system with a full change history built in.

</comment><comment><USER88> Saved PDFs that nobody read anymore is one of the issue we are trying to address with [https://mototomo.io](https://mototomo.io)

We want to tie your architecture visualization with your CI, making it an integral part of your daily workflow.

We focus on mobile apps at the moment but more stacks are in the pipeline.

</comment><comment><USER89> This reminds me of an idea I had: building service maps from logs.

If your logs have:

1) common format

2) service application names

3) tracer bullets

Then in theory it should be possible to create a crude visualization of a service mesh across your apps. It'd be a lightweight version (or extension) of Zipkin, I think. Although I'm sure there's a bunch of edge cases I'm not thinking of.

</comment><comment><USER90> We've at least come up with a way to programmaticaly declare links. We now can add comments above endpoint definitions in code and upload these "edges" to a central server that stores them to a graph. It has a web frontend that renders the graph (via tree.js I think). Not OSS though.

</comment><comment><USER91> yEd from yWorks - [https://www.yworks.com/products/yed](https://www.yworks.com/products/yed) has excellent features (with auto-arranging of nodes for better readability). Might be useful :)

ps - it's FREE!

</comment><comment><USER92> I only abide with one rule - the documentation that you would create, whether diagrams, contextual model, or any artifact related to the software should be something worthwhile to read. Otherwise, it all becomes a meaningful assumption with zero audience.

</comment><comment><USER93> Product Requirements Documents and Design Documents are a good start. At least then you have a 'human readable' understanding of what they were trying to accomplish. Note that diagrams are often part of a design document.

</comment><comment><USER94> I'd like to understand if is there is some sort of "Literate Programming" approach to this problem? Interleaving the architecture through the (combined) code + architecture document?

</comment><comment><USER95> Questions, isn't Terraform exactly suited for this? And doesnt it come with rudimentary charting features? I mean the charting feature is terrible by default but it's something, no?

</comment><comment><USER96> We use the Flowchart Diagrams stencils in Moqups just for that. And, because it's collaborator friendly, your team can hold you accountable if the diagrams become out of date.

</comment><comment><USER97> Enterprise Architect by Sparx is by far the best one I've used. At least as of a few years ago. The best user experience / convenience / features.

</comment><comment><USER98> I've had tremendous success using a custom modeling language inspired by and older version of the Archimate approach and some simple diagramming tools (I typically use yEd, but you can use pretty much anything that supports the ability to layer sub-diagrams like you might in horizontal swim-lanes).

The approach is to use different stacked layers to represent different levels of abstraction or specificity and how they all align to a business goal at the top layer. The layers can change depending on the environment but typically are as follows:

       Top - Business Goals
       (Top - 1) - Specific Software Implementation
       (Top - 2) - Application and run-time environment
       (Top - 3) - Containerization Layer
       (Top - 4) - Virtualization Layer
       (Top - 5) - Hardware Layer

I like to use boxes that have two sections a top section for a title and a lower section for some descriptive detail.

The basic idea is to describe, as a stack, all the components that go into servicing a given business goal. Start with the hardware, and add boxes going up the stack until you've described all the components of the system. Connect them with arrows pointing up to the next layer. If you need to group things together at a layer, use a box to group them.

Some components might live in one lane or another (or both), depending on how you think about them.

Use colored arrows to show dataflow between components at the logical layer (you can infer the flow between all other lower layers from the stacks). I like to use red, blue and green to model the dataflow at different system states like red for deployment, green for operational and blue for configuration.

Add or remove layers as you deem fit. Urls, usernames/passwords, IP addresses, specific config options and so on fit in the descriptive components. For some smaller ER diagrams you can even fit them right in the lane or have a call-out to another diagram with the larger diagram.

Some people like to use different colors for the different layers (e.g. Archimate-style).

Print off the diagram on a plotter every so often so you can stick it on a wall and write on it as things develop. Adjust the diagram in a sync every week or two to keep it up to date.

The goal is to have a flexible framework and not to get locked into a modelling approach with such a high specificity that you're sweating over which kind of arrow represents exactly what thing, but if you need that for certain cases you can. The layered approach helps to decouple/deconvoluted some of the density of meaning in other languages that often has people having to look symbology up just to read the diagram. You can adjust/tweak as necessary and most projects have some different "dialect" of this language. Fill it out with just as much specificity as you need to answer any question you have. Often entire boxes just have a ??? for the description because it's not entirely necessary to know the details.

I've used this to describe fairly complex systems that serve millions of requests per day and after 3 or 4 iterations the diagrams were sufficient to answer any non-code-specific question we had. Multiple systems can be displayed next to each other and the dataflow arrows show interactions so you can even show very complex inter-service interactions as well.

I think the most important factor here is to use it as a mix of both documenting work that's been done (the existing system) and use different looking boxes to show aspiration or forward looking work to do (maybe dashed lines or a different color or whatever). Don't try to design the entire system at the start or you'll fall into disharmony with your agile developer teams.

I put a really trivial example here (made in yED) [https://imgur.com/a/H8dCwoD](https://imgur.com/a/H8dCwoD) I made this in just a couple minutes using mostly default yED pallet options if that helps you understand the level of effort (probably spent more time tweaking the colors to white and the font tbh).

</comment><comment><USER99> After using Omnigraffle exclusively, I've taken a huge liking to PlantUML and alongside confluence... it serves 90% of my needs

</comment><comment><USER100> ASCII art is the gold standard. You can still read those RFCs decades later. Add a little Markdown, and you're done!

</comment><comment><USER101> Fire yourself up a Windows XP virtual machine, pour a glass of white zinfandel, and go to town with Rational Rose.

</comment><comment><USER102> You could try [https://archbee.io](https://archbee.io)

</comment><comment><USER103> Graphviz is surprisingly good for documenting architecture - bonus of bring easily versionable too!

</comment><comment><USER104> There is a very good way to document software architectures:

I use BPMN 2.0 with DMN

Look it up, see what you think.

</comment><comment><USER105> Make documents live. Make them an organism. Swagger.io is the best idea ever.

</comment><comment><USER106> You should instrument your systems to product the diagrams.

</comment><comment><USER107> I manually write SVG, and maybe even animate them. Not the most productive way, but a picture can say more then thousand words. You can then put it into source control, web pages, or just have it as an image.

</comment><comment><USER108> I would love a design IDE!

*Edit - off topic

</comment><comment><USER109> >It then gets saved as PDF and shelved as an artefact that is disconnected from all the other architectures

Sounds like architecture to me. You're doing it right already!

</comment><comment><USER110> Draw.io has Amazon service icoms and GCP too. Did you try that?

</comment><comment><USER110> I never knew architect was a thing in software.

<comment><USER55> The title is commonly found in heterogeneous projects where software isn't the solo driver. Ex: embedded systems

Pretty much the title just describes a senior dev., who owns the software aspect of the project.

<comment><USER57> I'm working in automotive. The usual chain seems to be requirements engineer, system architect, software architect, software developer, integration engineer, tester.

</comment></comment></comment><comment><USER111> Man, it seems like you totally lost connection with technology. There is no value in an architect who doesn't code (none, if you think otherwise you've worked too long in enterprises that don't deliver enough value to stay relevant the coming years). Just use whatever drawing tools you know and draw up your diagrams. Should never take you hours to draw them up. How complex are they? If they take you so long, you probably are documenting way too much or are using way too complex architectures.

I feel the solution to your problem is more in the application than the tools. Try moving towards architectures like micro services. KISS. Then use the time you're freeing up to keep connected to your developers and write code.

<comment><USER39> One thing I loved about Amazon was having no architects, visio, powerpoints, UML in any of the teams I worked in.

Each service is designed, documented, implemented, deployed, maintained and advertised to other teams by the same few engineers.

Most documentation and runbooks are just text in wikis. If your service cannot be documented without drawing 10 boxes and 20 arrows you should split it in smaller services.

<comment><USER111> That's nice! Agile to the max!

<comment><USER39> not really

</comment></comment></comment></comment><comment><USER112> You're going to get a fair amount of hate for mentioning the word "architect" here. They go into the same naughty list as manual testers, Scrum masters and release managers! Despite this, they can be very necessary for large orgs.

I've used Ardoq in the past, decent tool. All manual. Sparx EA looks very similar to visio and heavily TOGAF influenced. Both models are tough to create and maintain. A DSL in their own right.

No one really cares about architecture diagrams until they're really needed i.e platform migrations, rewrites, onboarding new staff, better reserve instance pricing. I've seen 6 different development teams all write architecture diagrams differently. All of them out of date and inconsistent.

I do think there is an opportunity here to build something more useful, the difficulty I see is that architecture is quite dependent on perspective. Security sees perimeters and firewalls, development sees microservices and DBs, DevOps see VPCs and networking.

I did come across weave works visualisation tools for Kubernetes that seem impressive and an OpenSource project but haven't had a chance to play with it yet.

You're right in your initial assumption that there is nothing out there to model architecture easily. Visio is as good as we have right now.

<comment><USER113> Do point towards the "architect" hate pages, please. You've piqued my interest.

<comment><USER112> Scan up and down this thread. Comments are saying he/she shouldn't have a job, he/she should be writing code instead, who is h/shee to dictate to delivery teams.

This was posted a few weeks back by a DRI in Stripe, [https://hyperbo.la/w/aws-org-chart/](https://hyperbo.la/w/aws-org-chart/), which sounds alot like what traditional architects do. Nobody showed any interest.

Anytime I've attempted to raise a discussion on this it gets shut down quickly.

Yeap, maybe hate is a strong term. Certainly bad feeling towards the practice.

<comment> m-i-l The analogy I sometimes use is that you don't need an architect to design a garden shed, but you do for a house which is much larger, has complex integrations with plumbing, electrics etc., plus building regulations to comply with, etc. A lot of dev work, especially in smaller companies, is building garden sheds, i.e. small single purpose self contained apps, but that doesn't mean every building is a garden shed.

<comment><USER112> I like that. The logic is often "I worked on a team that didn't require an architect, therefore no teams require architects".

I do readily admit there are quite a few hapless architects out there though.

</comment></comment></comment></comment></comment><comment><USER114> If you need documentation for architecture, your architecture is complicated. Improve the architecture instead.

<comment><USER115> Sometimes the least complicated architecture is still complicated (by human standards).

<comment><USER114> What i mean is, the simplicity is in the: "If i cameback to my project after 1 or 2 years, i can easily work with it because it has no complexity to remember".

<comment><USER116> Some problems are inherently complicated, even if you come up with the best design.

</comment></comment></comment></comment><comment><USER117> What love about the Shinkansen, at least Tokyo <-> Osaka is that it leaves every 5-10 minutes so I never make reservations. I just casually go when I feel like it, shop outside for a snack, then go in and get a ticket at a machine and hop on the next train.

This is something I can't do with planes as well as you have to book in advance, get there early, check in, get inspected, line up to board. Filling plane seems to take 15 to 30 minutes. Filling the train takes 2-3 mins. And of course the train drops me off in the center of town, not 30 to 90 minutes outside of town like most airports.

There's a couple of seasons where getting a seat or getting 2 seats together might take more planning but most of the time taking the Shinkansen feels no different than taking any local train or subway in terms of prep which makes it super easy to use. It's a little expensive, $240-$350 round trip (free seating->reserved seating->1st class) but I've still made impulse trips for various events deciding on the same day that, yea, ok, let's go!

I will say China's bullet trains are amazing as well but booking/tickets are not nearly as smooth.

<comment><USER67> Wrong thread mate</comment></comment>


Google's summer interns make for noisy neighbors  - <AUTHOR> http://money.msn.com/now/post--googles-summer-interns-make-for-noisy-neighbors <comment><USER2> This seems pretty tame, IMO. I think these folks should pick their battles. Better to have intelligent kids making noise (as they'll probably listen to you when you ask to quiet down) than to have belligerent kids who were raised with poor manners.

<comment><USER3> Yes, because when you're living in an apartment that costs $3,200/month and can't fall asleep because your neighbor is blasting nerdcore music, at least you can find solace in the fact that the noisemaker is an intelligent, well- mannered computer whiz who is apparently so intelligent and well-mannered that he doesn't recognize making lots of noise in the middle of the night is rude.

As for darting out into traffic, there's an Android app for that, right?

<comment><USER4> >Yes, because when you're living in an apartment that costs $3,200/month and can't fall asleep because your neighbor is blasting nerdcore music...

This never happened. What you imagine Google interns to be like and what they actually are seem to be disjoint sets. Music isn't even mentioned in either article or the Yelp review.

And I am somewhat suspect of the claim that Google interns are darting into traffic. The problem is if it happens even once by accident, you'll have residents complaining that it's an epidemic.

<comment><USER3> I was being sarcastic, perhaps poorly. I know people who work at Google, and I can assure you that they don't like listening to music. Or soaking in hot tubs. Ever. I'm not sure about jaywalking though. I'll have to ask.

</comment></comment></comment></comment><comment><USER4> If building security is honestly unable to do anything about it (as mentioned in the linked article) I suspect the claims of residents are somewhat exaggerated. Especially considering some of the "havoc" they're causing is jaywalking. While it's undoubtedly important to be a considerate neighbor, I suspect there is some overreaction here.

Edit: I read both stories and the Yelp reviews[1] that sparked them. They're nothing more than blogspam designed to make people go "Oh yeah I can totally imagine what they might be like..." and project their own ideas of noisy college kids on to these interns.

The interns aren't blasting music, screaming in the night or breaking anything. It's telling that one of the accusations against them is jaywalking.

[1][http://www.yelp.com/biz/crescent-village-apartment-homes- san...](http://www.yelp.com/biz/crescent-village-apartment-homes-san- jose#hrid:fdzRsLGvf2h-yxLQ3ET92w)

</comment><comment><USER5> "like a dorm now"

This person is exactly right. That's what happens when you house 400 university students together. I don't see how this has anything to do with them being Google interns. It's completely reasonable that the residents are upset, most people would be if their quiet apartment became like a dorm, but this is the fault of the building management, not Google.

</comment><comment><USER6> They put a bunch of college kids in an apartment complex. What else did the neighbors expect to happen?

</comment><comment><USER7> I think the issue is that fairly immature college students are making enough money to live a mature life, and they are thus being transplanted into communities of middle-class people in the bay area.

Without commenting on the pay of these interns, perhaps Google should consider arranging centralized summer housing for these interns purely because of the difficulty of the local market. It would be yet another perk for recruitment, and ostentatious behavior by interns could be curtailed to Google-controlled areas.

The intern I recruited for the summer in SF seized my offer of an air mattress on my floor for the summer, and I can't help but think that these other interns are just being forced into an awkward, foreign environment rather than intending to cause ruckus.

</comment><comment><USER3> No wonder I didn't have any luck recruiting interns this summer. $3,000 apartments? Hot tubs? Jaywalking?

I thought shelter in the Ghost Town part of Oakland and an AC Transit bus pass would surely lure a true hacker or two. Guess I'll have to rethink this next year.

</comment><comment><USER8> What's the vacancy rate in San Jose? I would not have expected offhand that they could find an apartment complex with enough vacant units to house 400 interns. Even if they are putting 4 interns per apartment, that would be 100 units.

</comment><comment> shawn-furyan How did this make the front page again? I don't get why anyone would care about this. If the company was Exxon, GE or BoA instead of Google, would this have made the front page once, let alone twice?</comment>


Bash Vi Command Line Editing Mode - <AUTHOR> http://www.catonmat.net/blog/bash-vi-editing-mode-cheat-sheet/

<comment><USER2> It's readline that has the vi mode

      set editing-mode vi

in .inputrc will enable it everywhere.

<comment><USER3> luckily not everything on the command line uses readline, else there'd be way more gpl licensed command line tools. vi mode has been in nsh and pdksh, independent of gnu readline. It is also part of the specification for sh at opengroup.org:

[http://www.opengroup.org/onlinepubs/000095399/utilities/sh.h...](http://www.opengroup.org/onlinepubs/000095399/utilities/sh.html)

Interesting note about emacs mode though:

In early proposals, the KornShell-derived emacs mode of command line editing was included, even though the emacs editor itself was not. The community of emacs proponents was adamant that the full emacs editor not be standardized because they were concerned that an attempt to standardize this very powerful environment would encourage vendors to ship strictly conforming versions lacking the extensibility required by the community. The author of the original emacs program also expressed his desire to omit the program. Furthermore, there were a number of historical systems that did not include emacs, or included it without supporting it, but there were very few that did not include and support vi. The shell emacs command line editing mode was finally omitted because it became apparent that the KornShell version and the editor being distributed with the GNU system had diverged in some respects. The author of emacs requested that the POSIX emacs mode either be deleted or have a significant number of unspecified conditions. Although the KornShell author agreed to consider changes to bring the shell into alignment, the standard developers decided to defer specification at that time. At the time, it was assumed that convergence on an acceptable definition would occur for a subsequent draft, but that has not happened, and there appears to be no impetus to do so. In any case, implementations are free to offer additional command line editing modes based on the exact models of editors their users are most comfortable with.

</comment></comment><comment><USER4> This works in ZSH as well, I also didn't know about it so this is definitely going to save me a lot of keystrokes. Although I already had some of the regular shortcuts memorized (like ctrl-a goes to start of the line) being able to use one set of keybindings is great!

<comment><USER5> And in Zsh, you could even have it show the current Vi mode (Insert or Command) in the prompt. I don't have my .zshrc handy, I'll try to get the command once I get the .zshrc.

<comment><USER6> Wow, that's been my biggest trouble with vi mode for years, and I've been using Zsh for a long time and didn't know it could do that. I would be eternally grateful if you could post the solution here...

<comment><USER5> I'm at work after a long vacation, so got access to my .zshrc. Here's the relevant part:

        #It starts in insert mode
        export VIMODE=INS
        function zle-keymap-select {
            VIMODE="${${KEYMAP/vicmd/CMD}/(main|viins)/INS}"
            zle reset-prompt
        }

        zle -N zle-keymap-select

        bindkey -v

I use Oh My Zsh, but as far as I know this should work without it too.

Wish HN had a notify-on-reply system like Reddit's orangered. Would you see this? Would you not? Would I miss eternal gratefulness from a fellow HN citizen? Oh, how I wish I knew the answer!

<comment><USER6> Maybe you won't even see this ;) , but it unfortunately doesn't seem to work on my vanilla Zsh. Perhaps I'll look into OMZ a bit and see if things work out that way. Thanks anyways :)

</comment></comment></comment></comment></comment><comment><AUTHOR> I've been using Ubuntu and bash for several years now, and never knew until today that Bash had a Vi mode. I'm ashamed.

</comment><comment><USER6> My biggest complaint about readline's vi mode is that there is no visual indicator of what mode you are in, and it seems there are quite a few actions that unexpectedly take you out of insert mode as compared to using Vim, and without some way of seeing this, it's an exercise in frustration.

I've been using Vim as my primary editor/IDE for three years now, and I still can't get used to vi mode on the command line, and keep going back to emacs mode because it functions exactly like you would expect it to.

</comment><comment><USER7> I use vim as my editor but never got on with "vi mode" in bash/readline or zsh/zle. However, when you have a complicated command line you can use vim (or your favorite $EDITOR) on it.

In bash type Ctrl-x-e

In zsh I press Ctrl-z, which does what I want because I have this in my .zshrc:

      setopt hist_ignore_space # trick so that history doesn't get polluted
      function edithist() {
         local tmp=${TMPPREFIX}${$}hist
         read -Erz >| "$tmp"
         "$EDITOR" "$tmp"
         print -Rz - "$(<$tmp)"
         rm "$tmp"
      }
      bindkey -e '\M-q' push-input # replaces push-line in 3.0.x
      bindkey -e -s '\C-z' '\M-q edithist\n'

The zsh version leaves you editing the command line after exiting the editor. The bash version executes the command after exiting the editor.

<comment><USER3> And if you don't have a problem with vi mode, use ESC to enter command mode and enter v to edit the command line in ${EDITOR}

</comment></comment><comment><USER8> I've known about Vi mode for a long time, but have never been able to make the switch. It's a brain bender!

<comment><USER9> Something similar happened to me. I'm a happy Vim user and have been for years, but I've always used bash in emacs mode.

However, some months ago I started to work in an environment full of Solaris 8 machines with ksh as their default shell in vi mode for some reason. It's configured that way for every machine and we have to constantly log in and out of them to do our jobs, and it's always been that way so I simply didn't ask for it to change. After all I was also the new guy.

After a few weeks I got so tired of trying to use emacs commands in vi mode shells while at work, and vi commands while in emacs mode at home that I changed to vi mode at home. And I've been happy since then. It's not that hard. You get used to it quickly, especially if you use vi or Vim a lot like I do.

</comment></comment><comment><USER10> One really really annoying thing about this: pressing return in "normal" or "insert" modes executes the command. That behaviour just doesn't feel right.

<comment><USER5> Why? What would you expect it to do?

<comment><USER10> Well, Enter in normal mode in vi puts the cursor on the next line, at the first non-whitespace character. I would like enter in "normal mode bash" to do the same. I would also like to scroll up (j) and see the previous command as i left it (i.e. if modified, show them).

</comment></comment></comment><comment><USER11> Is there an analog for \e on the postgres console? That makes more sense to me than using vi editing all the time

<comment><USER12> fc</comment></comment>


Apple starts patenting mobile app ideas - <AUTHOR> http://www.unwiredview.com/2010/07/30/apple-starts-patenting-mobile-app-ideas/ <comment><USER2> For years I've said that Apple is by far one of the scariest software companies out there.

The enthusiasm for their products and CEO seems to have a blinding effect on the very same people that would normally be up in arms.

I think it would be an interesting social experiment to outline many of their business practices without mention of the products, company or brand, even possibly an alias, or dummy co. and survey their hardcore base for opinion of the company.

<comment><USER3> You have to think about it. If Apple were a type of government, what type would they be?

Wait, Ill let you guess.

Socialist Dictatorship. Think about how closed they are as a system... Would you really want a Socialist Dictatorship running your country?

<comment><USER4> This is a pretty flame-y comment. There's not much use in this comparison. It only serves to ignite the Apple fans and detracts from what could be an otherwise great conversation about _this particular event_.

<comment><USER5> I don't get how mentioning the political angle of the sentiment expressed in the parent post somehow makes it flamey.

Both platforms and governments represent ways of coordinating the productivity of numerous participants. Although there are differences it seems reasonable to think that lessons learned in one sphere may very well transfer to the other. If you believe that central planning is the most effective method for a platform (both hardware and software) then isn't it reasonable to ask why this wouldn't translate to the wider economy as well?

<comment><USER6> It's not a useful comparison. Companies aren't run like governments, where democracy is usually held as the ideal. The comment wasn't useful, but it was inflammatory. I don't think the commenter had bad intentions, but I agree with stanleydrew's judgment.

<comment><USER7> I've actually been wondering a lot lately why _isn't_ democracy held as an ideal for companies? With the amount of power that large corporations have, why do we as a society not hold them to higher standards and require them to _be_ governed more democratically?

<comment><USER8> Because the nothing would ever be done.

<comment><USER7> Then why do we run countries that way? If "benevolent dictatorship" is good enough for giant multinationals, why isn't it good enough for nations? If it isn't good enough for nations, why is it good enough for multinationals that have as much or more power than many nations?

</comment></comment></comment></comment></comment></comment></comment></comment><comment><USER9> As bad as this seems, the best thing you can do as an aspiring developer is _ignore it completely_ , and do whatever you're going to do anyway.

The only way these patents are going to matter to you is if you hit it big enough to be worth taking to court -- it's a millionaire problem. Even then, there are lots of steps between "patent granted" and "patent successfully defended in court". You're so far from that point that it's not even worth thinking about this kind of crap.

Also, before you bust out your pitchforks and torches, put your logic hat on for a second: this doesn't make any sense as an offensive move. The patent system is broken and everybody knows it. And as a result, any responsible tech company with sufficient resources _must_ play the same game of mutual self- destruction. Meanwhile, Apple has a vested interest in cultivating a developer community. Patent trolls could easily kill that community. If Apple didn't patent ideas like this, some patent troll in Texas _would_ , and the situation would be much worse for small developers.

Obviously, I don't _know_ if Apple is being defensive or offensive here, but it's pretty difficult to imagine them going from retail hardware company to professional patent troll. Again, it doesn't make sense as an offensive move.

<comment><USER10> >The only way these patents are going to matter to you is

...if you want financing.

The investment community keeps a close eye on patents, because it's a major potential liability.

>Obviously, I don't know if Apple is being defensive or offensive here, but it's pretty difficult to imagine them going from retail hardware company to professional patent troll

It's easy to imagine. Microsoft went through exactly the same metamorphosis. Originally their patents were "defensive" (which is a spurious to start with -- simply documenting making an idea public is just as much of a defense), but as the growth curve started to peak they started looking at that portfolio as a way to assure their continued success, if by less productive means.

<comment><USER11> > which is a spurious to start with -- simply documenting making an idea > public is just as much of a defense

The idea behind defensive patents isn't that they defend your use of that idea, but that they defend you from competitors who have patents that might affect you. (Since they hopefully allow you to countersue.)

</comment></comment></comment><comment><USER12> One thing that surprises me in the images was that one of them is exactly "Where to?" by tap tap tap:

<http://taptaptap.com/#whereto>

<comment><USER13> Wow, it's just blatently ripped off! Wonder what else they got "inspired" by...

Direct links to the images:

taptaptap: <http://taptaptap.com/img/screenshot/whereto/1.jpg>

the patent: [http://www.unwiredview.com/wp- content/uploads/2010/07/Apple-...](http://www.unwiredview.com/wp- content/uploads/2010/07/Apple-patent-travel-app.jpg) (upper right "mockup")

<comment><USER14> maybe they are trying to protect the app, so that folks on other platforms (cough-google-cough) don't rip it off?

<comment><USER15> If a patent is filed by someone other than the inventor then it is void. They would have to put the taptaptap people on the patent.

</comment></comment></comment></comment><comment><USER16> While I'm certainly not a fan of this like most commenters here, am I the only one that is of the opinion that instead of hating Apple, we should hate the broken US Patent system?

While it disgusts me that they are able to patent these things, they are operating within the current rules of the patent system, and one could argue that if they didn't do so, someone else may come along and patent the same things. The phrase "don't hate the player, hate the game" comes to mind. In fact, they could be running afoul of their duty to their shareholders if they did not make their best effort within the law to protect their intellectual property. They could be altruistic and morally correct as many people here seem to wish they would, but someone else could come along, file the same silly patent, and succeed then bring a suit against Apple for infringement. We should all be sending letters to the USPTO or Congress, not Apple for this atrocity.

Further, it is important to keep in mind that these are patent applications that have been FILED, but are not patents that have been ISSUED. There is a big difference there. I could file an application for a patent on a pencil, but it will not become an issued patent because that's bogus. Likewise for these, they may well get rejected for being unpatentable subject matter.

</comment><comment><USER17> Too many free passes for Apple in these comments.

</comment><comment><USER18> This seems like a direct conflict of interest for Apple. Patenting app ideas will only serve to further alienate developers from the platform.

I don't see any good coming from this, and I really hope "generic idea" patents like this start getting shot down by the patent office with regular frequency.

</comment><comment> alok-g The philosophy with patents these days is that whatever you do (as a part of a big company) that hasn't been done exactly that way before, you submit an invention disclosure on it. In this sense, patents these days are used more like copyrights!

</comment><comment><USER19> Gary Kildall refused to develop anything like a word processor application for CP/M because, basically, that way leads to evil and corruption. MS, of course, beat him out in the IBM deal and dominated with exactly that recipe.

Everything old is new again.

</comment><comment><USER20> They recently patented this 3D Modeling using an iphone too: [http://www.appleinsider.com/articles/10/07/29/apple_investig...](http://www.appleinsider.com/articles/10/07/29/apple_investigates_3d_recording_of_real_world_places_objects.html)

</comment><comment><USER21> The article only looks at it from the 'Apple is evil' perspective. I wonder if Apple are patenting these purely so that others can't and thereby allowing freedom for developers to develop these apps without worrying about patent infringement

<comment><USER22> I'm looking at this from the "ANYONE who tries to patent generic ideas is evil" perspective.

<comment><USER9> No offense, but that's not a very nuanced or useful way to think about the situation. It's the same line of thinking that makes 16-year-old kids declare that they'll never work for The Man. Idealistic and perhaps admirable, but not very practical.

Opposing any individual player in a game for acting in their own rational best interest is dumb. If a big company with good products _didn't_ act defensively in these situations, they'd be eaten alive by patent trolls who have no such qualms. Until the _laws_ are changed, these kinds of patents are a necessary evil.

<comment><USER23> A complication with patent trolls is that they're immune to defensive patents: they don't practice, so they can't be countersued or bargained with. I think you probably mean "other companies that develop mobile apps." In this case, especially in the context of the direct copy of the TapTapTap app as shown above, it looks like this means "our own developers."

</comment></comment></comment></comment><comment><USER24> I don't see these patents up on PeerToPatent.org yet, but if anyone has any data that can invalidate them, keep an eye out for when they do go up and stop the applications in their tracks.

</comment><comment><USER25> Why do people expect Apple to play by different rules? If they are developing these applications to be released in 8 months they're potentially in a bad spot if someone else patents them 2 months from now. What they choose to do after they are granted the patent is a separate issue. Patent reform in general is yet another issue. It's like complaining that the away team hits a technical free throw in a basketball. That's just how the game is played these days.

</comment><comment><USER26> Even more worrying is the clear indication that Apple is switching to E-Ink display technology for next-gen devices.

</comment><comment><USER27> seeing this has pushed me over the edge. i now want to join or start an effort to destroy or at least fix the idiocy that is the current US software patent system. we cannot let this bullshit continue!

</comment><comment><USER28> What ever happened to Apple taking the lead, standing up, and doing the right thing, damn the consequences? One of the reasons why Apple fans have been so fanatical about Apple products is because they know Apple will do the right thing. Unlike say, Microsoft.

So now Apple is just like any other evil, scheming mega-corp. It's pretty sad actually. Like the day the music died, Apple software has died.

<comment><USER29> When has Apple ever indulged in idealism? They support a hellhole of a manufacturing plant, they willingly implemented DRM before complaining about it, everything they've made for decades has been disposable and hostile to tinkerers, and now they are starting a dystopian software market that's authoritarian in ways Microsoft never even dared.

<comment><USER28> Hmm, after you put it that way, you are right of course. I think you just broke my Reality Distortion Field!

</comment></comment></comment><comment><USER30> Don't hate the player, hate the game.

<comment><USER31> If this is an analogy to sport and say the sport is baby killing. Then I can hate the game and the player. You have a choice to get involved in the game.

If this as an analogy to drug dealing. I agree that you should not hate the players, as they have no choice.

However, I am allowed to hate the drug lord(s).

<comment><USER30> > _If this is an analogy to sport and say the sport is baby killing. Then I > can hate the game and the player. You have a choice to get involved in the > game._

My point is that Apple is merely playing by the same rules as everyone else. Getting upset because Apple patents something broad or obvious is just misguided, they're quite honestly doing exactly what they are supposed to be doing as a publicly held company.

Some companies may avoid patents for ethical reasons, but ignoring the problem isn't going to solve anything.

IMO, anyway.</comment></comment></comment>


Silicon Valley: Feel the Froth - <AUTHOR> http://online.wsj.com/news/articles/SB10001424052702304470504579161880453868414 <comment><USER2> Bubble talk and high valuations comes up every month or so. pud's comment sums it up nicely:

Generally, being profitable precludes a company from getting "silly [high] valuations" & buzz in Silicon Valley. Unless they're really, really profitable.

Big valuations usually stem from not knowing how much a company will make once they start charging for stuff. So the "it" crowd works itself into a frenzy and VCs take a big gamble.

But once you make a dollar, all the mystery is gone. You're judged & valued pretty much on your revenue alone. Which is usually low (startups are hard) and unsexy (so not a ton of buzz).

Not saying a agree with it. But that's how it is.

[https://news.ycombinator.com/item?id=5236239](https://news.ycombinator.com/item?id=5236239)

<comment><AUTHOR> The most interesting thing, to me, about the current valuations, is where they're going to be in another 6 or 12 months of this momentum. Yellen is highly likely to maintain the negative interest rate environment for years to come, and that should encourage a stock market move even higher.

Motivated bull markets never stop at a bit above historical average values. They go a lot higher, become quite irrational, and then crash. As it is already, about 85% of the gains in the market over the last two years have been pure PE expansion, as earnings growth has tumbled to low single digits.

I expect valuations for tech companies across the board to get significantly frothier before the music stops again. If a company like Snapchat is worth $3.x billion today, I see no reason to think capital won't bid it up to $5 or $10 billion over the coming year, assuming the very accommodating environment continues.

</comment></comment><comment><USER3> "This year, shares of newly public technology companies are being valued at 5.6 times sales, estimates University of Florida professor Jay Ritter, who tracks IPOs. That is well short of the median of 26.5 times sales in 1999."

At least the WSJ feels obliged to put facts in their articles, even if they contradict the headlines.

<comment><USER4> How exactly does that contradict the headlines: "Silicon Valley: Feel the Froth: Tech Valuations Stir Memories of 1999, but There Are Some Differences"?

<comment><USER5> 5.6 times revenue is a fairly cheap price for a fast growing company (historically, on the average, ceteris paribus)

For example, P&G is currently trading at about 3 times revenue.

<comment><AUTHOR> One of the problems with that 5.6 number, is how tilted down it is by larger slower growth companies carrying much lower ratios. Some examples:

Facebook: 20 | Workday: 40 | LinkedIn: 27 | Yelp: 30 | Pandora: 9 | RetailMeNot: 12 | Salesforce: 10 | Splunk: 25 | Rocket Fuel: 15 | HomeAway: 8 | Baidu: 15 | Priceline: 10 | Sina.com: 10 | Youku: 11

Twitter: 15? ($650m in expected sales or whatever, $10b assumed valuation)

So is there a bubble in a certain class of tech companies? I think frothy is the right word for now. The valuations are clearly very high, but not 1999 high. Right now it reminds me a lot more of 2005 > 2007.

<comment><USER5> Data source? What are their growth rates?

</comment></comment></comment></comment></comment><comment><USER6> "Some people worry that the looser rules may end up hurting small investors."

LOL bagholders will always find a way to set themselves up as bagholders, all you can do is shove them in or out of certain markets. When you look around the poker table and can't figure out who the sucker is, and you're only at the poker table because its trendy and cool to play poker right now, guess who the sucker is?

Just like real estate always goes up (until it doesn't) tech IPOs / valuations only go up, so by greater fool theory you should put all your money into whatever is going up because you can always sell to a greater fool at a profit (until you can't)

If you use EPA/OSHA/NAFTA/whatever to eliminate all other resource extraction industries, you end up with a bunch of sharks extracting resources (money) from dumb investors. The same folks who would be selling the golden gate bridge to multiple people are stuck selling tech IPOs at this time.

</comment><comment><USER7> It seems to me that the surest indicator that a bubble is underway is people saying that it's not a bubble.

<comment><USER8> Is the converse also true?

People say that a bull market can't be stop until the last bear has been shot. (Then again, who are these "people" that keep saying things?)

<comment><USER9> Yes.

"The stock market climbs a wall of worry"

[http://www.investopedia.com/terms/w/wallofworry.asp](http://www.investopedia.com/terms/w/wallofworry.asp)

It will continue to go up as long as there are people who are afraid and have not put their money in. As soon as it is obvious the market will go up forever, then it will drop since there is no more new money coming in.

<comment><USER8> I wish there were an accurate way to measure this.

<comment><USER7> There are lots of people who claim they can, under the heading of "technical analysis".

</comment></comment></comment></comment></comment><comment><USER10> Valuations on AngelList certainly seem to be creeping relentlessly higher for Valley companies.

The typical pattern seems to be the following:

\- first a seed round of $500k with a convertible note

\- next a valued equity round of $1m at a premoney valuation of $6m

The general impression I get from this is that valuation has become divorced from reality. What seems to be driving it is that the founder/s just don't want to give up more than 25% of the equity for around $1.5m funding. In that sense they're kind of pulling numbers out of their nether regions to make the math work out.

</comment><comment><USER11> Well if not an IT bubble, surely there's a housing bubble. "Home prices in San Francisco and surrounding counties rose more than 15% in the past year".

That's the kind of increase we saw year after year just a year or two before the bubble popped, and prices fell by 50% or so (around 2005-2006 I guess).

It's funny how the majority just assume prices will keep on climbing (I was one of those merry fools by the way), and in hindsight it becomes so obvious that such increases are not sustainable.

<comment><USER12> > That's the kind of increase we saw year after year just a year or two before > the bubble popped, and prices fell by 50% or so (around 2005-2006 I guess).

IIRC, while prices in many parts of the state fell by that much or more, prices in San Francisco did not (and the much smaller amount they did fall in SF was much later than the general bubble collapse, around 2008-2009, as a result of the general economic slowdown _caused by_ , among other things, the collapse of the real estate bubble nationally, not because there actually _was_ a bubble in SF particularly -- SF prices were pretty flat, IIRC, 2005-2008.)

</comment></comment><comment><USER13> "Froth" as in lots of bubbles? One little bubble collapsing wouldn't necessarily blow out the rest, unlike a singular bubble.

Or "Froth" as in "frothing at the mouth" (from insanity and/or rabies)? Given the silliness, this is equally applicable.

From having worked on a trading system in the late 80s, I know that investors (and traders) at the retail level work at a gut level and would see market moves very shortly after news items would tick across on the Reuters feed. I would argue that this article is intended to be like spraying valium into the zeitgeist for the inevitable collapse. If they can grab mindshare with this "foam" concept, they may very well be able to isolate failed IPOs to companies (without real profit) in limited segments.

</comment><comment><USER14> Original article here:

[http://online.wsj.com/news/articles/SB1000142405270230447050...](http://online.wsj.com/news/articles/SB10001424052702304470504579161880453868414#printMode)

</comment><comment><USER15> Meanwhile, the amazing Nokia, was traded by bananas (7B) , while Twitter has a market value of 11B ?? WTF

</comment><comment><USER16> To me, the obvious sign of the bubble isn't the high valuations, but the asphyxiating red tide of MBA-culture people who are in technology for all the wrong reasons.

They're an invasive species. They come in during bubble times, compete successfully for attention and funding, because they have superior social polish (and, more importantly, can exploit the "just like me" bias of chickenhawking VCs) to the real technologists, build a self-referential junk- pile of nothing, and then leave just before the silly bubble-world they've created collapses.

Then real technologists get a few years of relative calm and meritocracy (although there's not nearly as much money in it, then) before the cycle repeats.

Technology is incredibly rewarding and I wouldn't want to be in any other career, but it's _hard_ and you gotta be real to get any good at it. It takes years of realness-- hard work (often unrecognized) that kicks your mental ass-- just to get the basics. When people who aren't real try to come in and get the rewards-- Harvard MBA CEOs who don't even understand linear algebra setting themselves up as "data whizzes" because they were able to hire smart people-- it's irksome.

<comment><USER17> This... I've met them, I've seen them. They are scum.

I've noticed they tend to ingrain themselves into startup news and blogs or similar things.

I know some MBA's that run some startup news site in Stockholm/Sweden as well as their own startup. Really disgusting personality.

Really fits into the mild of "superior social polish and exploitation".

<comment><USER11> I don't entirely understand. Is it wrong of them to run a startup news site while having their own startup? If so, why?

Or is that unrelated, and it's just that these particular guys are not very nice?

<comment><USER18> I think it is the latter.</comment></comment></comment></comment>


10 Best Practices for Peer Code Review - <AUTHOR> http://www.slideshare.net/SmartBear_Software/10-best-practices-for-peer-code-review

<comment><USER2> Good points. Can't emphasize enough the need for annotations and smallish patches. The worst for the reviewer is a 2kloc patch touching several dozen files without any annotations.

Positive culture is very important too. Invariably I found that the best way to start a discussion is with a question: "why did you implement it that way?" instead of "this code is wrong/bad/unreadable". Another mistake: starting with trivialities such as deviations from coding style. Spotting stray tabulation is easy, spotting a bug or suggesting better architecture is hard. Lastly, remember that the author has got something working and your suggested changes can introduce bugs, so this possibility should be weighted against potential "improvement".

Giving a good code review is as hard as writing the code in the first place.

</comment><comment><USER3> I'm not sure I agree with number 4 "Authors should annotate source code before the review begins".

This source code will live on beyond the code review. If it requires annotation for the code review to occur, how will it stand up when the next dev comes along to make changes. Is the next dev expected to revisit many of the recent code reviews including the changes?

Some context, or annotation, could be good to have in the commit message.

In most cases, I believe the changes and the code should live on their own, without annotation.</comment>