On: ReStructuredText vs. Markdown for documentation

[jonaf]

As a developer, I would LOVE a tech writer to sit next to me and walk me through the best way to write documentation, using the best tools. And by "best," I don't mean what I think is best, I mean what the professional tech writer thinks is best. Until I have the experience to opine to the contrary, it is my responsibility as a software engineer with a mission to produce quality software to care deeply about documentation, even if it's not my full time responsibility. I would love to see more articles about the "how." I would learn a lot and be a better software engineer as a result.

[jquast → jonaf]

I've tried to do this in the past, but there hasn't been much interest at large. I presented this article as a workshop in santa cruz python meetup earlier this year, https://jeffquast.com/post/technical_writing_with_sphinx/

[jonaf → jquast]

Thanks for that, although I don't think those particular tools apply in a polyglot sense, the concepts establish a nice pattern to replicate in other tool chains.

[teddyh → jonaf]

The GNU Coding Standards document has some advice on exactly this:

https://www.gnu.org/prep/standards/standards.html#GNU-Manual...