News for hackers. Stuff that matters.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by thangalin on Friday November 04, 2022 @05:36PM (#33474157)
> Most folks mention that Markdown is not suitable for serious documentation projects.

Here are a few of my PDFs written in Markdown:

* https://pdfhost.io/v/mhw8jCJzw_autnoma

* https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_...

* https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow...

* https://impacts.to/downloads/lowres/impacts.pdf

I think Markdown can be used in serious documentation projects. Admittedly, I am biased, given I've been working on KeenWrite for several years:

https://github.com/DaveJarvis/keenwrite/blob/master/docs/scr...

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by PaulWaldman on Friday November 04, 2022 @05:52PM (#33474363)
These look great! Were these generated with KeenWrite?

I've been generating PDF documentation with Obsidian. The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by thangalin on Friday November 04, 2022 @06:51PM (#33475110)
> These look great! Were these generated with KeenWrite?

Thank you! My sci-fi story, autónoma, is the reason I started to work on KeenWrite, and can be fully generated from within the app. The others could be edited in KeenWrite, but there'd probably need to be some work done to get the HTML/CSS preview panel to display the various annotated sections correctly. Speech bubbles (::: bubbletx and ::: bubblerx), for example, currently work in KeenWrite, but the spectrographic lines in the Impacts Project would need to have special CSS written to render correctly in the preview.

> The challange is when a document will have multi, non-technical, owners. Invariably the "solution" is to open the PDF in Word.

Teaching people to separate content from presentation takes a lot of effort. That's also a process problem. You could ask people to provide feedback by adding notes into the PDF, rather than editing it directly.

At some point it'd be nice to see real-time collaboration added to KeenWrite, which would go a little ways to helping solve multiple users editing a single document:

https://github.com/DaveJarvis/keenwrite/issues/120

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by bitexploder on Saturday November 05, 2022 @12:29AM (#33477975)
We have an entire consulting documentation pipeline build on Pandoc. Everything is written in Markdown. It took a good bit of tooling to make our reports easy to write, but that is mostly automation around our industry specific artifacts. Our reports look quite nice IMO.
Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by edurl on Saturday November 05, 2022 @03:36PM (#33484812)
I would love to know more about this documentation pipeline. Anything you can share (repos, docs, tooling...?)

Thanks.

Re:Markdown, Asciidoc, or reStructuredText – a tale of docs-... by bitexploder on Saturday November 05, 2022 @08:05PM (#33487285)
It’s all internal, unfortunately. It essentially cobbles together markdown documents into a processing pipeline that ultimately makes a PDF. Pandoc does a lot of the heavy lifting getting it all into Latex before PDFing. We have lots of quality of life features around figures, findings, and all the things you expect in a professional report. We use Python doit, and other things to sequence out markdown fragment assembly. We have plugins for processing tool output into markdown and it will run Python and R files that generate markdown as a part of the processing pipeline so you can programmatically generate any content your heart desires. Just to give an idea of tooling :)