<story><title>ReStructuredText vs. Markdown for documentation</title><url>http://zverovich.net/2016/06/16/rst-vs-markdown.html</url></story><parent_chain><item><author>jawns</author><text>One point that&amp;#x27;s not really touched upon is the fact that it really does matter whether the person writing the documentation is a technical writer or a developer.&lt;p&gt;If you&amp;#x27;re a tech writer, you&amp;#x27;re probably interested in using the best tool for the job, because writing documentation is what you do day in, day out.  If ReStructuredText is the most powerful format, then you&amp;#x27;re going to strongly lean toward that.&lt;p&gt;If you&amp;#x27;re a developer, however, writing documentation -- while you may recognize its necessity -- is a task that is often a slog.  It&amp;#x27;s something you do so you can get it out of the way, and you really don&amp;#x27;t want to spend very much time thinking about the &amp;quot;how.&amp;quot;  You especially don&amp;#x27;t want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.&lt;p&gt;I say this as a developer who is also a writer.  I enjoy writing, but I know many developers don&amp;#x27;t.  And if Markdown makes it easier for them to write documentation, either because they&amp;#x27;re already familiar with it or because it&amp;#x27;s just a simpler format, then I&amp;#x27;m all for it, even if ReStructuredText might be a bit powerful overall.</text></item></parent_chain><comment><author>marcosdumay</author><text>Completely true, until you need a feature that the less powerful format does not support. Then you are back at the beginning, regretting spending all that time learning something that won&amp;#x27;t fill your needs.&lt;p&gt;ReStructuredText is not hard. Yes, unusual features are hard to memorize, but a quick google search beats it being impossible every time.</text></comment>
<story><title>ReStructuredText vs. Markdown for documentation</title><url>http://zverovich.net/2016/06/16/rst-vs-markdown.html</url></story><parent_chain><item><author>jawns</author><text>One point that&amp;#x27;s not really touched upon is the fact that it really does matter whether the person writing the documentation is a technical writer or a developer.&lt;p&gt;If you&amp;#x27;re a tech writer, you&amp;#x27;re probably interested in using the best tool for the job, because writing documentation is what you do day in, day out.  If ReStructuredText is the most powerful format, then you&amp;#x27;re going to strongly lean toward that.&lt;p&gt;If you&amp;#x27;re a developer, however, writing documentation -- while you may recognize its necessity -- is a task that is often a slog.  It&amp;#x27;s something you do so you can get it out of the way, and you really don&amp;#x27;t want to spend very much time thinking about the &amp;quot;how.&amp;quot;  You especially don&amp;#x27;t want to spend very much time learning the intricacies of a new markup format, unless you absolutely have to.&lt;p&gt;I say this as a developer who is also a writer.  I enjoy writing, but I know many developers don&amp;#x27;t.  And if Markdown makes it easier for them to write documentation, either because they&amp;#x27;re already familiar with it or because it&amp;#x27;s just a simpler format, then I&amp;#x27;m all for it, even if ReStructuredText might be a bit powerful overall.</text></item></parent_chain><comment><author>xapata</author><text>I wouldn&amp;#x27;t say Markdown is simpler. It has fewer features, but the core experience is about the same as reStructuredText.&lt;p&gt;RST header markup is more readable in plain text. In Markdown, the less important a header is, the more hash marks. In RST, I am free to make less important headers have less visual weight.</text></comment>