Markdown software recommendation WYSIWYG What You See Is What You Get

[Wen-Wei_Tseng]

As to collaborating on Markdown files, HackMD is another solid choice.

• Rich Markdown syntax with LaTeX math, diagrams, and more.
• GitHub integration for version control.
• Collaborative live notes and comments.
• Generous (IMO) free plan.

[Tamas_Papp]

@helgee

Markdown is a nice and simple format in theory but it is also underspecified

https://commonmark.org/

is meant to address that.

@helgee

Don’t judge people for not knowing the tool du jour even if it is simple.

Generally I agree with this, but given how simple basic Markdown is, if someone is unable/unwilling to learn it at a very basic level then I share @gustaphe’s doubts about whether they should be working on technical docs.

As for the original question: I prefer raw text with some hints for formatting. Eg in Emacs,

There isn’t proper WYSIWYG for Markdown anyway since the final appearance depends on the medium and the rendering style.

[helgee]

I do not know about OP’s situation but in my case we are working on a large study across multiple organisations with 50+ people involved. Out of those only my team of three people uses Julia but we are implementing the engineering models of other teams and need inputs from them for our documentation. All of our documentation is in Markdown (of course) but since we are just a subcontractor, I am in no position to dictate what the deliveries should look like.
While I am certain that all the engineers supporting us would be (mostly) willing and able to learn Markdown, I see no need to demand it because it is not a hill I am willing to die on. We’ve got bigger problems

For people on macOS I also want to recommend Marked 2 which is a Markdown Previewer that supports GitHub’s stylesheet among others and can even be used with custom Markdown processors so one could try to integrate it with Documenter.jl (which I have not done, yet.)

[Tamas_Papp]

@helgee

While I am certain that all the engineers supporting us would be (mostly) willing and able to learn Markdown, I see no need to demand it because it is not a hill I am willing to die on.

I understand, but my point is that if Markdown is used for the docs, then someone writing the docs should know Markdown. I don’t really see a way around this.

It may be possible to “give input” without knowing anything technical. Eg one can just generate a PDF of the docs and have people annotate it (on screen, or a hardcopy). But that task is distinct from writing the docs.

[helgee]

I see, let’s rephrase this slightly so I can agree

The person writing the docs should do that in the format and with tools they are most comfortable with to remove friction from the process. The person editing the docs however needs to be competent in the target format (e.g. Markdown) and should not rely on a crutch (which a WYSIWYG editor for Markdown arguably is).

Is that what you mean @Tamas_Papp and @gustaphe?

[gustaphe]

I think my position is a bit more hardline than that. I don’t see what a wysiwyg editor gives you over plain markdown unless you are basically afraid of text editors. And then you can’t read source so you can’t document it.

[helgee]

@gustaphe

wysiwyg editor gives you over plain markdown

It is the basic trade-off between TUI and GUI: TUI is strictly more powerful but you need to memorise syntax and there is hardly any discoverability. GUI (ideally) shows you at a glance what’s possible but is very hard to get right and often just hides complexity instead of dealing with it.

[JosephPollacco]

@JosephPollacco

TYPORA

Here are some examples how to integrate Typora and Git:

Typora and Github integration

Content Workflow Using Github And Markdown

Hope that helps

[Tamas_Papp]

@helgee

Is that what you mean @Tamas_Papp

This depends on the context. For FOSS or similar, I am still a hardliner like @gustaphe, but in a commercial setting whatever the parties agree on should be OK — it’s their funeral.

Eg if someone wants to edit documentation in MS Word, transcribe it to parchment using a quill, send it by carrier pigeon, and they are willing to pay for the overhead of dealing with this on the other end, then is should be fine.

Personally, I believe the primary reason for investing in learning some tooling is avoiding all kinds of transcription/conversion errors that result from a convoluted process with people using multiple formats.

Git + Markdown is probably the cleanest way of doing this currently, and doing anything else results in multiple rounds of revisions and proofreading is probably a false economy; as it will take up much more time for everyone compared to learning some tools, or result in an inferior outcome. Practically, even coordinating 3–4 people without distributed version control becomes a nightmare, with people rereading sections all over until they get tired of it an no longer notice the errors anymore.