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 ca

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.