Early Drafts for git/markdown writers


Hi folks!

We use git, github, and write our platform doc in markdown.

I’ve noticed that for early drafts of new and lengthy content, markdown & gitHub makes it hard for people to see the content–but we like GitHub’s tools for commenting & collaboration, and the content is going to end up in markdown controlled by git…

So, not asking for advice, but asking what YOUR actual current practices are around getting reviews & sharing the comments for newer, longer pieces of content. For example, if this was a brand new file for your team:
https://developer.okta.com/docs/api/getting_started/api_test_client.html (it’s not new, just an example)




And of course, what you love or hate about your current process.


I usually use pandoc to convert the MD to HTML and send that out for review.


We also convert our MD to html (with couscous). And then there’s the question about missing the inline commenting possibilities (specially if people are used to it, coming from Confluence), and how to actually review.

How do you perform the review in html case?


GitHub provides great commenting–but people have to have an account and have to be comfortable reading “code.” We also sometimes create PDFs and distribute them, or cut and paste HTML into email or google docs for content that needs non-GitHub-member review.


Yep, we use our local network Git, but some people have been complaining that it’s not very comfortable - probably because they don’t see the actual html look, if they’re not generating it by themselves. As they are devs, they don’t want to put too much energy into looking into docs, anyway. Thus I was wondering if there is some other magic pill somewhere, but still the Git is most probably the best option so far :slight_smile:

Edit: Just realized that my question doubles this: Doc commenting in HTML output?


Having recently moved from Zendesk to Jekyll, I’m still working out some of the kinks in the review process for non-technical folks. I’ve found that after a quick walkthrough of GitHub, most people are pretty comfortable leaving comments/making small changes in the web UI.

To show people what the content will look like once it’s live on the site, I use a Netlify webhook to generate a deploy preview of the site, which is accessible at the bottom of every pull request. I typically add a comment on the PR that includes a direct link to the page on the deploy preview site that needs review with instructions on what I’m looking for.

Whenever commits are added to a PR, Netlify will trigger an update and re-deploy the preview. It’s super handy for going back and forth and thus far has worked well - reviewers can view the Markdown content in-line on GitHub alongside the rendered version and add comments as they go.

It’s not as efficient as I’d like it to be, but it does okay for now.


Cool, Erin! So you have a separate site for each branch? We have a lot of activity, so wondering about PR clashes or if a different site for each PR is built. Thanks!


The preview Netlify builds is specific to the PR, so yep, a different site for each branch/PR. :slight_smile:


thank you so much!!! I think we’re going to do something similar. Yay!