Don't write documentation in Markdown

286 pointsby randyzwitchabout 5 years ago

103 comments

dangabout 5 years ago

Concurrent rebuttal thread: <a href="https://news.ycombinator.com/item?id=22677970" rel="nofollow">https://news.ycombinator.com/item?id=22677970</a>Follow-up supporting thread with older article: <a href="https://news.ycombinator.com/item?id=22677161" rel="nofollow">https://news.ycombinator.com/item?id=22677161</a>

评论 #22679713 未加载

husarcikabout 5 years ago

This reminds me of a comment on an anti-markdown post I read a few years back."As far as I'm concerned the best tool for writing documentation is the one that anyone can actually be bothered to use. Markdown might not be perfect but at least it's simple and commonly understood so there isn't much barrier to writing/updating documentation." - warmans[1] <a href="https://www.reddit.com/r/programming/comments/4ck2lu/why_you_shouldnt_use_markdown_for_documentation/" rel="nofollow">https://www.reddit.com/r/programming/comments/4ck2lu/why_you...</a>

评论 #22679769 未加载

评论 #22676225 未加载

评论 #22680416 未加载

评论 #22675952 未加载

1MoreThingabout 5 years ago

This is missing the point.The goal is "please write your documentation." What solution has the least friction around that for engineers? Right now, it's overwhelmingly Markdown.It's not perfect, and often doesn't provide the features a technical writer or other content specialist might want, but it handles most use cases and is something developers are willing to write in.So please, write your documentation in whatever you feel like. As long as it gets written.

评论 #22675705 未加载

评论 #22679014 未加载

评论 #22678651 未加载

评论 #22678089 未加载

评论 #22676226 未加载

评论 #22676030 未加载

taylodlabout 5 years ago

Meanwhile programmers are like: Please write documentation! Please. I'm begging you. Even documentation written in Markdown is better than the nothing that all-too-often gets created.A lot of programmers argue the code is the best documentation. No it's not. Source code answers the how and what but it doesn't provide any answer to the most important question of all - why?Software embodies several architectural and design decisions. What decisions were explicitly made and why were they made? All too often when looking at code I can certainly understand what was done, but it's not at all immediately clear as to why.On the teams I've been working with I've gotten them to capture these decisions. It's been a great help - sometimes the original implementors can't remember why something was done the way it was done - especially when asked three or more years later.Admonishing people to write documentation in Markdown would be a nice problem for me to have. Meanwhile I'd just like some documentation at all. Please?!

评论 #22680127 未加载

评论 #22684452 未加载

drcongoabout 5 years ago

I can't stand reStructuredText, it's obtuse. Over the last year or so have converted all of our documentation to Markdown and I couldn't be happier about it.

评论 #22675605 未加载

评论 #22675734 未加载

评论 #22675637 未加载

评论 #22678598 未加载

JMTQp8lwXLabout 5 years ago

There's hills that seem worth dying on. This doesn't seem to be one of them. The author says it's "tolerable" to use markdown for a README.md, but in many small projects -- that's all there is. Besides the code, there's the README. When I think of larger open source projects, I don't see intricate or excessive usage of markdown. They have full blown websites-- React, Jest, Material UI-- you name it. I don't see a single actual example of the problem.

评论 #22676230 未加载

评论 #22676254 未加载

评论 #22677713 未加载

lhorieabout 5 years ago

This is committing a fallacy I see far too often at my company: that because something is considered "technically superior" it should be the tool of choice. This misses the human aspect of a system. Markdown has low barrier of entry, and in a world where more often than not, documentation is poor or non-existent, it doesn't really matter if a documentation system has many bells and whistles if those features get seen as too difficult to learn and result in no docs being written in the first place.Another important human aspect of documentation is docs are often written by people joining a project late who may already be knees deep trying to understand the projects APIs. Burdening them with learning a documentation system on top of that can definitely a tipping point between "I should document this" to "ah whatever, I'll just slog through the code".

评论 #22678571 未加载

rvzabout 5 years ago

> Developers: reStructuredText is better than .txt and .md because it has feature XYZ, and it's special syntax is great.> Researchers: .rst and .md are poor with math symbols, please write the technical documentation in beautiful LaTeX with rendered symbols.> Managers: If I can't read or edit it easily, I'll hire someone to rewrite it using Word or Google Docs.> Everyone: Here's the Word document...> Scribe: 𝔜𝔢 𝔬𝔣𝔣𝔦𝔠𝔦𝔞𝔩 𝔡𝔬𝔠𝔲𝔪𝔢𝔫𝔱𝔞𝔱𝔦𝔬𝔫 𝔰𝔥𝔬𝔲𝔩𝔡 𝔟𝔢 𝔴𝔯𝔦𝔱𝔱𝔢𝔫 𝔟𝔶 𝔥𝔞𝔫𝔡 𝔞𝔫𝔡 𝔰𝔢𝔱 𝔦𝔫 𝔰𝔱𝔬𝔫𝔢 𝔴𝔦𝔱𝔥 𝔭𝔢𝔫 𝔞𝔫𝔡 𝔭𝔞𝔭𝔢𝔯.> Me: Meh. if everyone can't read or edit it quick enough towards the deadline, then I'll stick to Google Docs.

walterbellabout 5 years ago

AsciiDoc is compatible with Markdown and can generate many output formats, including Docbook and Latex, which enables toolchain reuse. This provides more optionality than RST.The most important property of documentation is existence. Markdown has a low barrier to entry and the markup can later be upgraded to Asciidoc.

评论 #22679523 未加载

Athasabout 5 years ago

While I acknowledge that Markdown's lack of extensibility is a big problem, one that RST doesn't share, RST has its own problems. For example, this is how you write a link in RST:<pre><code> `link text <https://news.ycombinator.com>`_ </code></pre> Obscure, but OK. This is how you put something in monospace:<pre><code> ``monospace`` </code></pre> So then how do you make the link text contain monospace formatting? Last I checked, there was no clean way. Using non-matching bracketing characters is a terrible idea because it inhibits nesting, which has been known at least since POSIX shell introduced $(). There is really no excuse for the way RST uses backticks. This is a major reason why I prefer Markdown.

