I've also had enough with various wikis. And at some point we didn't find a decent tool for documenting our projects. We decided to build our own tool https://nots.io (yay NIH syndrome). The main idea is to make possible to link any type of doc like plain or markdown text, files, google docs right with the code. To give all docs a clear scope. And make it easy to discover what code is documented from the site or IDE. 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), and let you know if the document is obsolete now.

We have a demo (https://nots.io/demo). Check it out, I'd love to get feedback.

Shameless self-promotion: That was exact problem I was facing during my entire career. That's why we decided to build a tool which links documentation and code -- https://nots.io This gives at least two benefits: now it's easy to find the right doc straight from the code you're working on. Also Nots tracks updates in code behind each doc, and marks the docs as obsolete if code has drastically changed.

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!

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.

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

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 :-)

Hi HN,

I’m Alex of 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!

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

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.