Hacker News Reader

Comment by packetlost | Hacker News Reader

> But it certainly is not something you'd want for writing the documentation for an enterprise-grade product.

I guess that depends. If you're making a print manual, yeah probably not. IME markdown gets painful as soon as you start doing a bunch of tables.

Most enterprise web applications would probably be completely fine with just markdown-based docs.

View on HN

I think a good example is all of the wonderful documentation that's been created with mdBook.

Heck, the Rust book was written with it, and they also made a print edition, so maybe markdown is enough even for that.

https://github.com/rust-lang/mdBook

Carol put in a tremendous amount of work to build tooling to go between Markdown and Docx. The publishers used the docx versions for print.

That doesn’t mean that I think Markdown is inadequate or the wrong decision, but it’s not just a “write in Markdown and you’re good” sort of situation.

Ah, good to know! Is that tooling public anywhere, or was it pretty tailor-made just for the Rust book?

Both public and tailor-made: https://github.com/rust-lang/book/tree/main/tools

I can find here the process of converting docx to md, but not the reverse. I see the material is checked into the repo in both formats. Does that mean the docx's are your master, and you generate the markdown from it for diffing and building HTML?

I'm investigating how to switch an organisation away from a docx-only mess of a documentation system, and it looks like you might have found a process that'd work for us, and let people keep using docx if they have to.

I wonder what all those binary blobs do to the git repo though.

Thanks for any info!

You'd have to ask Carol, with the way we split the work, she handled all of this.

From my perspective, the markdown was the master copy.

Sorry I can't be of more help!

Awesome! You and Carol rock!

Thanks! She gets 100% of the credit in this case though :)

The link below (https://github.com/rust-lang/book/tree/main/tools) could imply the book was written as Word .docx with named styles, which enabled transformation into markdown for the mdBook?

Reply on news.ycombinator.com