search

TechAndCheck / tech-and-check-alerts

Daily tip sheet for fact checkers
MIT License
13 stars 6 forks source link

Update technical architecture document #57

Open reefdog opened 5 years ago

reefdog commented 5 years ago

We've already learned and changed some after creating our initial technical architecture. We should make sure it reflects reality.

slifty commented 4 years ago

@reefdog now that this is getting a bit more fleshed out, could you update this?

Also... What is the tool we're using for the technical architecture? Right now I don't feel like I would have the ability to update this diagram which I think reflects a lottery-weakness in the project.

reefdog commented 4 years ago

I used Shapes, because it's $10. We should decide on a uniform tool; Shapes is hardly standard (or terribly professional), but OmniGraffle (which is both of those things) is quite expensive. Both of those are Mac-only, which isn't great.

I don't know of a good cross-platform diagramming app; for our architecture (which is fairly simple), maybe we use a cross-platform or browser-based drawing app instead? In which case I'd recommend Figma, and would be happy to convert this to Figma and update it there.

slifty commented 4 years ago

I'm going to ask around to see if anybody has FOSS solutions to this problem that they would recommend.

reefdog commented 4 years ago

That's a good call.

Meanwhilst, it looks like Figma has a template and examples for building AWS diagrams after all. (Ours shouldn't be an "AWS diagram" since we may/will interact with non-AWS services, but it's good to have examples of using it as a technical architecture doc at all.)

kfogel commented 4 years ago

FWIW, I've come to like Dia, which is FOSS. It took me a little while to become fluent, but now I actually enjoy using it.

You can see some examples of dia-made images in this folder, and the usage notes in this file may be useful too.

Happy to answer questions about it.

slifty commented 4 years ago

Thank you @kfogel this looks like it may well be perfect.

@reefdog I know there may be a bit of a learning curve for this, but I do think that the FOSS and cross platform nature of Dia makes it the right fit for this particular task since we want something that can be updated over time by whoever is maintaining the project. Feel free to push back for another option if you think it's best.

kfogel commented 4 years ago

You're welcome, @slifty.

The main usage tip I have is probably an obvious one, but I'll offer it anyway:

When using Dia to make architecture diagrams or any other kind of diagram that involves a lot of duplicate uses of a small set of objects (you know, cylinder for storage device, file cabinet for database, whatever), just keep one dia file (or layer) that is a library of those pictures, and copy from there as needed. There's an initial investment in setting up that library, but then you can cruise through making new diagrams as needed.

reefdog commented 4 years ago

Yes, thanks @kfogel! Total agreement that a cross-platform FOSS app with an open file format is preferred. Besides Dia, I also saw LibreOffice Draw recommended, and decided to give both a try on macOS.

Both satisfy the FOSS / open file format requirement, though neither can open each other's files (.dia and .odg, respectively). Dia comes in at around 100MB installed (besides X11), while LibreOffice (which must include the entire suite) is 700MB.

Installation of both is fairly simple. Dia requires X11, which is no longer bundled with macOS and hasn't been updated in three years, but can still be installed with brew cask install xquartz; then brew cask install dia (or download from the site). (Some people have to do further configuration, but I didn't.) LibreOffice was a quick brew cask install libreoffice (or download from the site).

My initial impression is that LibreOffice is far more nativized to the host OS. It feels like a Mac app, and I imagine that on Linux and Windows it feels like a native app for those platforms. Dia feels like an X11 app: non-macOS-standard keyboard commands, dialog boxes, etc.

The concern there is partly usability/aesthetics, but also which app is likelier to stay atop platform changes, such as Apple's recent bevy of macOS restrictions (killing 32-bit support; requiring app signing; etc.).

In summary: I like that Dia is focused on diagramming (while LibreOffice brings along a full unwanted office suite); but also like that LibreOffice feels more at home on each OS and seems to be maintained more regularly. My vote would be for LibreOffice, but I'll happily go along with the team.

reefdog commented 4 years ago

(It strikes me that none of that was an exploration of their diagramming capabilities. That's because our needs are pretty light and periodic, and so our primary concern is actually more how quickly fellow team members can get setup and contribute changes to the document then how complex of architectures it can generate.)

kfogel commented 4 years ago

No opinion on the question of dia vs LibreOffice Draw, since I've never used the latter, but thanks for writing up this exploration, @reefdog.