Startup idea — this is what you can take from your past experience
Yeah, it’s been a while since last blog post. Building startup and a company take waaay more time than it was initially planned. This year and a half were full of wins and losses. In this blog, I’m gonna cover most interesting stuff happened to me and Nots.io team during this period. But first, let me step back and look at a larger picture, and show what drove me to the idea of building Nots.

Paul Graham once said that the best startup ideas have three things in common:

  • They’re something the founders themselves want
  • That they themselves can build 
  • And that few others realize are worth doing

In 15+ years of writing code for a living, I worked in teams of different sizes — from a team of two and small startups, to big outsourcing companies. I used a lot of programming languages and project management methodologies. Each new team was a completely new exciting journey.
At the beginning it was completely “chaotic” way of defining what to do, how to implement and deliver things. On the next job, we used home-grown trial-and-error project management and code management frameworks. One of my latest teams had strict rules defined by CEO and CTO of how to manage code and where to track errors — each step was defined in tight guidelines. 

Completely different on a first sight, all my previous experience has one thing in common: it was (and still is) really tough to share knowledge about what prerequisites for development we had, what spec or customer input was on the table, how developed modules depend on each other, what code actually does and why given decision was chosen among others? Of course, there are lots of different ways to share documentation around the project. I’ve tried many and here’s what I found.

Even though one can put some insights into regular code comments in source code, this makes code very noisy, hard to read and explore. This way has low expressive power. Sure, we have all that JavaDoc/JSDoc/DocFx goodness with reach formatting. But it requires really strong team culture to follow to maintain these docs in right consistent shape. The biggest downside is that this format is targeted more on extracted generated HTML page rather than on regular developer who just reads it in an editor.

 

 

Starting from mid-2000’s various wiki systems are gaining popularity. Really reach text formatting, easy linking between pages, self-hosted version, quick deployment. It seemed like a panacea and a great place to leave all the information in. Back then I was one of the originators of making locally installed wiki system DokuWiki (very popular at that time) a central place to share information about the project. It was really easy to add everything to it. Unfortunately, this knowledgebase became outdated and inaccurate over time.  It was really far from code — where all things happen. Was it a hotfix or a regular feature, every engineer should keep in mind to write or adjust doc in completely separate place — in the wiki. It’s tough, it’s annoying.

 

 

Next generation of wiki software comes with all-mighty Atlassian stack. It may seem that now it will solve all the problems. On one of my past jobs, we had strong requirement to describe every module we’ve done in Confluence — wiki made by Atlassian. It seemed really good: one can easily link between wiki article and for instance Jira task. But as with DokuWiki, it is pretty far from what every software engineer has to deal with on a daily basis. It’s not well integrated with the code. Wiki articles rather sooner than later get rotten. Especially when there’s an urgent need to change or fix something when the pressure to deliver the project on time is high and there’s no time to update docs (which also requires lot’s of time and effort).

Working in startup brings new challenges. The community around startups incentives everybody to use Skype/Slack/Email/PM tools/Google Docs/Asana/Dropbox, sometimes all at once. Not mentioning voice and video messengers. It’s cool, it’s trendy. 
For sure it’s super exciting to have a well-prepared specification in GDocs, collaboratively edit it and have no worries about where to put it. Everything is available in the cloud from any device. The downside is even more evidential: now your development team has dozens of different places where knowledge about the project is stored. It’s spread among a bunch of online services. And still, it is pretty far from the code. 

At the end of the day, I came to the conclusion that in order to track my own docs, tasks, files, and specifications reliably I desperately need some tool for myself. Just like a bunch of little yellow sticky notes stuck on a fridge door, it would be cool to glue a note on a line of code, function or class, file or entire git branch. 

Often times it’s really handy to link current code changes to:

  • Short aftermath after talking with management staff, design department, another engineer, support team
  • Spec and functional requirements in some online service
  • Screenshot, mockup or PDF with a guide
  • Code snippet or Stack Overflow thread with an example and explanation
  • Hotfix ticket, etc

After investigating all other products and options on the market I realized that nothing quite fit my needs so I decided to build Nots.io to keep, track and manage my notes.

The goal for Nots is to equip engineering teams with the right tool to speed up the development process and save money. It’s easy to leave a note to yourself with a spec, so after a while when this code ought to be updated, you can quickly find out this note with the specification and recall past architecture decisions. 
This works across team too: no need to spend time looking for an owner of some piece of code and communicating with her. For example, if one has to fix button position on a page made by another person. Developer opens HTML file behind that page in Nots, finds the mockup previously attached by the designer and places button correctly according to the design document. Easy!
Another positive outcome is that Nots reduces “bus factor”. When a key player suddenly disappears, the team won’t stall. Notes in Nots.io shared among all teammates, so everybody is on the same page. When a new developer joins a team and explores project’s code, with Nots a newcomer can easily find existing specs/guides/whatever linked, discuss those with colleagues and get up-to-speed quickly. Painless onboarding.
Since notes and code are tied together, Nots will tell you if a note became out-of-sync with linked source code, or even when it turns to not relevant anymore.  This drives everybody to always keep notes in good shape.

Right now Nots is still under development. I’m gonna keep blogging about interesting technical and management challenges popping on our way to the beta release. Leave your email below and stay tuned to not very frequent news and updates.