评论 #22675739 未加载

karlicossabout 5 years ago

Not sure about proper documentation, but I've found Org-mode to be quite enjoyable for writing readmes, mainly because of its org-babel [0] (aka executable code blocks) support. That way you can include/tangle bits of source code and help strings documentation in the readme, avoiding unnecessary duplication. The results of the evaluation are committed to the repository as well, and it's plaintext, so you don't need Emacs to fix/update the docs -- you can patch up the evaluation results, and the maintainer with Emacs can fix it properly later.E.g. here [1] I'm reusing the argparse help string in the readme. That makes the source code the primary source of truth.Another experiment I did was writing readme as an Ipython notebook [2], and then compiling the output to markdown. That allowed me to link bits of readme straight to the code. E.g. as an example, each of the 'Features' [3] links straight to the unit test for that specific feature. The downside is that you need to remember to refresh the readme after code changes, otherwise the line numbers break. Perhaps that can be set up automatically as a CI job.In hindsight through, would have been easier to use org-mode as well to avoid keeping two separate files for the readme.- [0] <a href="https://orgmode.org/worg/org-contrib/babel/intro.html" rel="nofollow">https://orgmode.org/worg/org-contrib/babel/intro.html</a>- [1] <a href="https://github.com/karlicoss/rexport/blame/master/README.org#L15-L17" rel="nofollow">https://github.com/karlicoss/rexport/blame/master/README.org...</a>- [2] <a href="https://github.com/karlicoss/cachew/blob/master/README.ipynb" rel="nofollow">https://github.com/karlicoss/cachew/blob/master/README.ipynb</a>- [2] <a href="https://github.com/karlicoss/cachew#features" rel="nofollow">https://github.com/karlicoss/cachew#features</a>

评论 #22683110 未加载

zelphirkaltabout 5 years ago

I'd also recommend people to make use of reStructuredText for documentation. Also it is actually possible to write something like a thesis or scientific research in it, where you might need arbitrary linking powers, which you simply don't have in Markdown. This can also be important for technical documentation. Furthermore you can add custom roles, like I did for my personal wiki implementation, to link to other pages, which are actually other reStructuredText files.The downside of reStructuredText is, that there are almost no libraries in other languages than Python, which can transform it into HTML for the web. The canonical parser is a custom parser, without grammar and lots of states, which is unfortunate, because if there was a grammar, it could easily be implemented in other languages and the format might be much more used. But perhaps it would not be as extensible then?Another, but quite minor, downside is, that it is a little bit harder to learn than Markdown.Perhaps I can suggest Emacs Org-mode? The downside is, that it's only available to the extend in Emacs and other implementations are lacking many things.Anyway, I wrote a thesis in reStructuredText and used Pandoc + custom preprocessing for document internal linking to generate the final PDF version and once I had it set up, it worked great.

oefrhaabout 5 years ago

