Markdown is an excellent choice for documentation

Every few months, it seems a new post decrying the use of markdown for documentation (or other things) rises to the top of Hacker News.

There are often good reasons for preferring a more structured option, like reStructuredText , LaTeX , or Asciidoc . Especially in projects where more formal text is required, or where you need to support specialized and structured text formatting.

But for 98% of software projects (and in my experience, 95% of all other text I've ever written), markdown suffices, and it is truly a low barrier compared to the alternatives. It's basically plain text (which anyone can learn to write in a few seconds) with extra features.

I've written two books entirely in markdown—specifically, LeanPub-flavored markdown —and besides plain text, it is the easiest language for general content authoring.

The fact that Markdown's lowest common denominator is 'I can write plain text,' coupled to the fact that there are very good libraries for markdown in every conceivable language, means it is the simplest way to make sure you have a basic level of maintainable documentation, no matter who contributes to your codebase. Getting people to contribute plain text changes to documentation is a heck of a lot easier than getting people to contribute in a specific format which is less popular and requires more specificity.

All 5,000+ posts on this blog are written in Markdown, and there are times when I drop back to HTML for advanced formatting. No problem. And if you want to mix LaTeX into Markdown, there are ways to do that , too.

The truth is, the simplicity and ubiquity of Markdown is the reason it is the best choice for most projects.

It may not be as fully-featured or structured as [insert your favorite format here], but it's good enough .

以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

• Markdown is an excellent choice for documentation

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。