4 ms·

Good documentation isn't only about it being readable in plain-text. It is about being accurate, maintainable, easy to read (when processed) and even, dynamic (

Good documentation isn't only about it being readable in plain-text. It is about being accurate, maintainable, easy to read (when processed) and even, dynamic (look at Stripe's documentation that contains your own API keys, not random ones). Anybody writing documentation with this goal in mind will quickly realize that Markdown is not fit for the job. Asciidoc is fully compatible with markdown, and provides a lot more functionality out of the box. Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this. The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k. A quick search on Google allowed me to find this page[0] which lists no less than 20 different markdown flavors. Asciidoc comes in 1 and only 1 flavor that does most of everything you want. Also, there's a great open-source project that allows you to create a documentation website in Aciidoc: https://antora.org/ https://antora.org/. (I'm not affiliated, just a happy user) [0]: https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684b...

robocat 7y ago
Personally asciidoc has too many features, and the asciidoc syntax is baroque. Cheat sheet: https://powerman.name/doc/asciidoc https://powerman.name/doc/asciidoc and there are a bunch of complicated examples on this page: https://www.methods.co.nz/asciidoc/newtables.html https://www.methods.co.nz/asciidoc/newtables.html Examples of asciidoc text styling: 'Emphasized text', * Strong text* , +Monospaced text+, ``Quoted text''. 'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^ and ~some sub text~ Example of a nested table (WTF!): [width="75%",cols="1,2a"] |============================================== |Normal cell |Cell with nested table [cols="2,1"] !============================================== !Nested table cell 1 !Nested table cell 2 !============================================== |==============================================
- gouggoug 7y ago
  You do not need to use _all_ the features provided by Asciidoc. Here's what I think is a better link[0] than the one you provided. It's the Asciidoc getting started documentation. It's not complicated at all, it looks extremely similar to markdown. If you want to compare MD and Asciidoc side by side, go here[1]. Which one looks more complicated? Now, regarding the table syntax, yes, I agree, it is complicated and that's because tables are complicated. In markdown you don't even have tables, so it's not really fair to say "look at the table syntax in asciidoc WTF, what a mess!". [0] https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... [1] https://asciidoctor.org/docs/asciidoc-vs-markdown/#comparison-by-example https://asciidoctor.org/docs/asciidoc-vs-markdown/#compariso...
- type0 7y ago
  If you want simple tables just use csv |=== include::customers.csv[] |===
osrec 7y ago
I especially like the fact that you can have counters in asciidoc, so you can do interesting kinds of numbering. Trying to do the same in markdown is tricky and it's what actually led me to asciidoc.
stared 7y ago
Every time I hear "X provides more functionality than Markdown", consider it a strong reason to choose MD. I think that The Rule of Least Power (https://en.wikipedia.org/wiki/Rule_of_least_power https://en.wikipedia.org/wiki/Rule_of_least_power) > suggests choosing the least powerful [computer] language suitable for a given purpose is a good guideline. For every "I need feature X" there should be a question if using this feature is actually beneficial. For general typesetting, we can use general XML, with custom tags. Or anything. To be clear - I don't mean that MD is the solution for documentation. For many things, we clearly need a different tool. For example, for mathematical papers (with many formulae and cross-references) while we can hack MD to do the job, most likely it won't be the right tool. > Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this. Most of these things, IMHO, are standard solutions, but not as good when you ask why? E.g. instead of footnotes, inline links (it is not printed on paper, is it?), hand-written table are rarely readable as usually other formats are better, you can easily generate TOC from MD headers structure, etc.
- gouggoug 7y ago
  I think this comment illustrates why there's always a debate between markdown vs asciidoc vs xyz. Markdown is "good enough" for a large amount of people who care less about what seasoned technical writers care about. > I just reference other functions by name. (granted a "function name" isn't the best example): when your documentation becomes large enough, your function name will appear in so many places throughout the documentation that you'll want to change it once in one place, and it to appear everywhere else. Having a dynamic variable inside your documentation to take care of this is immensely useful. This is the kind of feature that other documentation markups offer that (1) you do not need to use but, (2) have at your disposition when you need to. Now, just to illustrate this with a better example: I wrote user documentation about "how to create a concourse-ci cluster in Google Cloud". This documentation contains a lot of things specific to my organization ("acme"), for example, the VPC network name that needs to be used is fairly variable and depends on the GCE project name but also the region of the project and other things. Depending on who reads the documentation and their project, a few things need to be changed. For this purpose, the top of my documentation contains a few variables that are then used throughout the document in place of hardcoded values. The variables: :concourse-ci-host: ci.acme.io :concourse-ci-url: https://{concourse-ci-host} :gke-cluster-name: concourse-ci :gke-cluster-region: us-central1 :service-account-concourse-ci: {gke-cluster-name} :service-account-concourse-ci-docker-registry: {gke-cluster-name}-docker-registry :gcloud-vpc-network-name: {gke-cluster-name} :gcloud-static-ip-name: {gke-cluster-name} :gcloud-cloud-router-name: {gcloud-vpc-network-name} :gcloud-cloud-nat-gateway-name: {gcloud-vpc-network-name} An example of a section of the documentation about create the firewall rules: # Create the network gcloud compute networks create {gcloud-vpc-network-name} # Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-internal --network {gcloud-vpc-network-name} --allow tcp,udp,icmp --source-ranges 10.128.0.0/9 gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-ssh --network {gcloud-vpc-network-name} --allow tcp:22 gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-rdp --network {gcloud-vpc-network-name} --allow tcp:3389 gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-icmp --network {gcloud-vpc-network-name} --allow icmp Which automatically renders: # Create the network gcloud compute networks create concourse-ci # Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP gcloud compute firewall-rules create concourse-ci-allow-internal --network concourse-ci --allow tcp,udp,icmp --source-ranges 10.128.0.0/9 gcloud compute firewall-rules create concourse-ci-allow-ssh --network concourse-ci --allow tcp:22 gcloud compute firewall-rules create concourse-ci-allow-rdp --network concourse-ci --allow tcp:3389 gcloud compute firewall-rules create concourse-ci-allow-icmp --network concourse-ci --allow icmp > That’s usually enough. Until it's not (example above). And it only becomes not enough when your documentation increases in terms of size, complexity of the subject being documented and number of technical writers writing it. > My coworkers and my future self are adults and can use ‘find’ But your users don't want to use find. They're already too busy learning and understanding your product and the documentation shouldn't get in their way. Markdown is fine for quick short documentation. Asciidoc is needed for extensive large documentation.
ogre_codes 7y ago
Documentation for a software project should be fairly succinct and should be editable by anyone on the project. Developers are exposed to markdown on a near daily basis for other tools like GitHub, StackOverflow, and many other tools. Markdown is the tool every one of us already know how to use. > The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k Yet 99% of documentation I've written uses the basic syntax described here: https://daringfireball.net/projects/markdown/syntax https://daringfireball.net/projects/markdown/syntax Extensions add to that basic set of tools, so even if you are using Github's flavor of markdown, every single developer on your tool is going to be able to read and edit most of your documentation without referring to any reference material.

robocat 7y ago

Personally asciidoc has too many features, and the asciidoc syntax is baroque. Cheat sheet: https://powerman.name/doc/asciidoc https://powerman.name/doc/asciidoc and there are a bunch of complicated examples on this page: https://www.methods.co.nz/asciidoc/newtables.html https://www.methods.co.nz/asciidoc/newtables.html Examples of asciidoc text styling: 'Emphasized text', * Strong text* , +Monospaced text+, ``Quoted text''. 'Subscripts and superscripts': e^{amp}#960;i^+1 = 0. H~2~O and x^10^. Some ^super text^ and ~some sub text~ Example of a nested table (WTF!): [width="75%",cols="1,2a"] |============================================== |Normal cell |Cell with nested table [cols="2,1"] !============================================== !Nested table cell 1 !Nested table cell 2 !============================================== |==============================================

gouggoug 7y ago
You do not need to use _all_ the features provided by Asciidoc. Here's what I think is a better link[0] than the one you provided. It's the Asciidoc getting started documentation. It's not complicated at all, it looks extremely similar to markdown. If you want to compare MD and Asciidoc side by side, go here[1]. Which one looks more complicated? Now, regarding the table syntax, yes, I agree, it is complicated and that's because tables are complicated. In markdown you don't even have tables, so it's not really fair to say "look at the table syntax in asciidoc WTF, what a mess!". [0] https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ https://asciidoctor.org/docs/asciidoc-syntax-quick-reference... [1] https://asciidoctor.org/docs/asciidoc-vs-markdown/#comparison-by-example https://asciidoctor.org/docs/asciidoc-vs-markdown/#compariso...
type0 7y ago
If you want simple tables just use csv |=== include::customers.csv[] |===

osrec 7y ago

I especially like the fact that you can have counters in asciidoc, so you can do interesting kinds of numbering. Trying to do the same in markdown is tricky and it's what actually led me to asciidoc.

stared 7y ago

