Technical documentation that just works

This tool seems like it is a nice markdown based CMS but I don&#x27;t see too many features related to the more difficult parts of doing technical documentation. Like having working code samples.<p>I attempted a Kotlin centric documentation framework a while ago to address this: <a href="https:&#x2F;&#x2F;github.com&#x2F;jillesvangurp&#x2F;kotlin4example" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;jillesvangurp&#x2F;kotlin4example</a><p>I mainly use it to generate the documentation for my Elasticsearch Kotlin Client (jillesvangurp&#x2F;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&#x27;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.<p>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.

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

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.<p>Some details: Our company is still firmly architected around the &#x27;pets, not cattle&#x27; 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.<p>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.<p><a href="https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;4%2B1_architectural_view_model" rel="nofollow">https:&#x2F;&#x2F;en.wikipedia.org&#x2F;wiki&#x2F;4%2B1_architectural_view_model</a>

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.<p><a href="https:&#x2F;&#x2F;asciidoctor.org&#x2F;" rel="nofollow">https:&#x2F;&#x2F;asciidoctor.org&#x2F;</a>

Not to downplay what seems to be a nice tool, but bundling markdown files into a static site is the easy part.<p>What I would love to see is a way to combine markdown pages with source-generated API docs from multiple languages.<p>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.

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&#x27;t work well without JavaScript.<p>I think the tablet viewport (aka desktop-not-maximized) could use bit more love, and it&#x27;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.

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.<p>[1] <a href="https:&#x2F;&#x2F;github.com&#x2F;sphinx-doc&#x2F;sphinx" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;sphinx-doc&#x2F;sphinx</a><p>[2] <a href="https:&#x2F;&#x2F;github.com&#x2F;pradyunsg&#x2F;furo" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;pradyunsg&#x2F;furo</a>

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...<p>e.g. <a href="https:&#x2F;&#x2F;themes.gohugo.io&#x2F;doks&#x2F;" rel="nofollow">https:&#x2F;&#x2F;themes.gohugo.io&#x2F;doks&#x2F;</a> or<p><a href="https:&#x2F;&#x2F;themes.gohugo.io&#x2F;hugo-geekdoc&#x2F;" rel="nofollow">https:&#x2F;&#x2F;themes.gohugo.io&#x2F;hugo-geekdoc&#x2F;</a>

MkDocs Material is a popular tool for open source python projects. Here are some examples:<p>pydantic - <a href="https:&#x2F;&#x2F;pydantic-docs.helpmanual.io&#x2F;" rel="nofollow">https:&#x2F;&#x2F;pydantic-docs.helpmanual.io&#x2F;</a><p>FastAPI - <a href="https:&#x2F;&#x2F;fastapi.tiangolo.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;fastapi.tiangolo.com&#x2F;</a><p>Starlette - <a href="https:&#x2F;&#x2F;www.starlette.io&#x2F;" rel="nofollow">https:&#x2F;&#x2F;www.starlette.io&#x2F;</a><p>AutoKeras - <a href="https:&#x2F;&#x2F;autokeras.com&#x2F;" rel="nofollow">https:&#x2F;&#x2F;autokeras.com&#x2F;</a>

Can confirm, it’s a breeze to use, build and deploy.<p>AWS Amplify console can deploy this with SSL and zero config.<p>Also, the search is my favourite feature.

I need a system that:<p>A) Let&#x27;s me and other users add annotations to a document.<p>B) Allows me to view all the annotations added to a doc.<p>C) Automatically, or semi-automatically merges annotations from the &quot;version 1.0&quot; doc into the newly released document for &quot;version 1.1&quot;.<p>PDF covers (A) and (B) but I haven&#x27;t been able to find a tool that does (C).

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

Author here, AMA!

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&#x27;t want another Docker service! My dream would be for Observable[1] to create a private space to create my documentation.<p>[1]<a href="https:&#x2F;&#x2F;observablehq.com" rel="nofollow">https:&#x2F;&#x2F;observablehq.com</a>

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

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 &quot;Insiders&quot; monetisation strategy.

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

Looks perfect. Good job!