MkDocs VS Nots.io

MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file. Start by reading the introductory tutorial, then check the User Guide for more information.

Nots.io is a SaaS for engineering teams aimed to help keep project docs up-to-date by linking them to the source code.

Often times 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, 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.

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. Choose image, PDF, GoogleDoc file. Import description and discussion from GitHub pull request. Get links from jira issue numbers. We know that docs could be spread across many places. Now 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 right from the IDE or from our site.

We also track the relevance of each added document. When 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.