9/20/2023 0 Comments Markdown keeps opening vimr![]() ![]() 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: 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. I use Mark Text as a webpage grabber, and then I copy/paste the markdown text I captured into Typora and use Typora to edit it.Markdown, Asciidoc, or reStructuredText - a tale of docs-as-code Mark Text free markdown editor for Windows/Mac/Linux is better than Typora at accurately capturing everything on a webpage and Typora has a more user-friendly editor, so I use both applications. Max-width: 1800px /*adjust writing area position*/ ) with a CSS content according to /Width-of-Writing-Area. ![]() To get Typora usable in editor mode in Windows and macOS, you must create a file "" in your themes folder (e.g. It removes the preview window, mode switcher, syntax symbols of markdown source code, and all other unnecessary distractions, and replaces them with a real live preview feature to help you concentrate on the content itself. Typora will give you a seamless experience as both a reader and a writer. Typora can capture in this way formatted lists, headings, formatted text, hyperlinks, and images. Typora can capture rich content directly from word processors and webpages, convert it directly into markdown text via copy/paste, and it preserves the original formatting too. The latest version of Typora is currently a beta version and it's free software, but Typora may cost something in the future. I use Typora free (commercial license, not open source) markdown editor for Windows/Mac/Linux because it works very fast. ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |