Hacker News new | past | comments | ask | show | jobs | submit login
Technical documentation that just works (squidfunk.github.io)
208 points by dedalus 6 months ago | hide | past | favorite | 77 comments

This tool seems like it is a nice markdown based CMS but I don't see too many features related to the more difficult parts of doing technical documentation. Like having working code samples.

I attempted a Kotlin centric documentation framework a while ago to address this: https://github.com/jillesvangurp/kotlin4example

I mainly use it to generate the documentation for my Elasticsearch Kotlin Client (jillesvangurp/es-kotlin-client). The idea there is that all examples and source samples are correctly compiling Kotlin code that I can get the output of when they run (e.g. a println). Running the tests, actually generates the documentation markdown. Using a dsl and multiline strings, I can mix lambda code blocks, markdown, or markdown inside files. For the lambda blocks, it figures out the source and line numbers using reflection. But it can also grab source samples based on comment markers. For bigger blobs of markdown, it's easier to grab the content from markdown files. For smaller sections of markdown, I can use inline multi line strings or a Kotlin DSL.

The main benefit of this is that my examples update as I change and refactor the code base. Also, since it runs as part of my tests, I know when examples break.

MkDocs has a good plugin system, and it's definitely possible to add a plugin to check each code block according to some rules. I know because I made one :)

https://oprypin.github.io/mkdocs-code-validator/ https://github.com/crystal-lang/crystal-book/pull/503

Basically you have three approaches to tackle code samples in markdown files:

1. run the code with some kind of plugin as part of your doc pipeline

2. generate documentation from your code

3. take some kind of hybrid approach

I went for 3., annotate snippet "areas" in the source code of a project (mainly in tests) and extract the snippets to a folder, e.g. into the mkdocs folder. I commit them to the (docs) repo. If the project changes, usually I fix the tests and update the snippets in mkdocs. This way I can be sure that the code in the documentation is actually working and people can copy&paste it. To scratch my own itch, I (surprise, surprise) created a script and even packaged it[1].

[1]: https://pypi.org/project/snex/

True, Material for MkDocs doesn't have a working out-of-the-box solution for working code examples, as it's a language-agnostic theme for documentation, but it shouldn't be too difficult to integrate [1].

[1]: https://dev.to/yysun/make-code-run-in-your-docs-4800

same, and with the trend like replit or small interpreter (graalvm or else) I kinda foresee a potential wave of notebook like docs

live snippets (brett victor hello) or even ability to try permutations of inputs to get a feel

and maybe .. metalevel generated live tests.

I feel like there is a huge market for something as powerful as confluence but not as terrible as confluence.

https://en.wikipedia.org/wiki/List_of_wiki_software Try some of these first before coming up with yet another wiki software.

Yes, and I'm currently building that [1].

But there are a few alternative to Confluence today. Whether it is Notion (not too good for technical documentation, true), Slab, Clubhouse (not the audio app) or even Quip. They mostly fit companies which are under 150 people. Managing documentation with an external tool is hard because technical documentation is better when closest to the source code

[1] https://dokkument.com/

I’m very interested in seeing how Dokkument turns out. There are too many documentation tools that:

1) have horrible navigation 2) lack a good editing experience / CMS, especially when working with a lot of images & videos. Markdown is actually distracting in this case because I have to break my workflow to upload these assets to my CDN. 3) are not designed to meet the needs of product marketing - they can’t have analytics added or they can’t be branded to match the rest of the marketing website.

Maybe I just haven’t found the right tool yet.

That's an interesting question. You need to differentiate two types of tools.

1. Internal knowledge bases. 2. Customer help centers.

1. are internal only and usually a tool like Confluence, Notion, or Sharepoint is used. Except from Sharepoint their designs are not very customizable. Because that's not the main use case of these tools

2. are customer facing and is usually easier to customize. There are plenty of tools but they mostly follow the initial "intercom" [1] help center design. A few categories with a bunch of articles and folders inside. They are usually not really great tools. On the navigation part there are still a lot of innovation to be done because we still don't know how to orient people who are novice

[1] https://www.intercom.com/help/en/

Thanks for clarifying. That’s exactly the problem that I’m facing. There really needs to be a third option that doesn’t follow the Intercom style of docs that is also suitable for marketing use.

In an ideal world, navigation would be chapter-style, similar to Stripe’s docs.

I’m currently using Docusaurus as my public docs site, but it isn’t ideal because 1) it’s cumbersome to manage a lot of uploaded content and 2) it is not particularly easy to manage the navigation.

