In mid-2018, when we launched the beta of Archbee, we had the vision of helping software developers and architects paint a better picture of their systems. With very little marketing, the product was well received, and as a result, in 5 months we've got over 3000 people signing up to use our product. We've learned a lot by talking to our most engaged users. We've learned a lot from studying other products in the space. We've learned a lot just by reasoning from first principles. We've learned a lot, and we're ready to tell you where Archbee is going next!
An overwhelming amount of users asked us for the ability to write some text that couldn't be expressed by diagrams. So we introduced a Markdown editor that let them put lengthier text right next to their diagram. This sparked a thought, and we quickly realized that diagrams are just a specific case of technical documentation, and we could be solving a bigger, more valuable problem for the world.
We made it our mission to help teams improve their technical documentation!
So if you think top down, the easiest way to document something is to just write some words about it. For example: our infrastructure is made of AWS Cloudfront, AWS EC2 connecting to AWS RDS. This could also be expressed as a diagram, and the diagram lets you imagine it faster, but when you have something more intricate to say, for example: we made the decision to not use AWS Lambda as we found out it would hurt user experience, the diagram is clearly not enough.
What if your DevOps team wanted to express the fact that you have a datacenter for each continent? Diagram doesn't help, words help, but they're not the best. That's why we have maps around. So maps with pins are another form of documentation.
What if you wanted to keep some genius whiteboard content that your team sketched on? Text is ok, diagram is not good, map is not good. But still, it's documentation that is valuable and hopefully will be kept somewhere, ideally with minimum fuss. Maybe take a photo?
What if your team is designing a system that will be gradually deployed but it's useful even after 20% of the work is done? You could put mini tasks into Trello or Jira, but we know engineers like to have stuff very close to where they work and just synchronize the documentation status right there.
What if a client asks for a new API endpoint and your team is just trying to come together on a solution on how it should look? Sure OpenAPI/Swagger can work as documentation but that's only going to show up after you've written some good part of the system and deployed it somewhere. You could send your client some sample JSON in a text file, but it's not the most efficient or nice.
How about when you come up with a rough draft of what a code API should look like. You could fire up an editor and do it right there. But then your iteration process suffers. When you hire new developers, they'll probably ask 'what they were thinking when they chose this?'. Sure you can put some comments in code, but maybe your manager needs to know as well, or QA people, or even your CTO. Should they just use git and read code as developers do?
To recap this big train of thought. You can represent any type of documentation with just text -- that's the swiss knife. But there are obviously better and more intuitive ways to represent 'some' concepts. Like diagrams, maps, photos, videos, JSON APIs, wimpy code editors -- those are the big guns. With the swiss knife, you can do anything that you can do with the big guns. The other way around doesn't always work, but it's often more efficient in communicating. That's why we need both.
This how we rationalized a new type of documentation editor. Dissecting software engineering teams' activity patterns, and creating a great user experience, which even the most hardcore VIM and Emacs users seem to enjoy. We hope you do too!
What should you do next? Just hop on the Archbee train and create a free account, you'll get value immediately.