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.
2 Likes
is meant to address that.
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.
2 Likes
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.)
5 Likes
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.
2 Likes
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?
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.
1 Like
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.
Here are some examples how to integrate Typora and Git:
Hope that helps
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.
2 Likes