I’m thinking of rolling my own within my marketing site (that’s built in Gatsby) and using a suitable CMS but I’d certainly like to avoid the time investment.

We use Quip and the difference with Confluence, which we used before, is that the rest of the organisation (the non-tech departments) adopted it really quickly.

That told me that Quip seems to be much more intuitive and easier to use for less technical people.

I agree. Gitbook/Readme are best solution I found so far. I like more gitbook, but they could improve the I18n support.

I see all missing a way to create other pages for content marketing (e.g. Academy, Blog etc..).

quip and slab (to a lesser degree, guru) are better experiences, but literally none of them will let me CI my codebase's documentation, or even so much as upload a zip file. It would be very nice to host private documentation in a linkable format, but behind a login, since, it is private documentation.

Has anyone a good idea about how to document high level architecture. I want something to document a huge web of interlinked pieces. E.g. this application is linked to this URL, which has been deployed on that server, connects to a database there, which has DNS aliases X Y Z, etc... Bonus points if it can scan our environment, and warn me when something has changed.

Some details: Our company is still firmly architected around the 'pets, not cattle' server philosophy, we have tons of teams each owning a small piece of the puzzle, people come and go. Hence,every time something changes, we spend a lot of time on architecture archeology to find back our own application.

There is some work done around the 4+1 view, but its all in word documents, mostly declared holy and locked down so nobody is allowed to update them or even look at them once written, and no 2 people agree about what 4+1 actually means.


I've actually just tried something similar for work (we'll see how it goes).

Take Material for MkDocs with the "mermaid2" and "plantuml-markdown" plugins, a custom plugin to inline SVG diagrams [1], and "mike" for versioning.

This gets us a Git repo where anyone can draw and contribute diagrams with either Mermaid, PlantUML, or Draw.io diagrams embedded in SVG. Hosted in GitLab Pages for access control.

All three diagram formats support hyperlinks in their outputs, so we're aiming for a clickable, "zoom-able" adaptation of the C4 Model [2].

It's a bit fiddly to get going, but quite nice and easy to work with afterwards, provided individuals can commit time to updating the diagrams.

In principle, GitLab supports PlantUML with extra config, and SVG embeds, but in practice we can't yet commit to updating our self-hosted GitLab, and the SVG embed is aggressively filtered - so Draw.io embeds often show up blank. MkDocs solves the "make it pretty, browseable, and searchable" aspect. Git and "mike" solve the "what was the original design again?" aspect.

I'm tempted to write the approach up, but I broke my blog - perhaps I should rebuild it with Material for MkDocs :)

The Material for MkDocs Insiders program gets you nice extras (mermaid support built-in, stay-on-same-page across "mike" versions, and more) [3]

[1] https://pypi.org/project/mkdocs-plugin-inline-svg/

[2] https://c4model.com/

[3] https://squidfunk.github.io/mkdocs-material/insiders/

(edit: typos)

Thanks. This is an alternative vision compared with what I am doing, but it seems better. Especially the C4 model as basic philosophy, and then the supporting technology.

Pleas blog about this, it is very interesting to me.

Just to be sure: this is what you mean with Mike?


Yep, that's the one - the versioning was more important to me than it might be to others (even internally). mike was a bit confusing to set up in CI since it re-commits the build back to a branch (imagine the loops you could get yourself into) but the output is nice.

We're not strict about C4 (we actually created an alternative-but-similar flow incidentally) - but C4 to me is a nice diagrammatic principle of "Don't Repeat Yourself" - draw a box, label it, and link to that system's diagram instead.

I could go on for pages / hours :D I'm a bit over-passionate about documentation. Email's in my profile, FWIW.

Thanks, this is similar to what I have started to work on. Note GitLab supports a Kroki integration, which is a powerful way to enable "all the things" wrt diagramming libs.

High level architecture documentation is the most-needed and least-done. Some ideas:

- one piece of (longish) sample code that uses each stage. It can also be an end-to-end test (not unit) and so forced in sync

- "Design Patterns" - unpopular now, but the whole idea was common idioms so everyone can tell what you're doing.

- very separate modules, with good names; interacting via simple APIs, with good names. Choose these names from outside the implementation, as if by someone who doesn't know it. The names will tell you what it is and what it does.

Shell scripts!

I prefer a diagram on a company wiki that contains only text boxes and connections. Accessible and editable by anyone in the browser (we use draw.io plugin for confluence).

