What are notes?
In terms of Nots, a single piece of knowledge, that added to the system, is represented as a note. A note could be a short text message, like a yellow sticky note on a whiteboard. Or a bigger article with rich-formatted text, links, attached images, and PDFs. Here’s a brief overview of the notion of notes.

So small notes in Nots are useful when you want to leave a quick memo to your future self. It’s like a code comment we all do in text editors and IDE’s every day, but more robust. Ever wanted to stick a link, an image, or an stack overflow answer to your code? It’s not quite a good idea to place that into the code comments. Sometimes it’s not even possible, like pasting an image into the code. Sometimes such comment may look inappropriate.  But this is an ideal case for making a short note in Nots and leave your code clean and elegant.

Another use-case is when there’s a need to put a larger piece of documentation, like technical spec or rationale of a big feature. We encourage engineers to leave this kind of docs in Nots, rather than making huge javadoc/rdoc/phpdoc blocks in the source code. These chunks of docs pollute the code, make it less readable, increase cognitive load. Code alongside with extensive documentation is hard to read, hard to reason about, hard to navigate through

 

 

Here’s bird’s eye view of Elixir’s Mix module. The actual code is highlighted with red. Everything else is doc blocks. 

 


 

A note added in Nots has a clear scope — you can always find out the strictly defined lines which are covered by the documentation. When the source code changes inside the defined scope, either by you or by your colleagues, Nots handles these changes and updates the scope. 

Based on these attached notes, the system does reasoning about the relevance between the current state of your source code, and the linked documentation. In case if the note is linked a long time ago, or if the fragment of code underneath has been changing pretty heavily, Nots substantially decreases the relevance indicator. We call it fresh rate: it goes from 10 when everything is fresh or just added. Down to the red value of 1, when the code changed so drastically, that it’s better not to rely on this doc.

Fresh rate not only makes everyone in the team confident, that everything described in the attached note is up-to-date. Nots also computes the overall fresh rate of the project. Wit classic knowledge-bases and wikis, you never now that it’s time to take care of your docs. And usually you never do. In Nots, when there’s lot’s of stale notes, the project’s fresh rate also drops. This and lots of notes with orange and red fresh rate markers in the interface provokes engineers to put efforts to return docs in good shape, by constantly reviewing and adjusting outdated notes.

 

 

Volkswagen's diesel graveyard   Lucy Nicholson / Reuters

Oftentimes when docs stored somewhere else in the knowledge-base system, dropbox/gdocs/slack or a wiki, you have no answer whether the information you found there fits with what you actually see in the code. Quite frequently this systems unintentionally become a junkyard with what used to be a topnotch collective knowledge about your code. No links between docs and code. No quantitive measure of accordance with the actual state of things like the fresh rate. All these makes these systems barely helpful. 

Notes in Nots were designed to preserve this relation, to have firm boundaries, to give you answer what the code actually does and whether the team could rely on the attached documentation. We endorse everybody to do docs because they pay you dividends. But do it in a proper manner with nots.io

Read our guide on how to set up your first project and explanation on how to create a note.