How to contribute to OutSystems Documentation
The OutSystems community is the reason we keep developing an amazing platform. We want you to be successful, so with that in mind, we want to give back even more.
We’ve decided to make our product documentation available to all of the community, letting you contribute and collaborate with us.
Have you found inaccurate information? Have you seen a how-to that needs to be updated? Now you can easily make these corrections yourself in GitHub.
Help us make our documentation even more useful for everyone!
All edits, contributions, and corrections are made through GitHub – one of the most collaborative platforms for software projects.
Don't have a GitHub account? Sign up here.
Our documentation is available in the following GitHub repositories:
In these repositories, you can make the following types of contributions:
- Propose a change. You can propose changes to address inconsistencies or to improve/update existing content.
- Propose new content. You can propose new knowledge content, such as how-tos or best practices, that might help other members of the community.
All contributions are done in GitHub using Markdown – a simple, lightweight markup language with plain-text formatting syntax. To see how easy it is to master Markdown, check out this guide.
Do you have questions, ideas or feedback? Drop us a message via [email protected]
Anytime you stumble upon something that you feel could be better, here’s how you can propose a change:
-
Click the Edit button.
The corresponding page opens in the GitHub repository.
-
On the GitHub page, click the edit icon.
-
A text editor opens. Make your changes in it.
-
When you have finished your changes, scroll down in the editor, add a comment about your change and click Propose file change.
-
To submit your changes for approval, click Create pull request.
And that's it! Your proposed changes are processed by our team and, if approved, made part of the documentation.
Creating new content for our knowledge ecosystem is invaluable to us. It means that you are both knowledgeable and care about our community.
If you have any question about how or where to propose new content, drop us a line at [email protected]
Depending on the type of content that you create, choose from these TK Templates:
You can propose new content to our community by doing the following:
-
In the GitHub repository to which you want to contribute, select the folder you want to add your new document to.
-
Click Create new file.
-
Give a name to your file in the format
[filename].md.
-
Copy the content of a template to a new file and add your content to it. To preview the content, click Preview.
-
After you have added all the content, scroll down, add a description, and click Propose new file.
-
To submit your new content for approval, click Create pull request.
And that's it! Your proposed changes are processed by our team and, if approved, made part of the documentation.
If you plan on contributing frequently, we advise a more bulletproof setup. This takes a bit more time to put in place, but in the end, it makes it easier for you to contribute in the future.
The main steps in setting up your environment are:
- Set up Visual Studio Code
- Fork the repositories
- Clone your forks to your computer
Note: This article details the process of how to install and set up the required tools to contribute. Other tools can be used, however, these are the ones we recommend.
Follow the steps below to get your Visual Studio Code environment up and running.
Needed tools
The tools you will need to set up Visual Studio Code are:
- Git, for source control purposes.
- Visual Studio Code, to edit the markdown files.
- Visual Studio Code extensions, to aid you while editing.
Installing Git
- Download the latest (stable) version from https://git-scm.com/download/
- Run the installer and follow the installation steps.
Installing Visual Studio Code
Visual Studio Code is available for Windows, Linux, and Mac.
- Download the latest (stable) release of Visual Studio Code from https://code.visualstudio.com/
- Run the binary and follow the installation steps.
Visual Studio Code extensions
We recommend the following extensions:
- SpellChecker - v1.2.13 [Michael Vernier]
- Markdown Shortcuts - v0.12.0 [mdickin]
- Relative Path - v1.4.0 [jakob101]
- Github Markdown Preview - v0.0.2 [Matt Bierner]
- Git Graph - v1.18.0 [mhutchie]
Installing an extension
- Open the View menu and select Extensions. Alternatively, use the keyboard shortcut
Ctrl+Shift+X. - Search for the extension and install it.
Note: Make sure you are installing the correct extension and respective versions. Newer versions may also work.
To fork our repositories to your account, repeat the following steps for each repository:
- In GitHub.com select one of our repositories.
- Click the Fork icon.
- Select your account in the pop-up.
- A copy of the repository is created within your account.
Now that you have a fork of the repositories and Visual Studio Code set up, you can clone your fork. To do this:
- Open the Command Palette using the keyboard shortcut
Ctrl+Shift+P. - Enter clone.
- Select the Git: Clone option.
- Paste the URL of your fork, and press
ENTER. - Select a folder on your computer to save the repository files.
- Wait until the repository is cloned (If you haven't already logged into GitHub, you may need to do so at this point.)
- After the cloning completes, a notification appears. Click Open.
For more information about cloning a Git repository in Visual Studio Code, see Cloning a repository.
Now that you are set up and ready to contribute, we recommend the following:
- Sync with your GitHub repository copy
- Create branches for bigger contributions
- Submit a Pull Request (from your fork to the main repository)
We recommend you regularly sync your changes with GitHub. This ensures that you are working with the latest version of the master repository.
To sync your changes with GitHub, click the refresh icon on the bottom toolbar of Visual Studio Code.
If you are creating a lot of content, we recommend creating a new branch. One of the main reasons for this is to keep working materials separate from the existing ones, which, if needed, makes it easier to discard them completely.
- From the Command Palette (
Ctrl+Shift+P), select Git: Create Branch. - After you have completed your work in the branch, merge it with the master of your fork.
After you have completed your work and committed it to GitHub, you must submit a pull request.
- From the GitHub.com web interface, navigate to the master repository. (The one from where you created your fork.)
- Click New Pull Request.
- On the Compare page, click compare across forks.
- In the base branch drop-down menu, select the branch of the upstream repository you want to merge the changes into.
- In the head fork drop-down menu, select your fork, and then use the compare branch drop-down menu to select the branch you made your changes in.
- Enter a title and description for your pull request.
- Click Create Pull Request.
Your changes will be reviewed and, if approved, merged into the main repository.
To help you create and edit content, we prepared a style guide. OutSystems staff uses the style guide to review all new content, including your pull requests. We created the style guide as a reference that you can back to when needed.