I accept that these diagrams will always be out-of-date and therefore try to keep text and details to a minimum. I think of it more as a pointer for where to "dig up" a piece of the system or who to ask, to use your metaphor.

You can use DGML with Visual Studio, then export that as SVG and even animate the SVG like this https://microsoft.github.io/coyote/concepts/actors/state-mac...

I use PlantUML. I ignore the UML bit and just use it for code-based diagramming.

This is a good answer. Ditch the tools graphical tools that store diagrams in a proprietary or image-centric format. Diagrams as text that can be effectively managed alongside code in git or whatever version control system you used

For more complex technical documentation AsciiDoc would be a better fit than markdown. A simple table with code blocks is not possible with markdown, for example. I think the target audience is pretty much the same as for AsciiDoctor.


Especially when combined with Antora (https://antora.org).

Not to downplay what seems to be a nice tool, but bundling markdown files into a static site is the easy part.

What I would love to see is a way to combine markdown pages with source-generated API docs from multiple languages.

In my case, we have Ruby, Java, Scala, Kotlin, Clojure and JS. All of these have their own independent ways of generating API documentation. It would be wonderful to bundle this all up into one static site, and able to reference classes and methods in any language and have it link together.

That would be https://mkdocstrings.github.io/ except it currently doesn't have implementations for any of those languages.

That could be done with Hugo, if the generated API docs are placed into the static assets folder of the Hugo project. I think you are looking for a tool that would support it out of the box, but it shouldn't be to hard to set up.

Then you’ll end up with lots of micro-sites with very different designs and no unified search.

This actually looks quite nice. Works perfectly without JavaScript, looks good on mobile, and uses just plain Markdown files. For comparison, the official MkDocs page doesn't work well without JavaScript.

I think the tablet viewport (aka desktop-not-maximized) could use bit more love, and it's strange to include a dark mode slider and not respect my system dark mode setting, but these are both pretty minor overall. Good job.


> I think the tablet viewport (aka desktop-not-maximized) could use bit more love

IMHO, layouts for tablet viewports are often quite frankensteiny and hard to get really great. Is there anything in particular you feel could be improved?

> it's strange to include a dark mode slider and not respect my system dark mode setting

Material for MkDocs can do that [1], but I've disabled it for the documentation as I like the actual documentation for this tool to have the what I'd call "canonical" styling.

[1]: https://squidfunk.github.io/mkdocs-material/setup/changing-t...

Sure, when I open the page in my browser window (1223px), I have left and right sidebars. Now I zoom in so the font is a size that I like (new viewport is 980px) and I only have a right-hand sidebar. So far so good. Except, if I refresh the page, now the right hand sidebar goes away for some reason. Zooming back out now results in the right-hand sidebar appearing but the left-hand sidebar staying hidden.

So there's some weird inconsistency in the layout, but the upshot is if I bookmark the page and return to it (or open a link in a new tab), I don't get a right-hand sidebar.

If I did get a sidebar, I'd prefer it to be the left-hand sidebar than the right-hand sidebar, but that's more personal preference.

Just to clarify: the left-hand sidebar is the navigation, which collapses into the drawer behind the hamburger menu icon on breakpoints below 1220px. The right-hand sidebar is the table of contents which lists all anchor links specific to the page.

> Except, if I refresh the page, now the right hand sidebar goes away for some reason.

That is very weird and not intended. I just tried to reproduce the behavior (macOS, Chrome), but to no avail. If you have the time, it'll be great to have an issue with steps to reproduce (and possibly a screen capture), so we can fix it!

You know, I just tried and can't reproduce in Chrome either. I'm able to reproduce in Safari, and now having successfully nerd-sniped myself I'm pretty confident it's actually a bug in Safari. The `@media screen and (min-width: 60em)` doesn't update its definition of an `em` when the page is zoomed in or out, so zooming the page gives more pixels for the "min-width" part, but the "60em" is still being treated as the original zoom level.

Jup, that's sadly a still unfixed bug in Safari [1]. Super annoying, but if we would use px for media queries, we would have to swap out all rem units with px, thus not respecting your default font size.

[1]: https://adamwathan.me/dont-use-em-for-media-queries/

Why use this over something like sphinx[1], which has quite a rich and established ecosystem? Combine with Furo[2] and it even looks quite similar.

[1] https://github.com/sphinx-doc/sphinx

[2] https://github.com/pradyunsg/furo

Sphinx is Python-specific, and yes, in that instance much more powerful than MkDocs. MkDocs is a general documentation solution, which is language-agnostic. Also, Sphinx is normally written in rST with a steeper learning curve than Markdown, which to my knowledge is preferred by many users (especially non-technical people). As always, YMMV.

The Furo theme is rather new and borrows some things from Material for MkDocs, for example Admonitions. There's also Material for Sphinx [1], which is a port of Material for MkDocs to Sphinx. Note that it doesn't include all features Material for MkDocs offers.

[1]: https://bashtage.github.io/sphinx-material/

MyST-Parser/MyST-NB provides a great environment for extensible markdown with Sphinx (fully supplanting any need to work with rST). Combined with sphinx-pydata-theme, you get a clean look with little configuration. We use this for some large C projects (with and without Breathe), though the Sphinx apidoc ecosystem is indeed better for Python. (Material is great, but comparison with Sphinx isn't so clear-cut.)


Sphinx supports more than Python. Also RST is not particularly hard to use in comparison to markdown, and the extension mechanism is typically better.

The Linux kernel is documented using Sphinx. So it isn’t really 100% Python specific.

This is a nice tool. Is there an advantage over a static site generator like hugo with a documentation theme? I mean despite the fact, that this explictely targets documentation...

e.g. https://themes.gohugo.io/doks/ or


I've been exploring a lot of these tools recently and it seems like there are two ideologies. Hugo, and many others in the jamstack/SSG space, are basically full-fledged content management systems. These come from a long line of tools all meant to basically replace Wordpress in a content-focused workflow. This means they support a lot of bells and whistles with document schema (categories, tags, site maps, etc. etc.) and taxonomies. There are even workflows like draft posts, setting future publish dates, etc. (again very Wordpress inspired). You could build a recipe collection site just as easily as a technical documentation site with hugo for example.

On the other end of the spectrum you have tools like MkDocs (or mdbook, docsify, docusaurus, etc.) which are more focused on technical docs in markdown format. These tools put much less emphasis on schema, layout, taxonomy and really try to go from a pile of simple markdown files to a rendered site with as little friction as possible. You typically just lay out files in the filesystem, make simple markdown links between files, and the tool takes care of all the details of building a doc site like layout, rendering, linking, table of contents, and even search.

The big tradeoff between them is complexity. There's a _lot_ to learn to fully use something like hugo. You can spend days going through all of its features and building complex asset processing pipelines, themes, taxonomies, workflows, etc. But this is also a bit of a downside if you just want to turn some markdown files into simple technical docs--you have to do a bit of organization, add frontmatter, and learn a few hugo quirks. You'll have a fancy base to really go wild and add tons of content... but for technical docs you might not need all that power and complexity.

MkDocs strikes a really nice balance in this regard--you basically just write markdown files with simple links and it will figure out the rest. The Material theme here is _very_ slick and one of the best out of the box themes you'll find for any technical docs generator (or even SSG in general) period. This combo is so good Spotify use it heavily in their developer portal system Backstage: https://backstage.io/blog/2020/09/08/announcing-tech-docs That's a pretty strong endorsement IMHO.

Thank you, that comment is very enlightening... I know hugo pretty well, so this might have been not as obvious to me. One of the things, I did not like so much about hugo (although I think it's awesome), is documentation. It is pretty well documented but as you said the sheer amount of options is overwhelming.

What I was missing, is a list of quickstart best practise scenarios along with a well designed template for exactly this use case, like:

  - A small blog
  - A companies homepage
  - A photographers website
  - A technical documentation with search index
  - An image gallery
Since all this IS possible with hugo, you just have to find your way to do it, I think ;)

Yeah hugo kind of suffers from being one of the first popular tools in the SSG space. It's been around for a while and feature creep has definitely added to the complexity. Being written in Go is both a huge advantage, and an unfortunate disadvantage too these days.

It's great because the speed and ease of use is unrivaled, but nowadays a jamstack site is much, much more than just a pile of markdown turned into HTML. People are building complex SPA, SSR, hybrid, etc. architectures and using fancy webpack-based workflows with all kind of transpilation, code generation, etc. at every level. You have to jam all of that into hugo's workflow and it just adds to the complexity--now you need a full node/JS frontend setup (with webpack/babel/postcss/etc.) and hugo's setup on top of that. Hugo tries to do some of this itself with esbuild but it still is hard to get away from bolting on webpack with hugo and getting the best... and worst... of both worlds.

+1 insightful

Along these lines, the case for exporting a static site from NextJS (leaving the door open to all the options) is a lot stronger than trying to bolt on dynamic functionality to Hugo. IMHO it's not even close.

Since most developers don't like to write documentation, it is important to make the hurdle to write as low as possible. For me AsciiDoctor is the sweetspot because it is easy to setup, has good tool support (for example VS Code and IntelliJ), supports many text features and is relatively easy to learn (if you would only use the features known from markdown, it is as easy to learn as markdown).

Yeah asciidoc is pretty slick. I wish pandoc had more love/support in the SSG world as it can handle basically every doc format known to man with ease, and even enable fancy logic with AST filters in lua scripts. Why not use md, asciidoc, rst, etc. wherever you want.

My dream setup would be something with simple file-based routing like MkDocs, all of the rendering formats and power of pandoc, and the ease of deployment and speed of a Hugo-like static binary in Go (just one exe and you're done).

> On the other end of the spectrum you have tools like MkDocs (or mdbook, docsify, docusaurus, etc.) which are more focused on technical docs in markdown format. These tools put much less emphasis on schema, layout, taxonomy and really try to go from a pile of simple markdown files to a rendered site with as little friction as possible. You typically just lay out files in the filesystem, make simple markdown links between files, and the tool takes care of all the details of building a doc site like layout, rendering, linking, table of contents, and even search.

That's exactly the value proposition of Material for MkDocs. Just throw Markdown at it and tweak it with some configuration, if desired.

> MkDocs strikes a really nice balance in this regard--you basically just write markdown files with simple links and it will figure out the rest. The Material theme here is _very_ slick and one of the best out of the box themes you'll find for any technical docs generator (or even SSG in general) period.


There are SSGs that fit better into this category though. Nanoc is more of a SSG toolkit but offers loads of flexibility.


MkDocs Material is a popular tool for open source python projects. Here are some examples:

pydantic - https://pydantic-docs.helpmanual.io/

FastAPI - https://fastapi.tiangolo.com/

Starlette - https://www.starlette.io/

AutoKeras - https://autokeras.com/

Can confirm, it’s a breeze to use, build and deploy.

AWS Amplify console can deploy this with SSL and zero config.

Also, the search is my favourite feature.

Thanks! I'm glad to hear that. Indeed, a lot of love went into the search and there're still some things that will be improved on the search in the coming months, e.g. more concise search result summaries.

I need a system that:

A) Let's me and other users add annotations to a document.

B) Allows me to view all the annotations added to a doc.

C) Automatically, or semi-automatically merges annotations from the "version 1.0" doc into the newly released document for "version 1.1".