Every time I hear "X provides more functionality than Markdown", consider it a strong reason to choose MD. I think that The Rule of Least Power (https://en.wikipedia.org/wiki/Rule_of_least_power https://en.wikipedia.org/wiki/Rule_of_least_power) > suggests choosing the least powerful [computer] language suitable for a given purpose is a good guideline. For every "I need feature X" there should be a question if using this feature is actually beneficial. For general typesetting, we can use general XML, with custom tags. Or anything. To be clear - I don't mean that MD is the solution for documentation. For many things, we clearly need a different tool. For example, for mathematical papers (with many formulae and cross-references) while we can hack MD to do the job, most likely it won't be the right tool. > Basic functionality often needed when writing documentation aren't part of the original markdown spec and require non-standard extensions: tables, footnote, table-of-content, cross references are good examples of this. Most of these things, IMHO, are standard solutions, but not as good when you ask why? E.g. instead of footnotes, inline links (it is not printed on paper, is it?), hand-written table are rarely readable as usually other formats are better, you can easily generate TOC from MD headers structure, etc.

gouggoug 7y ago
I think this comment illustrates why there's always a debate between markdown vs asciidoc vs xyz. Markdown is "good enough" for a large amount of people who care less about what seasoned technical writers care about. > I just reference other functions by name. (granted a "function name" isn't the best example): when your documentation becomes large enough, your function name will appear in so many places throughout the documentation that you'll want to change it once in one place, and it to appear everywhere else. Having a dynamic variable inside your documentation to take care of this is immensely useful. This is the kind of feature that other documentation markups offer that (1) you do not need to use but, (2) have at your disposition when you need to. Now, just to illustrate this with a better example: I wrote user documentation about "how to create a concourse-ci cluster in Google Cloud". This documentation contains a lot of things specific to my organization ("acme"), for example, the VPC network name that needs to be used is fairly variable and depends on the GCE project name but also the region of the project and other things. Depending on who reads the documentation and their project, a few things need to be changed. For this purpose, the top of my documentation contains a few variables that are then used throughout the document in place of hardcoded values. The variables: :concourse-ci-host: ci.acme.io :concourse-ci-url: https://{concourse-ci-host} :gke-cluster-name: concourse-ci :gke-cluster-region: us-central1 :service-account-concourse-ci: {gke-cluster-name} :service-account-concourse-ci-docker-registry: {gke-cluster-name}-docker-registry :gcloud-vpc-network-name: {gke-cluster-name} :gcloud-static-ip-name: {gke-cluster-name} :gcloud-cloud-router-name: {gcloud-vpc-network-name} :gcloud-cloud-nat-gateway-name: {gcloud-vpc-network-name} An example of a section of the documentation about create the firewall rules: # Create the network gcloud compute networks create {gcloud-vpc-network-name} # Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-internal --network {gcloud-vpc-network-name} --allow tcp,udp,icmp --source-ranges 10.128.0.0/9 gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-ssh --network {gcloud-vpc-network-name} --allow tcp:22 gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-rdp --network {gcloud-vpc-network-name} --allow tcp:3389 gcloud compute firewall-rules create {gcloud-vpc-network-name}-allow-icmp --network {gcloud-vpc-network-name} --allow icmp Which automatically renders: # Create the network gcloud compute networks create concourse-ci # Configure the firewall to allow all internal traffic and internet traffic to SSH, RDP and ICMP gcloud compute firewall-rules create concourse-ci-allow-internal --network concourse-ci --allow tcp,udp,icmp --source-ranges 10.128.0.0/9 gcloud compute firewall-rules create concourse-ci-allow-ssh --network concourse-ci --allow tcp:22 gcloud compute firewall-rules create concourse-ci-allow-rdp --network concourse-ci --allow tcp:3389 gcloud compute firewall-rules create concourse-ci-allow-icmp --network concourse-ci --allow icmp > That’s usually enough. Until it's not (example above). And it only becomes not enough when your documentation increases in terms of size, complexity of the subject being documented and number of technical writers writing it. > My coworkers and my future self are adults and can use ‘find’ But your users don't want to use find. They're already too busy learning and understanding your product and the documentation shouldn't get in their way. Markdown is fine for quick short documentation. Asciidoc is needed for extensive large documentation.

ogre_codes 7y ago

Documentation for a software project should be fairly succinct and should be editable by anyone on the project. Developers are exposed to markdown on a near daily basis for other tools like GitHub, StackOverflow, and many other tools. Markdown is the tool every one of us already know how to use. > The markdown ecosystem is now riddled with non standard extensions and reminds me the browser ecosystem of y2k Yet 99% of documentation I've written uses the basic syntax described here: https://daringfireball.net/projects/markdown/syntax https://daringfireball.net/projects/markdown/syntax Extensions add to that basic set of tools, so even if you are using Github's flavor of markdown, every single developer on your tool is going to be able to read and edit most of your documentation without referring to any reference material.