Migrate documentation to WordPress

🗣 Feature Discussions Needs Research
1

Description

Right now our documentation is on GitBook. We want to change it mainly becasue of two things:

  1. We don’t want to limit collaboration to only those who know how to write markdown and use git.
  2. We want to use Frontity in the front-end to have total control over our documentation and at the same time demonstrate to other Frontity users how it can be done.

For this reasons we are going to migrate our documentation to WordPress and allow any person to login and suggest changes to our documentation using the Gutenberg block editor.

User Stories

As a Frontity non-techincal contributor
I want to collaborate with the documentation
so that I can add value to the community even though I don’t know how to code

Possible solutions

Allow anyone to login

This part is already working thanks to our integration of both the community and our WordPress with a SSO of Auth0.

Allow people to submit reviews

These are the normal WordPress user roles:

  • Subscriber - No edit rights
  • Contributor - Submit them for review posts created by themselves
  • Author - Publish posts created by themselves
  • Editor - Edit and publish posts created by anyone

We need to either modify one of those or add a new user role to allow them to submit reviews for any post, not only those created by themselves.

After that, we need to make sure they can submit reviews. I’m not sure how good is WordPress at this because there are some external plugins as well:

It’d be nice to also have the possibility to share those drafts externally, with something like:

All those plugins are only example, I haven’t done an extensive research.

Adding doc changes to our pull requests

Most of the times we do a PR we need to include changes to our documentation. Right now we are creating a new draft and adding the link to the PR. It works fine for us but has many limitations:

  • The draft cannot be seen publicly for external developers.
  • The draft cannot be created by external developers.
  • Changes are external to git, not included in the PR.

We need to find a way to add, or at least reference those database-based changes in the PRs. These are a couple of ideas:

  1. Export the modified posts:
    • Pull the DB in your local WP installation (maybe using something like https://wordpress.org/plugins/wp-migrate-db/).
    • Modify the relevant posts and save them.
    • Export them using the WP export tool.
    • Commit the XML file in your PR.
  2. Add the WP database to git:
    • Keep the database (or part of it) in sync with the dev branch of our repositories.
    • In your PR, use a npm command to spin up a local WP with that DB (similar to what we are going to do for e2e tests: https://github.com/luisherranz/wordpress-e2e-testing).
    • Modify the relevant posts.
    • Use a npm command to save the database to disk.
    • Commit the database changes.

This has the added benefit that we can solve merge conflicts between different post reviews using git, although I don’t know how good is WordPress itself at that or if it is even supported.

Managing different versions

It’d be nice to be able to maintain documentation for different versions, like 1.0, 2.0 and so on.

But we have to keep in mind that we cannot do it with a dropdown to select the version, like most libraries do, because we don’t have a single version. Each of our packages can be versioned independiently, so our system should accomodate that.

One possible solution would be to add a custom field with the version and a custom field that references to older versions for that post. If that is present, a dropdown appears in that post linking to the old post. Each time we release a new major version we rename the old post, for example from wp-source to wp-source-v1 and we create a new post wp-source with the custom field populated with a reference to wp-source-v1.

Supporting different languages

It’d be nice to allow people to translate our documentation to different languages. There are many ways to do so right now, so I won’t propose anything specific here.

Besides that, Gutenberg will officially support localization in the future, so we may just wait until then.

Gutenberg blocks

We can create blocks for different things that are common in the documentation:

  • Code blocks
  • Codesandbox embeds
  • Warnings
  • Deprecation notices

Feel free to keep adding possible solutions or more things we should take into consideration.