PDF covers (A) and (B) but I haven't been able to find a tool that does (C).

Isn't that just Microsoft Word with track changes on?

Or google docs on "Suggestion mode" ?

Text file in a github repo, seriously.

The docs seem very light on actual examples of writing/structuring syntax or outputs - does anyone know of an example generated site in the wild?

The README has some links to installations used by open source projects and companies, see my other comment [1].

[1]: https://news.ycombinator.com/item?id=27301712

Author here, AMA!

Do you have some examples, showcase or demo somewhere to see the actual final result? Thanks

Is this g3doc?

No, it's just a theme for MkDocs [1], a static site generator that has no affiliation with Google. Material for MkDocs only borrows the Material Design philosophy from Google.

[1]: https://www.mkdocs.org/

I hope someone make Docusaurus as a service, with a better design. I will be happy to pay for it.

This looks nice, but I don't want another Docker service! My dream would be for Observable[1] to create a private space to create my documentation.


It doesn't need Docker to function. You can export static HTML and host it however you like.

This looks very cool. I thought the search was broken because it said "initialising search" when I clicked on the icon and didn't change. Took me a while to figure out there was a text input above which just works.

Did you maybe use a slow connection? When the search index is ready (it's built client-side in a web worker) it switches from "Initializing search" to "Type to start searching". This can be observed when setting network conditions in web inspector to "Slow 3G".

EDIT: You're right, on mobile it only switches to "Type to start searching" after clicking in the search field. Thanks! I'll file a bug report so we can fix it.

It’s interesting tool but would be great if support: - i18n - multilingual è site map and seo - Strapi API - Tailwind CSS

Yep, mkdocs is great, then publish on github pages for free. Surely all documentation will go this route.

I found hugo with documentation templates to be enough. How does this compare?

I like the "Insiders" monetisation strategy.

Thanks! To those interested in the mechanics of the Insiders monetization strategy, I've talked more about in [1]

[1]: https://news.ycombinator.com/item?id=25884018

Now, if only GitHub Pages weren’t down… :(

Looks perfect. Good job!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact