Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Is there a better way to document complex software architectures?

news.ycombinator.com

Post reply on HN
Print view View original

221–230 of 239 posts

Re: Ask HN: Is there a better way to document complex software architectures?

#221

Post by taeric »

jonathanlydall wrote: post #210
taeric wrote: post #52

Earlier quoted context omitted.

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.

The main reason is that our "code management" (essentially code weaving) system allows coders to painlessly mix their own custom code in the same file as generated code. This is very useful for cases where you want to model signatures of methods in our tool, but then leave it to the developer to implement the method which performs the business code. If you want to change the signature of the method, for example addin…

This sounds like a large part of the reason is you deliver the code to others, but don't want to deliver the tool you used to make the code. This makes sense to me.

For the other cases you gave, that sounds like what Interfaces were made for. :) Granted, I think we are in a world where tooling not necessarily requiring language constructs is a better place.

Regardless, if you are seeing such success, I would be greatly interested in seeing you open up that tool.

Re: Ask HN: Is there a better way to document complex software architectures?

#223

Post by sagichmal »

agentultra wrote: post #172
sagichmal wrote: post #137

Earlier quoted context omitted.

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

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…

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

That's obviously a lie.

Re: Ask HN: Is there a better way to document complex software architectures?

#224

Post by jonathanlydall »

taeric wrote: post #221
jonathanlydall wrote: post #210

Earlier quoted context omitted.

The main reason is that our "code management" (essentially code weaving) system allows coders to painlessly mix their own custom code in the same file as generated code. This is very useful for cases where you want to model signatures of methods in our tool, but then leave it to the developer to implement the method which performs the business code. If you want to change the signature of the method, for example addin…

This sounds like a large part of the reason is you deliver the code to others, but don't want to deliver the tool you used to make the code. This makes sense to me. For the other cases you gave, that sounds like what Interfaces were made for. :) Granted, I think we are in a world where tooling not necessarily requiring language constructs is a better place. Regardless, if you are seeing such success, I would be great…

Here a recording of one of our guys on a webcast and it also shows the tool in action: https://www.youtube.com/watch?v=vA3L8_DaECQ

"No lock in" is an important aspect for us. We know of some other big players with "RAD" type tools which "generate" code, but unless one continues using their tool, the code they're left with is effectively unusable. Their business models are also often around runtime licensing.

As devs, building a tool for other devs, we want our tool to continue to be used because people clearly find the value in it, not because they feel locked in.

Re: Ask HN: Is there a better way to document complex software architectures?

#225

Post by taeric »

jonathanlydall wrote: post #211
taeric wrote: post #207

Earlier quoted context omitted.

The tool should be referenced as a versioned dependency at build time. When it gets a new release, you do a new build. Complete with new tests. Anything you do that increases the time between the introduction of the bug and the finding of the bug will make it harder to actually fix it.

In addition to my reply above about code-weaving, rather than the all or nothing approach that some code generation techiniques suffer, our tool allows proposed changes to be reviewed before you commit with writing the generated code to your disk. This allows developers to feel in control of what's changing in their code base during generation, rather than being worried that some custom code is going to get wiped out…

That attitude is ridiculously commendable, major kudos.

My fear is typically around having "mixed edited" code. That is, code that is edited by hand and generated. I greatly prefer being able to know that the generated stuff is extended by language mechanisms and I will never really have even the ability to edit something that the generator will do. I have seen bugs in generated code, but I have always pushed to fix the generator, not just fixed the generated code. (That make sense?)

And, reiterating because I feel it is important, your position is awesome. Thanks for sharing!

Re: Ask HN: Is there a better way to document complex software architectures?

#226

Post by tmaly »

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.

Re: Ask HN: Is there a better way to document complex software architectures?

#227

Post by xtracto »

mattlondon wrote: post #139
cubano wrote: post #87

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…

UML Sequence diagrams are useful, if they are kept up to date and reflect reality. I find they are great for the initial "what the hell is this doing?" stage of coming to something new.

The best way I like documentation is via a docs/ directory within the repo. Uing js-sequence-diagrams ( https://bramp.github.io/js-sequence-diagrams/ ) to create self-contained one page diagrams (like this https://jsbin.com/jusiyusowu/edit?output ) which go into code.

That allowed me to include documentation updates in the code review.

Re: Ask HN: Is there a better way to document complex software architectures?

#228

Post by qznc »

sien wrote: post #165
mattdeboard wrote: post #155

Earlier quoted context omitted.

This is interesting. I ctrl-f'd for "self-doc" because I was wondering when we will start seeing Terraform, Puppet, etc., have options to generate a diagram automatically as part of their normal operation. Self-documenting infrastructure would be a godsend. My organization is challenged by the lack of documentation of our infrastructure, especially. edit: Most of the responses to the original post seem to be addressi…

It's already there with Terraform but it's not that pretty yet: https://www.terraform.io/docs/commands/graph.html

More evidence that graphviz needs a successor or makeover. Some force-based post-processing with the additional goal of rectangular borders would be good. Also some tweaks like little arcs where lines cross and shadows for boxes.

Re: Ask HN: Is there a better way to document complex software architectures?

#229

Post by slimbods »

derangedHorse wrote: post #160
henrik_w wrote: post #96

Earlier quoted context omitted.

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.

As someone who's been in software development for only a couple years by comparison, I don't see huge architectural changes happen too often for any of our products. This is something that I'm currently trying to improve upon within my company, but I've gotten pretty discouraged with all these comments lol. Is there any way to mitigate the obsoletion of these models?

Make a tool that generates architectural diagrams from the code?

Re: Ask HN: Is there a better way to document complex software architectures?

#230

Post by adaml_623 »

basdp wrote: post #122
jimjimjim wrote: post #103

Earlier quoted context omitted.

Shack - doesn't need an architect. House - some do, some don't. Commercial Building - yep. Factory, Bridge or Infrastructure - you're insane if you don't. Just like in construction, it depends on what you are building/expanding. Not all software is the same.

So you're calling (f.e.) Amazon a shack?

A shanty town?
Post reply on HN