
Show HN: Nots.io – a developer-centric look at how to document your code - with-point
https://nots.io
======
mc3
Hi Alex

Love the idea. I love there are people working on this kind of tool.

My biggest question is where the data is stored. I think the storage model for
the comments should be mentioned in the FAQ. If it is on your server only then
I don't think I'd use it.

I would ideally like the comments to be stored as metadata files committed to
the repo or inline with the code. I'd probably therefore prefer a tool-user-
based pricing model. And I think $100/y would be a fair price per user.

I don't get the repo based pricing. I could have a repo with a single docker
file in, or a repo with a million lines of C++. Having a lot of repos forces
me onto the expensive per-user licensing. It would be ok at $100-$200 /y but
$69/m === $828/y seems too much. That's 1%+ of a senior dev's salary in most
part of the world, for one tool.

~~~
with-point
Hey, @mc3

Thanks for your feedback! This is the reason why we posted our work on HN. I
really appreciate it!

You won't believe, storing Nots data as a separate git repo or as a metadata
was our initial thought when we were starting the project. But it quickly
became clear that it's too complicated, pollutes the repo, hard to query. Lots
of downsides. But we know that everything you entered is your data, and we
cannot lock you on the service. We're thinking of one-click export of your
current docs snapshot as a nicely formatted HTMLs. Maybe even make a recurring
task of sending such snapshots by email once in a while. Will figure it out.
Stay tuned.

As of prices, it's a fair point. Now it's clear that we have to review per-
user prices. And you're right, something around $100/y is fine. Thanks for
your suggestions!

~~~
mc3
Thank Alex for the response.

Looks like you have run up against a shortcoming of git itself. I accept that
you may need to store the data on your end for those reasons. If this is the
case it might be worth having that in the FAQ too, and convince me that you
ensure a decent uptime and that you can export the data nicely if you want to
move on later.

Good luck with it. Hope it does well.

~~~
with-point
Gonna make a new section in price FAQ with this question. Thanks for your
input!

------
with-point
Hi HN,

I’m Alex of Nots.io ([https://nots.io/](https://nots.io/)) Nots is a SaaS for
engineering teams aimed to help keep project docs up-to-date by linking them
to the source code.

The problem: During my career, I saw so many times, how the company’s docs and
internal knowledge pile up in some knowledge base, wiki, google docs or simply
in .md files in the repo. And after a while, everything turns into a mess.
It’s hard to find the right document and determine whether it actually covers
the code developers are working on right now. When you find something, it’s
tedious to detect if the document is not outdated and everybody can trust it.

That’s why a few friends and I decided to build a tool to reflect our look at
the documentation. With Nots.io it’s possible to link any type of doc directly
with the code. Make a short note or full-blown markdown spec right at the
site. Upload an exiting image, PDF or import GoogleDoc file from your GDrive.
Automatically import description and discussion from GitHub pull requests. Get
links from jira issue numbers. We know that docs could be spread across many
places. Then in the system select several lines of code, whole file, commit or
branch and link the doc you have with the code. Now all docs have a clear
scope. It’s easy to discover what is documented from our site or right from
your IDE (right now we have plugins for VSCode and IDEA). Open a file, and if
there’s a document for a line(s) added before, you’ll see an icon. Click and
get the documentation!

We also track the relevance of each added document. When new commits come in
and the code behind the doc changes, we decrease its relevance factor (we call
it the fresh-rate). This answers whether the doc is fresh today, and you may
rely on it. All this keeps the documentation up-to-date.

As a Product Owner/Business Owner I’m currently using this tool for leaving
and exploring documentation for Nots. Would love to get your feedback!

~~~
Jaxkr
What kind of information is this best suited for? What is best to use nots
for, and what belongs in a comment?

~~~
with-point
Any information around the code: short text or link on what code does. The
bigger technical specification in markdown. PDFs/images/GDocs that describe
why code looks the way it looks.

You're using some non-standard language feature -- document! Choosing a
library over its competitor -- leave a note! Re-writing or re-implementing a
module, making some tradeoffs in code, dropping an existing feature -- all
this should be saved in docs. For the future-you, for your colleagues, for the
newcomers, for teammates who work remotely.

We make this internal "tribal knowledge" to be accessible for anybody in the
team in a couple of clicks.

------
verdverm
How do you justify prices per user that are greater than GSuite+GitHub+ZenHub?

Seems super expensive for adding icons/links to my code editor (I actually use
vim, so no support)

~~~
with-point
We have 2 levels of prices:

\-- per project, no matter how many teammates involved into documenting stuff

\-- per user, if you're quite big org and have lot's of colleagues and lots of
repos/projects.

If your entire team saves at least one hour per month searching for
information or finding answers in knowledge bases, then this costs more than
your expenses on Nots.

We're a self-funding startup and not going to sell your data to G or
Microsoft. We're working hard on new integrations and new plugins. Especially
for vim, as I'm also a vim user since early 2000s.

But if GSuite+GitHub+ZenHub entirely fit your needs, you can quickly find
documentation for the code you're working on right now, and they give you the
document relevance info, then I'm the first person who will advise you use
this stack. Because our main goal is to make engineers more productive,
probably with our tool. And certainly to keep documentation up-to-date :-)

