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
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.
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
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.
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.
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...
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.
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).
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.
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.
> 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.
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.
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.
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.
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.
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.
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 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.
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 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.
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]
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.
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.
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
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 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.
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].
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 :)
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].
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.
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.
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.)
78 comments
[ 3.2 ms ] story [ 156 ms ] threadBut 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/
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.
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/
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.
That told me that Quip seems to be much more intuitive and easier to use for less technical people.
I see all missing a way to create other pages for content marketing (e.g. Academy, Blog etc..).
e.g. https://themes.gohugo.io/doks/ or
https://themes.gohugo.io/hugo-geekdoc/
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.
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).
What I was missing, is a list of quickstart best practise scenarios along with a well designed template for exactly this use case, like:
Since all this IS possible with hugo, you just have to find your way to do it, I think ;)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.
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.
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.
Thanks!
https://nanoc.app/
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...
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.
> 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!
[1]: https://adamwathan.me/dont-use-em-for-media-queries/
https://asciidoctor.org/
[1]: https://www.mkdocs.org/
- https://fastapi.tiangolo.com/
- https://crystal-lang.org/reference/
- https://docs.pi-hole.net/
- https://docs.openfaas.com/
- https://mozillafoundation.github.io/engineering-handbook/
- https://microsoft.github.io/code-with-engineering-playbook/
[1]: https://github.com/squidfunk/mkdocs-material#trusted-by-
AWS Amplify console can deploy this with SSL and zero config.
Also, the search is my favourite feature.
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.
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.
https://en.wikipedia.org/wiki/4%2B1_architectural_view_model
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.
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)
Pleas blog about this, it is very interesting to me.
Just to be sure: this is what you mean with Mike?
https://github.com/jimporter/mike
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.
- 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.
[1]: https://news.ycombinator.com/item?id=25884018
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.
[1]: https://dev.to/yysun/make-code-run-in-your-docs-4800
https://oprypin.github.io/mkdocs-code-validator/ https://github.com/crystal-lang/crystal-book/pull/503
live snippets (brett victor hello) or even ability to try permutations of inputs to get a feel
and maybe .. metalevel generated live tests.
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/
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.
[1] https://github.com/sphinx-doc/sphinx
[2] https://github.com/pradyunsg/furo
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/
https://myst-nb.readthedocs.io/en/latest/
[1]: https://news.ycombinator.com/item?id=27301712
[1]https://observablehq.com
pydantic - https://pydantic-docs.helpmanual.io/
FastAPI - https://fastapi.tiangolo.com/
Starlette - https://www.starlette.io/
AutoKeras - https://autokeras.com/
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).