Technical documentation that just works

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.

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/

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.

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)

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.

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.

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

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.

Thanks!

> 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...

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/

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.

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

https://nanoc.app/

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.

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

Text file in a github repo, seriously.

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

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

Is this g3doc?

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

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.

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