Re:Why I Prefer RST to Markdown
by unethical_ban on Wednesday July 31, 2024 @03:16PM
(#41122437)
Yes!
Markdown is great because it is a way to write and store documentation in plaintext, in a way non-documentarians can follow.
And it's been making a ton of headway even outside that context -- I've seen occasional formatting goofs in online newspaper articles that indicated they were authoring their content in Markdown. (Which makes sense! News rarely requires complex formatting.)
Yes, though I would expect most news-folks to use some form of WYSIWYG for writing?
Re:Why I Prefer RST to Markdown
by zelphirkalt on Wednesday July 31, 2024 @04:33PM
(#41123147)
Although, I have to say, it is a sad state of afairs, if rST is already too difficult for a person with the job role "programmer" to use. If this is already the threshold, which would stop them from writing documentation, then I have my doubts about the quality of documentation, that they will write in Markdown.
Small barriers matter. Anything that kicks you out of the flow makes a huge difference. And rST is confusing enough often enough to kick you out of the flow.
Re:Why I Prefer RST to Markdown
by fireflash38 on Wednesday July 31, 2024 @04:50PM
(#41123317)
Agreed. Mandate function docstrings? You'll get "Function FlargleBlab blabs the flargle" docstrings. Just useless.
Ironically, that was my argument for getting rid of Confluence. Confluence should be the low barrier to entry solution, but its buggy, clunky GUI ends up actively punishing anyone who dares try to update docs. So a repo full of markdown files with a self-merge pipeline ends up being lower-resistance.
Re:Why I Prefer RST to Markdown
by AndIHateLatex on Wednesday July 31, 2024 @09:41PM
(#41125432)
I wonder if Spotify was right on the money with their Techdocs approach. It's all just Markdown files being rendered in another format, and the edit button is just sends you to a github or equivalent editing page. People want the idea of a platform... but do they need one?
Well, you could get similar results by just spinning up a copy of the Wikipedia software. Their formatting language even looks enough like markdown in practice (despite appearing earlier).
Markdown is... limited, I acknowledge. But with a very small amount of learning, markdown is as fluent and simple to write as normal text. In fact, 90% of what I wrote before I knew markdown was valid and decently formatted markdown already.
If you asked people who don't document to document in rST or tex... then you'd have no documentation at all. Because that suddenly adds a lot of effort on top of what you want to write down.
Now for some customer-facing whitepapers and documentation, we do use rST. But there you have people who are tasked with paying some effort to create some decently looking docs. Not trying to coax developers into writing down some of their state of mind while doing stuff.