Contributing to ExpressionEngine Documentation

Contributing to the ExpressionEngine Documentation

Good documentation is the foundation of good software and your contributions can help make good documentation great.

If you’re an ExpressionEngine user, then you have something to add. There is always room for more examples, clarifications, corrections, and updates. Jump in and make a pull request or give us a heads up by reporting an issue. Since the docs are all in markdown formatting and updates should be pretty straightforward.

Understanding the Workflow.

Contributing to the docs requires a basic understanding of Git. Here’s an overview of the workflow

1. Fork the GitHub repository: https://github.com/ExpressionEngine/ExpressionEngine-User-Guide . Read more about creating a fork of and working with a public repository here: https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository
2. Create a branch (see Branches below).
3. Update your branch
4. Submit a Pull Request, requesting merging your branch into the 6.dev branch of the ExpressionEngine public repository.

Contributing to the Documentation

All of the source files exist under docs/ and is where you will add new documentation or modify existing documentation. We recommend working from feature branches and making pull requests to the #.dev branch of this repo (See Branches below).

Suggesting a change is easy and there is no way you’ll mess up the public repo.

Start by forking the repository, the new branch you create is the one you’ll do your work in.

Once you have your new branch, confirm you’re actually in it! If you haven’t already, make sure you’ve read though the style guide. Then make your changes inside of your feature branch.

Push your changes to your fork of the repository, and when you’re done, send us a pull request.

We’ll take a look at your pull request, make sure everything looks alright, ask for any needed changes, and then merge it into the main code.

Branches

| Branch | Purpose |
| ------ | ------- |
| #.x | Currently released and published version.
| #.dev | Updates for the next version of ExpressionEngine (current version is the default branch). Does not exist for previous versions. |
** replace `#` with the current version of ExpressionEngine or version you wish to target.

Recommended branch names are namespaced and unique, e.g.:

• feature/my-feature-slug
• bug/bug-description-slug

Building and Reviewing the Docs Locally

While some updates are easy and can just be done in markdown without much review, others require a review of what the updates will actually look like when published to the docs. To review changes, you’ll need to build the docs locally. This requires a little bit of setup but is not overly complicated if you’re already familiar with front-end build tools.

Prerequisites

Building the docs requires Node and npm.

In the root of the repository, install all the dependencies: npm install

Building the Docs

To build the docs: npm run build

To dynamically rebuild on any file changes: npm run watch

Building theme assets

The documentation css and js files are located under theme/assets-src.

To build the theme assets, run npm run buildAssets. You can also dynamically rebuild the assets when a file changes: npm run watchAssets.

As with anything else, if you have any trouble building the docs let us know and we’d be happy to help.

Style Guide

Please read the style guide for samples and convention standards used in the ExpressionEngine user guide.

Reporting Issues

Want to help but a little daunted by the idea of making a pull request? We still want to hear from you. You can report errors in the documentation as issues in the github repo. Just remember, the more detailed the report, the more likely someone will be able to make improvements.

Thanks!

Most importantly, THANK YOU! Thank you for caring about the community and wanting to help. ExpressionEngine is open source and has always been successful because of our community. Let us know if you have any problems with the docs or anything else and we’ll be happy to help.

--

Originally published by Andy McCormick at u.expressionengine.com