Hacker News Reader

Comment by taftster | Hacker News Reader

I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms).

I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL.

The problem is simply that github, gitlab, and friends adopted Markdown and so it's got a heavy head start. Asciidoc is competing with small snippet documentation like README files written in Markdown and wiki pages in Confluence, Sharepoint, and the like. Asciidoc is pinched in the middle. I do hope it gets better adoption.

View on HN

> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL

There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc.

( Tools used are Gitlab CI, mark and Confluence, but they don't really matter, the workflow does).

Yeah, you could add a job to your CI that runs a compiler and outputs the result to a web page that can be accessed by all. I'm sure there's ways and means to have a web based editor that can commit into version control as well.

I didn't know it already existed. I'm working on something similar via a Github app which watch new commits made on master and offer to the commiter to upload its new .md files on the wiki.

As you said having the dev doc on an external tool is really a plus. You can have comments, you can add tags, easier to search, and give access to non technical people

I really like the sound of this. That’s how Google’s internal technical docs worked. Write markdown in src repo, get nice, searchable doc site in return.

Anyone know if a tool like that already exists to turn README.md files into a website?

There are a few ones, the only one that comes to mind is Docusaurus from iirc Facebook.

There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter. AsciiDoctor is already written in Ruby, which is probably what they use on the backend for Markdown conversion. Hugo supports it as well, and I'm sure there are other static site generators. I agree 100% about documentation on Confluence or Sharepoint. Seriously, will not even work at a company that is heavily invested in either at this point.

Github already supports Restructured Text (reST) in READMEs, and some other markdown flavours. Do not know about AsciiDoc but looks interesting.

As can be seen here, GitHub renders Asciidoc just fine: https://github.com/asciidoctor/asciidoctor.js

Alas, no support[1] for include.

[1]: https://github.com/github/markup/issues/1095

According to GitHub Docs [1], GitHub supports several markup languages, including Markdown, AsciiDoc, Textile, ReStructuredText, Rdoc, Org, Creole, MediaWiki, and Pod.

[1] https://docs.github.com/en/github/managing-files-in-a-reposi...

GitLab also support AsciiDoc.

SourceHut unfortunately does not. You can go through the hoops of POSTing to its GraphQL API from CI a new README from any format to HTML.

You can also embed diagrams and flowcharts with Mermaid into Asciidoc, not only in Markdown.

https://docs.gitlab.com/ee/user/asciidoc.html#mermaid

Examples for Mermaid layouts in the GitLab handbook: https://about.gitlab.com/handbook/tools-and-tips/mermaid/

> There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter

Github already supports AsciiDoc via AsciiDoctor.

It wouldn't be so bad if Confluence/whatever could just render the Asciidoc from the source repository. But they are generally closed systems. There's no way in or out of Confluence without significant headaches.

I have both a centralized Confluence instance and the documentation in GitHub. A GitHub action converts the markdown to Confluence to stay in sync. It's very handy, because developers like to document in markdown on GitHub, but business people tend to favor Confluence. One additional feature you get from this is the search over all repos, which doesn't work without additional tooling in GitHub.

One of the better, yet sad jokes, because it must have been one, was, when they announced "markdown support" in Confluence wiki, but barely any markdown worked. One has to ask oneself, who coded up that half-assed parser there, that manages to parse less markdown, than basically any half-serious markdown parser in any language, that I have ever used. Enterprise software for you.

Edit: Now that I think about it, the whole product palette of Atlassian seems to have issues making use of any decent markdown parser out of the myriads of parsers out there, that they could use. For example HTML in markdown on Bitbucket also does not properly work, so generating a table of contents is useless on Bitbucket as well.

The really fun part of having docs in confluence is that if Confluence goes down, you lose access to ops playbooks.

I’ve had similar fun experience with Slack-ops when slack goes down.

Reply on news.ycombinator.com