Publishing docs in two places is no fun

[verythorough]

A Little History

The docs for Netlify CMS started in this repo, as a README plus a few files in /docs. Then we created the netlify-cms-www repo to build netlifycms.org, copying over the /docs files into a Hugo setup, adding some marketing content as well.

This meant that the docs were now stored in two places, and of course, that was no good (see #266). @bdougie solved this by adding Markdown Magic to netlify-cms-www (#20). This meant docs could be stored in netlify-cms and pulled automatically into netlify-cms-www.

The Problem

It's been great to have docs stored in just one place, but storing in one place and building in two has caused some significant hassles:

• Adding new docs or changing filenames requires changes in two repos. Within-file changes are updated automatically, but file-level changes require an update to the Markdown Magic configuration in netlify-cms-www. This is also a hassle for any images added or changed in the docs.

• Previewing docs edits in the built site requires a lot of hoop-jumping. To test locally, you have to copy and paste the doc content into a local copy of the netlify-cms-www repo and build that. To see a deploy preview, you have to make a branch on netlify-cms-www with settings changed in the doc file to pull from the PR branch on netlify-cms (including a new user in the path if it's coming from a fork). If your edit involves file-level changes, you need to create two branches on netlify-cms-www—one for merging to master (pulling from master on netlicy-cms) and another for previewing (pulling from the PR branch on netlify-cms)

• Content is interpreted differently in the two locations. For example, inline links to files within GitHub require the .md extension, but these same links in the built site will 404, because they're html files with prettified URLs (Fix link to extending.md #471 (comment)). I just discovered this dual-publishing setup also causes problems for Hugo shortcode delimiters in code blocks (Update to Extending doc breaks docs site build #749).

A Proposed Solution

I think it's time to take docs out of the code repo, and store them in netlify-cms-www. This is actually common for large projects, including, for example, React.

Making the change would be fairly straightforward:

• Copy docs file contents into the bodies of their counterparts on netlify-cms-www, and remove them from netlify-cms.
• Remove the Markdown magic configuration from netlify-cms-www.
• Update contributor guides in both locations to reflect the new (simpler!) workflow.

Any objections? Anything I'm missing?

[Benaiah]

The only issues I have with this are the following:

• determining the docs for a specific version of the CMS will have to be done manually, instead of being tracked in Git alongside the code
• contributors are less likely to keep docs up to date with the code when they're in separate repos
• it's more difficult to add documentation for different PRs in preparation for merge and merge them both simultaneously

Basically, I'm worried about further drift between the code and the docs, which is already a common issue with our current docs.

The issues we have with markdown-magic don't seem insurmountable - we could have the CI in netlify-cms do a build of netlify-cms-www and report errors in PR threads, and it seems straightforward to get the list of filenames automatically instead of hardcoding them using globs in markdown-magic. The link issue still exists, but markdown-magic has built-in support for transforms.

OTOH that's a fair amount of dev time itself, so it may be simpler to do as you suggest and just separate them.

[verythorough]

I feel like making sure docs get updated in sync with code is a people problem more than it is a code problem. Just like requiring tests or linting for PRs to get approved, we can similarly require docs updates. Auto-versioning in-repo is handy, but only works if people actually update the docs to match. For that purpose, I think I'd rather employ version branching in a separate docs repo, similar to what Kubernetes does.

I think there's definitely room for eventually adding functionality that pulls some of the documentation directly from the code (in comments, for example), and Markdown Magic and other existing tools are great for that. Doing it at a file level, though, feels like more trouble than it's worth, especially with limited dev bandwidth.

As the project scales, I think it would be nice to have the docs in a separate repo, and I have found many examples of OSS projects that do this. On the other hand, there are also a few really big projects (like Rails) that have tons of docs, guides, and tutorials stored right in the code repo. And we could go that route, removing the netlify-cms-www repo and moving all of its code & assets into netlify-cms. Kinda feels so monolithic that way, though. 😉

[erquhart]

I'm leaning toward porting the docs out, primarily due to the nature of this project - it isn't a library for developers, it's an application for end users, which is implemented by developers. We could hybridize with implementation/extension docs in the source and user docs outside, but that's a lot for right now.

Giving this a shot is worthwhile - if we realize that any of the potential pain points become real issues in practice, we can always reassess.

[verythorough]

Makes sense to me. I've been thinking about some implementation details, and will work on a PRs for the port this week.

[Benaiah]

Sounds good to me - it's definitely the easiest short-term fix to the broken doc links issue.

[verythorough]

Actually, as @imorente pointed out in netlify/netlify-cms-www#45 (comment), a one-line _redirects file is probably the easiest fix for the link issue!

On the other hand, I'm really looking forward to easier docs previews. 😅

[erquhart]

Update: docs are staying in the repo - @verythorough is working on the transition 🎉

And yeah, redirects, why didn't we do that a long time ago 🙄