If you’re testing or learning a specific syntax, there are many online editors, such as, StackEdit for Markdown.
#MARKTEXT TOC CODE#
Most code editors will have plug-ins for popular markup languages which will offer you syntax highlighting, preview, etc. The choices - md, adoc, reSTīefore choosing a markup language, you’ll need to choose either a desktop code editor like VSCode or stay in your terminal and use something like EmacsVIM. If you don’t need a brief intro and would like to skip the appetizer, you can go straight to the entrée - Choose the right markup section. My hope is to provide you with a detailed analysis of these choices of markup languages and frameworks so that you can make an informed decision when selecting one for your next developer documentation project. I’ll skip the history but in case you’re interested, my friend and colleague Tibs delivered a talk on the history of text markup languages. In the first part of my docs-as-code series, I’ll talk about the choice of markup languages, the available frameworks, and do a comparison among Markdown (md), Asciidoc (adoc), and reStructuredText (reST) based on some use cases. Publish: Deploy your documentation live using platforms like GitHub (Pages), Vercel, or Netlify.
Automate the build (optional but highly recommended): Add a CI with spelling, prose, link checks, etc.This could be self-hosted or a managed provider. Host: Host the markup files on some repository.Extend (optional but almost a requirement): Use a framework to avail features that are not part of the basic markup.Write: Use a markup language to write the docs.I see five stages in docs-as-code implementation:
#MARKTEXT TOC SOFTWARE#
With the text files for documentation in version control system and changes going through the pull request process, the documentation is treated exactly like software code and hence docs-as-code. If your users are developers, it’s more likely that they would appreciate reading docs written by other developers. Note that I’m not using the term “product documentation”, rather “developer documentation”. Having git running in their DNA, these developers wanted to bring in collaboration, version control, scripting, and easier bug tracking within developer documentation. This “modernization” started when more and more developers started writing documentation (not all developers hate writing docs 🤭).
Since then, many companies in tech (including companies like IBM) have taken a modern approach to documentation.
I can speak for myself when I say that I never bothered to know who keeps writing the lengthy and complex documentation for every release. My immediate team had developers and testers but not a single technical writer. Who writes the developer documentation for your product? During the early days of my tech career, I worked on a database replication product at IBM. Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code
0 kommentar(er)