AsciiDoc is pretty good, yes. But reST? Just no.As a Python developer I’m no stranger to reST, and problems like the inability to nest inline constructs (e.g. [`code`](<a href="https://example.com" rel="nofollow">https://example.com</a>) is impossible in reST) are simply ridiculous. (Talking about docutils here. Maybe there are other unofficial implementations that fix some of the problems, but anything not used by Sphinx is rather useless.)I used to have READMEs of Python projects in reST because of PyPI long_description; those were converted to Markdown soon after PyPI started supporting Markdown. Now I write reST exclusively for Sphinx (mostly in the form of autodoc), but need to check documentation all the time.

评论 #22678693 未加载

dfeeabout 5 years ago

I have documented a moderately complex package in RST [0]/[1] and another in MDX (and a mix of MD & JS) [2]/[3] and have tons of $company docs written in MD.My thought is that RST is probably closer on the spectrum to LaTeX (despite still being far away) as it’s a more powerful syntax with a more esoteric format.If you’re a sole contributor or want to limit your contributors to those who know or have the patience to learn this, then sure, use RST.Otherwise, documentation is a team sport. Write in whichever format will let people get ideas down fastest and can most easily be coerced it formatted text. Right now, the best option for that is MD.These aren’t algorithms, so trade power for participation.[0] <a href="https://github.com/dfee/forge/tree/master/docs" rel="nofollow">https://github.com/dfee/forge/tree/master/docs</a>[1] <a href="http://python-forge.rtfd.io/" rel="nofollow">http://python-forge.rtfd.io/</a>[2] <a href="https://github.com/dfee/forge" rel="nofollow">https://github.com/dfee/forge</a>[3] <a href="https://dfee.github.io/rbx" rel="nofollow">https://dfee.github.io/rbx</a>

GordonSabout 5 years ago

I've been writing all my documentation in AsciiDoc for the past few years, and I love it! As another commenter mentioned, it's even compatible with markdown.I previously used Microsoft Word for all documentation, but the lack of human-readable diffs in source control was a PITA, and some features are just much better in IDEs that Word (e.g. search and replace with regex).

kickabout 5 years ago

This person's criticism is silly. Markdown documents are extensible: the entire point is that it makes the main parts require less cognitive load, and allows you to use HTML for the rest.<pre><code> ## CHAPTER IV. #The <white>Rabbit</white> Sends in a Little Bill It was the <white>White Rabbit</white>, trotting slowly back again, and looking anxiously about as it went, as if it had lost something; and she heard it muttering to itself *“<red>The Duchess</red>! <red>The Duchess</red>! Oh my dear paws! Oh my fur and whiskers! She’ll get me executed, as sure as ferrets are ferrets! Where can I have dropped them, I wonder?”* <gold>Alice</gold> guessed in a moment that it was looking for the fan and the pair of white kid gloves, and she very good-naturedly began hunting about for them, but they were nowhere to be seen—everything seemed to have changed since her swim in the pool, and the great hall, with the glass table and the little door, had vanished completely. </code></pre> Just write the two lines of CSS required for those elements, and bam! You're all good!They criticize this within, but their criticism isn't particularly strong: sure, the point of Markdown is to write less HTML, but in this instance, the HTML is about as semantically concise as you can get: the quickest solution in any system. Their comment on hybrid documents also doesn't really work in the context of most parsers.

评论 #22680229 未加载

评论 #22678715 未加载

arthurofbabylonabout 5 years ago

There’s sentiment here on HN that any documentation is good documentation - and while it is better than NO documentation, it’s just not correct to dismiss truly great documentation.For example, Stripe (the workplace of the author) has incredible documentation that single-handedly enabled me to build with it, despite my being a wretched server-side developer.That the documentation alone doubled the potential user-base, thus fostering growth and engagement with the product, is a testament to the power of great document versus just documentation.V1 docs in markdown - fine. But V2 for an ambitious tool should probably start approaching what Stripe is accomplishing.

评论 #22683516 未加载

评论 #22676606 未加载

评论 #22681693 未加载

virtualritzabout 5 years ago

I've been using ReST w. Sphinx since years and it's not the answer either.Consider this simple fail of nested styling:<pre><code> *I am italic but also **bold**.*. </code></pre> This produces (all in italics but lacking any bold text):<pre><code> I am italic but also **bold*.* </code></pre> If you assumed asterisks could be stacked; nope:<pre><code> *I am italic but also *bold*.*. </code></pre> Produces (all in italics but lacking any bold text):<pre><code> I am italic but also *bold.* </code></pre> ReST/Sphinx can't do this. Doh! Because of this you can also not have styling in e.g. link texts etc.These limitations seem unnecessary and random. For example, when the parser handles a table, which is also just marker symbols for cells, you can have styled text or links in the cell's text. Why this works but nesting styles doesn't is completely beyond me.

goodSyntaxabout 5 years ago

Rust documentation uses markdown and it is amazing. Not sure what this person is on about. Everyone also knows Markdown very well. Also, if you are trying to color certain parts of your documentation blue, I think you're focusing on the wrong things.... Documentation should be about example code, which is perfectly fine in Markdown, you simply go:```code <example> ```Also I don't agree with the author's points about links in Markdown whatsoever.

评论 #22680857 未加载

paultopiaabout 5 years ago

This seems quite silly. As many other people have said in these comments, RST is an obscure mess. By contrast, Markdown is supported by every editor, every static site generator, countless other applications, and is trivial to learn and to use.Also silly is to complain about stuff that everyone uses, like tables, not being part of the markdown spec. We have amazing tooling around markdown, like pandoc, who cares whether it's part of the spec?

h3raldabout 5 years ago

I beg to (partially) disagree... (shameless plug ahead!)<a href="https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm" rel="nofollow">https://h3rald.com/hastyscribe/HastyScribe_UserGuide.htm</a>OK, you are right that ordinary markdown is insufficient because a lot of functionalities are missing for proper technical writing and above all proper content reuse...That's why in my tool I started from an already fairly-advanced Markdown flavor (Discount) which already comes with a bunch of proprietary extension... then on top of that I added things like snippets, transclusions, fields, and even simple macros.

thangalinabout 5 years ago

My blog dives into Markdown, Pandoc, R, bash, and the ConTeXt typesetting engine.<a href="https://dave.autonoma.ca/blog/" rel="nofollow">https://dave.autonoma.ca/blog/</a>Part 8 (coming soon!) uses annotated Markdown to reproduce a famous poem (original is on the left):<a href="https://i.imgur.com/idV1mTM.png" rel="nofollow">https://i.imgur.com/idV1mTM.png</a>The text of the poem is written in Pandoc-flavoured Markdown:<pre><code> ::: poem Some say the world will end in fire, Some say in ice. From what I’ve tasted of desire I hold with those who favor fire. But if it had to perish twice, I think I know enough of hate To say that for destruction ice Is also great, And would suffice. ::: </code></pre> > Markdown is good for generating HTML and terrible for making PDFs.²Yes, Pandoc is essential for transforming Markdown into beautiful PDF files. Tooting my own horn a little more, my illustrated photobook, Impacts, is written almost entirely in pure Markdown, with a few annotations for plots and spectra:<a href="https://impacts.to/preview.html" rel="nofollow">https://impacts.to/preview.html</a>Tangentially related, what would be amazing is a robust text editor that allows injection of interpolated string variables from various data sources and structured data formats. Here's an architecture diagram to clarify:<a href="https://i.imgur.com/8IMpAkN.png" rel="nofollow">https://i.imgur.com/8IMpAkN.png</a>My open-source editor, Scrivenvar (<a href="https://github.com/DaveJarvis/scrivenvar" rel="nofollow">https://github.com/DaveJarvis/scrivenvar</a>), implements that architecture to some extent.

soulnothingabout 5 years ago

I'm a big proponent of contract and document based development. Easing on boarding, and correlating the current architecture with active documentation. I usually keep software centric, in git along side the code.Coming from Python I was a big fan of sphinx. With Graphviz we were able to embed flow charts of micro services. It worked very well. There are a number of extensions made it very powerful.I switched because it felt close to markdown but not markdown. I now use docsify[0].js. There are a few things I miss. But it's an easier transition as my docstrings are also markdown. So no context switching.Markdown is very bare. But that I feel keeps the documentation simple. With less knobs to twist, the documentation has less accents to it. With that limited range I feel it's more important to have a style guide.[0] <a href="https://docsify.js.org/#/" rel="nofollow">https://docsify.js.org/#/</a>

nnqabout 5 years ago

...Org mode anyone? <a href="https://orgmode.org/" rel="nofollow">https://orgmode.org/</a>

chubotabout 5 years ago

The best part of Markdown is that you can embed HTML, and the author gets it wrong by saying you can't mix the two freely.In CommonMark (and thus most modern Markdown implementations) you can embed Markdown in HTML like this:<pre><code> <table><tr><td> *This is markdown* </td></tr></table> </code></pre> You need blank lines before and after the tags.I think you could do this in markdown.pl but there were some quirks/limitations.----Related: CommonMark is a Useful, High-Quality Project<a href="http://www.oilshell.org/blog/2018/02/14.html" rel="nofollow">http://www.oilshell.org/blog/2018/02/14.html</a>

csoursabout 5 years ago

Invoking Cunningham's Law:Appeal to Mundanity: I've supported dozens of systems over the last 15 years, here are my opinions:The best documentation is the implementation.The second best documentation is any documentation at all.The better you reveal your implementation, the better your documentation.If you want to improve your second best documentation, knock yourself out. Concentrate on documenting interfaces and the location of your primary documentation (the source code, settings, etc)If you want to bikeshed your second best documentation, I'm afraid I'm just going to laugh at you.

luckyorlameabout 5 years ago

Please don't write "Please don't write your documentation in Markdown"

bjoliabout 5 years ago

XML solves these problems a long time ago. It has been abused so much that people don't consider it anymore, but I have been using 2 personal DTDs since about 2005 and I have been laughing every time people have complained about whatever shortcomings their markup language of choice has.you can use any programming language to work with it, and using scheme and SSAX makes even XSLT a breeze.

ChuckMcMabout 5 years ago

So many re-inventing SCRIBE from the '80s. Kind of funny actually.In the 70's and 80's we used ASCII terminals to edit documentation, and only some terminals supported attributes like bold, italic, and underline. But you needed to be able to read it in its "raw" form.So there were many systems developed that let you put the "markup" inside the document and keep it as reasonable as possible. The one I wrote a number of term papers in was SCRIBE that ran on the TENEX later TOPS20 machine and put the "final" output to a Diablo Hytype printer.Consider that you had a team of 20 software developers working to build a software package for writing text documents that could both be read when being created/edited and later processed into beautifully typeset documents using a film typesetter.This in contrast to a developer saying "hmm I'm putting up all this stuff in HTML and typing too much, I'll add a few shortcuts here, here, and here. Ta da! It works for me."The availability of cheap dot matrix displays and "desktop publishing" set aside all those goals of editing with a text editor and instead using "WYSIWYG" environments of increasing complexity and bloat.I applaud the reStructuredText people for wanting to attack the problem but I really wish they could look at what has already been done in this space to avoid the mistakes of the past. A version of SCRIBE that was UTF-8 clean would be pretty awesome as a starting point.In my own workflow I find working in text faster because if I use a WYSIWYG editor I get so distracted by it looking "wrong" that I can't focus on the text itself. I would truly love something that was TMWYW (tell me what you want) rather than something that keeps trying to show me what it thinks I want.

评论 #22681251 未加载

gravypodabout 5 years ago

Many people I've worked with in the past have unfortunately shared the sentiment of the author. I think the issue is sustainability of documentation practices. There's a desire path that engineers exhibit when writing docs. We just want to write something and have others be able to read it. Markdown is the lowest barrier of entry because, even without any special characters, my plain text will look "fine" in Markdown. Nothing is truely required.To me the two most important things are:1. Docs are tracked with software updates (track in VCS)2. Enable me to spend less time writing docs and more time writing codeGoogle documented their experiments with markdown documentation here: <a href="https://www.usenix.org/sites/default/files/conference/protected-files/srecon16europe_slides_macnamara.pdf" rel="nofollow">https://www.usenix.org/sites/default/files/conference/protec...</a>

oweilerabout 5 years ago

With Pandoc you can easily generate LaTeX from Markdown and then turn that into a PDF. This gives you best of both worlds.

评论 #22676911 未加载

评论 #22675696 未加载

biggestlouabout 5 years ago

I implore you: do not use anything but Markdown in environments where software engineers will be writing and maintaining the bulk of the documentation. I once worked on the docs team for a large org that used rST/Sphinx. Engineers complained incessantly and it was a constant struggle to cajole them to keep docs up to date.My experience suggests unambiguously that engineers will not take the time to learn a different markup format. They will spend hours or days or weeks learning a new language, deployment tool, protocol, library, etc. But in most cases they will simply refuse to spend one iota of time learning documentation tools. If you think I'm wrong, try making it your day job to get engineers to write rST (or Asciidoc or anything they don't already know).

评论 #22681501 未加载

ceejayozabout 5 years ago

> What if you want to have some things in the documentation be colored blue? You can’t!Maybe that's good, though. "Blue" isn't semantic, either.

ComputerGuruabout 5 years ago

RST is terrible. The idea is great, but the ball was dropped on the execution.We switched to restructured text for fish, and I remember the insane loopholes I had to jump through to render the markdown equivalent of `followed by a trailing space ` because Sphinx absolutely insisted on eating that trailing space.. and there’s no way to actually explicitly define an inline code block so I could bypass the abstraction (whereas with Markdown I could always just insert a code element).And don’t get me started on the inability to nest markup. What a joke. You can’t bill something as a “more legitimate documentation language” when you’re not even at feature parity with Markdown.

评论 #22681510 未加载

anonuabout 5 years ago

Most people will agree documentation is hard and painful. Engineers like to build and have someone else maintain and support. Im talking in generalities - so don't get too offended if thats not you.So it follows that you should reduce the critical path to documentation down to the path of least resistance. Markdown tools are plentiful. If you use GitHub, it is the core of their project management tools.Also, you want documentation to be a "living & breathing document" - in the sense that it should be updated and modifiable by everyone. A LaTeX-like solution doesn't lend itself easily to collaborative work.

johnminterabout 5 years ago

Use what works for you and we will use what works for us.Markdown is a great tool for documentation, especially using tools like RStudio and Rmarkdown. These tools typically use pandoc under the hood to let an author generate whatever they need - HTML, PDF, Word documents, Power Point slides...Because Markdown (and the tools mentioned above) produces a text document, this plays well with version control using git and github. Indeed github renders markdown files in the browser. These tools have been embraced by scientists who want to generate reproducible documents.

lucideerabout 5 years ago

I was unconvinced going in, but this is a compelling piece. Not dogmatic, very open to various alternatives. Highlights their advantages and Markdown's disadvantages without becoming laborious.

staredabout 5 years ago

Sigh. Markdown is "good enough". If it helps writing documentation, it is a good tool.What I struggle with is documentations that are incomplete (e.g. miss crucial, "obvious" installing steps), out-of-date, or incomprehensible. Often external contributors help (especially newbies), as they look at your project with a fresh eye, taking nothing for granted.If for a given project .rst is better than .md, cool. And if you generate HTML from it, end-users won't care what was your base format.

eeZah7Uxabout 5 years ago

Markdown and reStructuredText are very limited, and the latter is awkward and unfriendly.Use AsciiDoc. It scales up to entire books. It's extendable by design.It supports embedding diagrams, maths & so on.

评论 #22678703 未加载

kvzabout 5 years ago

I love Nix but even their core contributors agree the available documentation and broader information in the form of blog posts and tutorials in the ecosystem is subpar. I think the refusal to use Markdown and hence profit from more contributors is a big factor there. Sometimes it’s good to be a purist, and it has gotten Nix where it is today, but hanging on to ‘superior’ documentation formats can hurt growth and a dash of pragmatism would really help.

gfioravabout 5 years ago

It's never the best standard that wins, it's the most convenient.Figure out how to parse .md (or whatever is the standard) instead of pretending others switch to your standard.

rikrootsabout 5 years ago

Many years ago I made the mistake of documenting my Javascript library thing by building static web pages to explain it all. They became a nightmare to maintain, and made me scared to update anything in my library thing because it meant having to fix the web pages too.A while later, during a significant recode exercise, I tried a different solution. Inline code documentation with YUIDoc - which was much better. Except YUIDoc assumes people are writing their Javascript in an Object Oriented way. My library thing didn't have a single class in it. The generated documentation just didn't make sense ... but by the time I realised this I had almost completed the documentation exercise and wasn't going to waste the work. So I also updated the static web pages too (finally!) and presented both sets of documentation on the Javascript library thing's website.The thought of having to document changes and updates in two sets of documentation stopped me working on my Javascript library thing for over TWO years.Last year, when I made the decision to rewrite my Javascript library thing from scratch, I also made the decision to dump all the documentation. Instead I wrote it as inline comments in simple Markdown - the most basic flavour available - and used a tool to auto-generate documentation from that (I've ended up using docco - it does the job).Dumping all the documentation baggage has made me massively happier, and given me renewed love for working on my Javascript library thing.... As for project runbooks? I write them in Google docs. If a client ever demands to see their project's runbook (please God no!), I can create a PDF of the latest version and email it to them.

myu701about 5 years ago

I agree with the limitations of Markdown re: it being not great at doing some quality of life things like same-document references or embedding images as base64.I would enjoy those two features, can we add 'em? MD files would basically be able to replace RTFs in all but the older OLE stuff in the latter.But...even though I wish for those two, I have some sense that these things would start us down the slippery slope of bloating markdown to be HTML 2020(TM)

评论 #22675658 未加载

yellowappleabout 5 years ago

> Kidding. LaTeX is extremely powerful but also a nightmare to use and almost impossible to turn into online documentation.htlatex: "Am I a joke to you?"----I can't really speak to either rST or AsciiDoc (since I don't use either of them nearly enough to be comfortable with their pros and cons), but aside from LaTeX (via htlatex or Pandoc or some similarly-useful way to export to HTML for online use), I've also seen POD ("Plain Ol' Documentation") and outright manpages as effective choices here. Both are designed specifically for documentation (in the case of POD, inline documentation), and both are demonstrably able to produce a variety of output formats, including HTML for online use.That said, I also don't see why Markdown (or a more robustly-defined version thereof) couldn't be used to do the things rST can apparently do, especially when combined with a preprocessor (like what you'd almost certainly be using when generating documentation from e.g. source code comments like what quite a few modern programming languages support; on that note, quite a few of those languages do use Markdown for inline docs).

tannhaeuserabout 5 years ago

Obviously, the best documentation is the one that exists in the first place, and markdown is a very low-friction way to document things.That said, FWIW, using markdown vs highly "semantically" structured text doesn't need to be an exclusive-or choice. Citing from sgmljs.net markdown (markdown-in-SGML):> sgmljs.net Markdown is presented as an application of the SGML SHORTREF feature, which is an SGML mechanism to describe custom Wiki or other domain-specific syntax. Whereas in regular markdown it's possible to use HTML markup, in sgmljs.net Markdown it's also possible to use SGML markup and other constructs, bringing SGML's vast facilities for text organization and processing to markdown in a natural way. [1]For example, to annotate HTML's text spans semantically with RDFa or whatever, add context-dependent CSS classes, perform transformations, define custom syntax on top of markdown, customize markdown flavours such as github's, use text macros, add page boilerplate, etc.[1]: <a href="http://sgmljs.net/docs/markdown.html" rel="nofollow">http://sgmljs.net/docs/markdown.html</a> (my site)

umviabout 5 years ago

Markdown is the best. It's plain-text, meaning it can be version controlled. You can transform it to other formats with pandoc. It supports most common formatting options.I'm sorry, but "no color support" is not a compelling reason to switch to something more complicated. Define your own color meta-tag and generate a PDF from the markdown with colors if you care that much.

BeetleBabout 5 years ago

I used to think rst was a great solution. It is in many ways better than markdown.Then I tried using it. For a few years. To be honest, while certainly better than LaTeX and HTML in terms of ease of typing it still felt like typing with road bumps.These days I just use orgmode and then use pandoc to convert to rst for my Pelican blog. It's not as powerful as rst but at least it's not markdown.

bloakabout 5 years ago

One of the many things that annoy me about Markdown is the complexity of generating it and the difficulty of converting a Markdown document into a normal form. However recently I stumbled across this project:<a href="https://github.com/bobertlo/vmd" rel="nofollow">https://github.com/bobertlo/vmd</a>I've not tried it, but it sounds interesting.

paulsutterabout 5 years ago

Good documentation is whatever actually gets written. This reminds me of all the “semantic web” dreams that never happened.> Good documentation is all about the semantic markup. A “definition” is not just a different formatting or like. It means there’s actually a concept of a “definition” as a discrete concept in your documentation.

评论 #22675873 未加载

jkingsberyabout 5 years ago

As others have said... if you have extra time to optimize how you write documentation, fine, but just get something written. Actually... if you have extra time, take the time to write your documentation well - make it clear, consider who the audience is, spend some time thinking about how to organize the information, and so on. If you still have extra time, then it's time to worry about latex vs. xml vs. html vs. plain text vs. Word vs. Wiki vs. RTF.The company I work for has a wiki that most teams use for documentation, and that generally works pretty well - for most uses, you can use the WYSIWYG editor, and if you need something more precise you can use the wiki text editor.

Nikskoabout 5 years ago

The answer, as always, is that it depends.If you need to make some scribbles to describe a project, markdown will do. All of the things in this article are valid, but they're really don't apply to barebones documentation.If you need some more formatting and bells and whistles, then you graduate to something that supports macros and a is a more fully fledged tool (eg. Hugo). These tools solve these problems, while (generally) keeping the user-friendliness of markdown. At least if you build some sort of complex behemoth of a publishing system with macros and custom styling and all sorts of things, if somebody needs to make a small content change, you using markdown will be a saving grace.

d_burfootabout 5 years ago

I don't have a strong opinion about the base format, but one of my strongest technical opinions is that all documentation should be computable - that is, it should be generated by a program that's linked together with the code it's describing. You should reference particular code structures in the docs, and if the docs gets out of date it should break so that you're not lying to the reader about what's going on. Depending on how deep you want to go, you can also interact with the base code a bit in the doc-generator, showing particular input/output results, or show a few records from a DB table, etc.

manigandhamabout 5 years ago

Any documentation is better than none, so whatever is easiest is the best. And currently that's Markdown. RST isn't even close.Most projects don't need anything more than the headings, lists, paragraphs, and code-blocks anyway.

simiasabout 5 years ago

I thought that the author would make the case that technical doc should we written in some semantic format that could then easily be re-processed for various use cases which I could sort of understand (although any doc is better than no docs, so if Markdown helps with that I'm all for docs.md).But "my markup language is better than your markup language" is not very productive IMO. The fact that markdown lacks some advanced formatting tools might even be considered a feature, it means that it will render correctly when converted to monochrome output for instance.

threatofrainabout 5 years ago

How about MDX (Markdown + JSX)?<a href="https://mdxjs.com" rel="nofollow">https://mdxjs.com</a><a href="https://github.com/mdx-js/mdx" rel="nofollow">https://github.com/mdx-js/mdx</a>

jasonvabout 5 years ago

Anyone have recommendations on how to write a really structured book? I've been working on a text and I really want each section of chapters to be formatted identically, but also be editable, so that I can edit the chapter definitions, re-publish and merge with content I've already been working on.Sometimes I go into a tool like Airtable to define content pieces, but there are a lot of pieces.What I'm looking for is a way to define a chapter/sub-chapter recipe and work on iterative changes to content even as I refine the recipe definitions.

评论 #22679034 未加载

评论 #22677053 未加载

评论 #22680447 未加载

评论 #22676235 未加载

评论 #22675917 未加载

binarycrusaderabout 5 years ago

The wonderful markdeep addresses many of the author’s concerns:<a href="https://casual-effects.com/markdeep/" rel="nofollow">https://casual-effects.com/markdeep/</a>

gjvcabout 5 years ago

I'll use whatever I damn well please. Don't tread on me!

lajrabout 5 years ago

I think the limitations of markdown make it great for README documentation. It allows uniform, easy-to-parse instructions on how to use any repository. I don't even necessarily agree in terms of full documentation sites. Services like Gitbook or libraries like Gatsby allow you to set up great documentation sites using markdown. The points made about each unique syntax requiring it's own parser doesn't seem like a significant obstacle to me.

glofishabout 5 years ago

I tried reStructuredText and I found that writing hyperlinks was very tedious and ugly. Here is the example from the tutorial<pre><code> External hyperlinks, like `Python <http://www.python.org/>`_. </code></pre> Look at how many special characters it needs and how interferes with reading.I found it annoying and tiring to write and to read. It is the main reason I went with Markdown.RST may be superior technology-wise but it inferior when it comes to usability

评论 #22681534 未加载

anderspitmanabout 5 years ago

While making my blog browsable with curl[0] recently, I realized that I haven't been appreciating the human-readable aspect of Markdown. Text-heavy content doesn't always need another layer of abstractions (HTML/CSS/JS), nor the huge dependencies that come with them (browsers).[0] <a href="https://anderspitman.net/17/#curlable" rel="nofollow">https://anderspitman.net/17/#curlable</a>

k__about 5 years ago

Back in the days we used DocBook for documentation, because it's medium independent.When I read that AsciiDoc is a Markdown-like syntax for DocBook, I was instantly sold.

dmitshurabout 5 years ago

I’m glad there are some languages that define a simple convention for writing documentation as comments in code directly above the symbol, and tools for automatically extracting and displaying that documentation.I prefer knowing where to look for documentation in any project, rather than having to guess where some Markdown or HTML or RST files might be, separated from code.

ashildrabout 5 years ago

I and my team use two tools for documentation: - markdown (+ plantuml), because that’s plainext with not enough rules to bother them and keep them away from what they actually want to do. And it can do tables. - LaTeX, because if you already decided to do it properly and put away the IDE you can use the big tools and not something in between

nobodywillobsrvabout 5 years ago

What I really want is a Makefile that is also Markdown.So something with runnable (singleton) entry points and some english sentences giving context.This is what I typically do for small experiments that I will completely forget about.Too many IT folks do work and leave the running-entry-point and build-dev-loop as secret shadow workflows. It is basically fraud or stealing if you are an employee.

markus_zhangabout 5 years ago

To be serious, anything but Confluence. I have had enough with that and have to continue endure its existence for many more years. I use RST when I'm programming in PyCharm (support out of box I think), and use MD in other places.BTW I think Typora is a nice MD tool as it supports copy-paste of screenshots, extremely useful when writing tech documents.

评论 #22680468 未加载

savhabout 5 years ago

Obviously well written documentation is never easy and documentation format also depends on use case. For most of my needs Markdown is good enough. It's easy to learn, easy to use and well supported.I like to think that its simplicity (or lack of features) forces me to just focus on simple text to write easy to understand documentation.

arkanciscanabout 5 years ago

Please don't write long articles about why people shouldn't do something you don't like on the Internet.

rs23296008n1about 5 years ago

Mixed feelings about markdown. I think its great but the number of dialects is likely a possible issue. Perhaps a linter or sanity checker is required? Tables are an example, but no reason to dump markdown.But I'll still write markdown since its easy to generate and relatively easy to transform into a lot of something else.

madsbuchabout 5 years ago

I wrote my entire thesis using markdown as a super set of latex. I agree with the sentiment of the article, that for efficient documentation you need for building blocks. But I am still very happy about using markdown as a super set of other markup languages (HTML, latex, etc.) for friction less prose writing.

e2e4about 5 years ago

Amount of documentation (comments) still seems to be an open question.e.g. Bob Martin (Clean Code) wrote: > A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail. > <a href="https://mobile.twitter.com/unclebobmartin/status/870311898545258497?lang=en" rel="nofollow">https://mobile.twitter.com/unclebobmartin/status/87031189854...</a>I use to be proponent of comments throughout the code. But lately, am leaning more and more towards minimization through proper naming, annotation, function design (e.g. no side effects, single functionality).Here are some related materials:A more complete quote from `Clean Code` > Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation. > > Comments are not like Schindler's List. They are not "pure good." Indeed, comments are, at best, a necessary evil. If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much -- perhaps not at all. > > The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. > > So when you find yourself in a position where you need to write a comment, think it through and see whether there isn't some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression.Previous related Discussions on NH: <a href="https://news.ycombinator.com/item?id=8073230" rel="nofollow">https://news.ycombinator.com/item?id=8073230</a> <a href="https://news.ycombinator.com/item?id=8073620" rel="nofollow">https://news.ycombinator.com/item?id=8073620</a><a href="https://softwareengineering.stackexchange.com/questions/285787/clean-code-comments-vs-class-documentation" rel="nofollow">https://softwareengineering.stackexchange.com/questions/2857...</a>

评论 #22684612 未加载

turbinerneiterabout 5 years ago

Pandoc solves most of the shortcomings of markdown. I've written papers and Thesis with it. The main problem is that it isn't standard and some missing features need additional plugins. So your pandoc-flavourved markdown doesn't properly render in GitLab/GitHub.

jacoblambdaabout 5 years ago

I went into this article fully expecting to disagree but I think it makes a valid point. Plain Markdown definitely has issues that cause me to gripe to no end. These however are mostly resolved via extensions. The author argues that Markdown isn't a good choice since it lacks these features without modifying the standard however I don't think extensions are too big of an issue.If the extensions are part of the build script for processing the documentation then ultimately the user and consuming developers won't notice the difference between this and using another markup language.Hell one of the documentation pipelines I see quite often is the Doxygen + Breathe + Sphynx pipeline. This handles the markdown and offers most of those extensions mentioned by the author out of the box.If your documentation pipeline works well and the user can't tell the difference, there's no reason to switch. Markdown works and is more elegant to write in than LaTeX and rST by just about every measure in my eyes.One last note is that every markup language has it's own special blemishes and issues. LaTeX and rST are very much not immune to this and when it comes down to it, a properly built doc pipeline will cover these up no matter the language.TL;DR: If Markdown is making your life difficult it's probably not Markdown that's broken, it's probably your documentation pipeline.

oplessabout 5 years ago

If you're worrying about what format you're writing documentation in, I'd offer the actual motive is that rather than actually writing documentation you’re finding excuses not to write it.Just write a text file.Pretty it up when you’re trying not to think about a problem that you’re stuck on.

hn_throwaway_99about 5 years ago

I feel like an analogous discussion could be "please don't serialize your objects as JSON". But for all its warts and shortcomings there is a good reason JSON has become the format of choice in many domains. The same can be said of Markdown.

评论 #22680168 未加载

david_dracoabout 5 years ago

rst is great because there are tools to handle it installed already on many Linux distributions, such as: rst2html, rst2latex, rst2man, rst2odt ...Many tools that support markdown actually also support rst. For example, write a README.rst on github instead of a README.md.

评论 #22676009 未加载

nilsandreyabout 5 years ago

Please, write your documentation in whatever tool you like, including Markdown, and being Markdown better than others like a word document or directly PDF for accompanying code. If it's about a code, better living with him in the same repo.

cestithabout 5 years ago

I tend to use POD, but that's from many years in the Perl ecosystem and the tools like pod2man and pod2html that make it so easy to convert. LaTEX or AsciiDOC - or, heck, XML or SGML or DocBook - also work if you need semantic data.

评论 #22676108 未加载

tunesmithabout 5 years ago

I started switching from markdown to asciidoc for my code project documentation, and it was much easier than I expected. For simple docs it's almost exactly like Markdown, and its IntelliJ plugin is better, too.

the_arunabout 5 years ago

When we say documentation, it depends on what kind of documentation it is. IMHO Markdown is perfectly alright for API documentation. But are there better tools for that? I'm finding Sphinx is an overkill.

emmanueloga_about 5 years ago

I agree markdown is not great for documentation. I'm writing a little site generator for my blog and after exploring a a lot of different options I decided to come up with my own format!XML is a great way to write structured documentation. It is the best option for "mixed content", that is, content that has character data, optionally interspersed with structured elements. The problem is that most standard XML documentation formats (docbook, dita, etc.) are heavy and most times overkill. I'm using RelaxNG [2] to create a schema of my custom format document [2], and a bit of XSLT3 [3] to generate HTML5.RelaxNG is great, and pretty easy to use. You can think of it as a "regular expression over trees". The syntax is pretty intuitive, specially the compact form (there's an XML form too). For instance:<pre><code> start = element doc { attribute title { text } ?, element p { text } * } </code></pre> ... defines the schema for a document that should have a "doc" root tag, an optional title attribute, and 0 or more "p" elements, that should contain only text.The way I went about it, I'm just inspiring my format in a small subset of HTML5, plus some tags that I want to use to provide more structured information.XSLT 3.0 came a long way since the version 1.0 that everybody remembers and loathes. Now, XSLT3 has maps, arrays, functions, higher order functions, and all sort of other goodies that people have come to expect from a modern programming language. Yeah, you still need to get pass the XML syntax, but it is not a big deal once you get the hang of it.Finally, writing XML "by hand" is not a big deal neither. I'm using Emacs with the nxml and emmet [4] package, and I just needed to learn a few keystrokes for doing things like automatically closing tags. Emmet is amazing and fun to use to create small chunks of content at a time.1: <a href="https://en.wikipedia.org/wiki/RELAX_NG" rel="nofollow">https://en.wikipedia.org/wiki/RELAX_NG</a>2: <a href="https://gist.github.com/EmmanuelOga/39ddb345c2a499690e728e5908e942f2" rel="nofollow">https://gist.github.com/EmmanuelOga/39ddb345c2a499690e728e59...</a>3: <a href="https://stackoverflow.com/tags/xslt-3.0/info" rel="nofollow">https://stackoverflow.com/tags/xslt-3.0/info</a>4: <a href="https://emmet.io/" rel="nofollow">https://emmet.io/</a>

Skunkletonabout 5 years ago

I would rather have markup free documentation than no documentation at all. Many of the documentation markup languages have a pretty significant overhead. There is a reason markdown is so common for docs.

tbergeronabout 5 years ago

This place is becoming a meme of itself more and more each and every day.

评论 #22683133 未加载

评论 #22676174 未加载

samsquireabout 5 years ago

I've written a flat HTML renderer.<a href="http://github.com/samsquire/flat-html" rel="nofollow">http://github.com/samsquire/flat-html</a>Could be an alternative to HTML and Markdown

Guthurabout 5 years ago

We all know it's XML but everyone is too scared to admit it.It's simultaneously the best and worst tool we have for structured semantically rich information. And unfortunately probably the only one.

movedxabout 5 years ago

I’d say my website, which is a growing knowledge base for CloudOps related matters, works really rather quite nicely: <a href="https://thecloud.coach/" rel="nofollow">https://thecloud.coach/</a>Thanks to MkDocs and the Material theme, as well as plugins and extension, this whole setup looks great and scales really well to any device.I think the author’s article speaks purely to documenting code. I’d say code is much harder to document and I think I’d agree even MkDocs (and the setup I’m using) wouldn’t be good for pure code documentation. But documentation for a project?Nah. You’re completely wrong on this one.Edit: down voting without providing as rebuttal is childish, at best.

jason_slackabout 5 years ago

As a technical writer, I write everything in Markdown.Sure, it could use some features.Does anyone know how a developer could contribute to the markdown standard and code up some desired markdown features?

jeffdavisabout 5 years ago

It's two different philosophies of publishing. Markdown mixes style with meaning. Something like latex separates meaning from style.

sagichmalabout 5 years ago

> Markdown is about formatting, not information> Not extendable> Local processing only> HTML OnlyI don't get it. These are all extraordinary virtues of Markdown, not negatives.

评论 #22676850 未加载

dbg31415about 5 years ago

Hey, do you know how few projects have good documentation? Or any documentation?Write it in whatever you want to write it in, just write it.

phy6about 5 years ago

Beware of things that are fun to argue.

l0b0about 5 years ago

Reality check: what is your budget for documentation? "As little as possible" says the vast majority. OK then, Markdown it is. For anyone else, sure, spend a few days setting up LaTeX to actually produce PDFs (no, PostScript is not end user friendly) and a few weeks duplicating the Markdown you already knew how to write because you know ASCII formatting and basic HTML.

mnotabout 5 years ago

And yet, many RFCs are written in markdown now. And variants like kramdown do support semantic markup.

schnableabout 5 years ago

I almost closed this page when he suggested LaTeX. Glad I read the next line :).

teknopaulabout 5 years ago

Pfff. Imagine the state of the github if everybody wrote documentation in HTML.

AzzieElbababout 5 years ago

Markdown, shmarkdown. Just write some documentation please.

paolabout 5 years ago

TL;DR Don't use Markdown, use RST (reStrucruredText)My take: meh.RST is very comparable to Markdown, and the article makes almost no mention of why it is better. There is a downside, that it has a learning curve because most people are not familiar with it, whereas almost everyone has already used markdown.

评论 #22676245 未加载

评论 #22676553 未加载

throwaway3563about 5 years ago

Please don’t tell me what not to do, it’s considered harmful.Especially please don’t tell me to ignore an industry standard only to offer some bespoke solution as an alternative.

评论 #22676738 未加载

mcguireabout 5 years ago

Tl;dr: "Good documentation is all about the semantic markup."Well, ok, I'll buy that."What to use instead: LaTeX. [Just kidding.] A better answer is reStructuredText or RST. [Or AsciiDoc.]"Er, well, ... RST does have extension syntax that allows you some flexibility to use semantic markup, but then the tools all have to understand the extensions you use. LaTeX at least has the ability to define the meaning of your extensions in its own syntax, but that is not all that much fun.Conclusion: Everything sucks. Sorry.

jasonmp85about 5 years ago

Counterpoint: no.

jhokansonabout 5 years ago

Thanks i

exabrialabout 5 years ago

The only problem I see with markdown is the lack of an IETF spec. But then we run into the XKCD problem...

brian_herman__about 5 years ago

Please don't make platitudes and decisions for everyone.