ankur512512 / mulesoft-docs

Main MuleSoft documentation repository

MuleSoft Documentation Repository

This is the repository for MuleSoft’s documentation and contains the source content for the docs site.

Community Contributions

MuleSoft welcomes contributions from the community! You can contribute or provide feedback for our documentation in the following ways:

• Fork this repository, make edits, and submit a pull request. We respond to your request as quickly as possible.

• File an issue. Be as specific as possible about the changes you’d like to see.

• While viewing a page on our docs site, you can rate a specific topic and include comments for fixes, suggestions, or general feedback.

• Send mail to the docs team: [email protected]

• See the MuleSoft Docs Style Guide for writing tips.

Accepting the Contributor’s Agreement

Before you can contribute to our documentation, you need to complete two steps to acknowledge that you’ve read and accepted our Contributor’s Agreement:

1. Review the agreement, which is available here.

2. After you’ve read and agree to the agreement, you need to fill out the MuleSoft Contributor’s Agreement form and submit it to us. This form exists as an API notebook and does two things:

   • Identifies you using your GitHub account, and

   • Records your name as a contributor

After you’ve submitted the form, you are asked to authenticate to GitHub and accept our Contributor’s Agreement. When the script completes, an Issue is created in our contributor’s project with your name.

That’s it! You’re now able to make contributions to our documentation. Ready to get started?

Making a Contribution

After you accept our Contributor’s Agreement, you can simply fork our documentation repository and make changes, then submit a pull request.

Alternatively, you can click the Edit on GitHub link at the top of a page, click the pencil icon, and make your change.

The pull request is reviewed by our team as soon as possible.

Building the Site for Local Preview

This repository includes a Gradle build script that you can use to build the documentation site for local preview. The script automates all aspects of the build. All you need on your machine to execute the build is a Java Development Kit (aka java and javac).

Begin by cloning the documentation repository:

$ git clone [email protected]:mulesoft/mulesoft-docs.git

Note: If you’re not interested in the entire history, and you want to reduce the size of the clone, add the --depth flag to execute a shallow clone:

$ git clone --depth 1 [email protected]:mulesoft/mulesoft-docs.git

Next, switch to the directory into which you cloned the repository:

$ cd mulesoft-docs

Finally, use the gradlew command to launch Gradle and execute the site builder:

$ ./gradlew

Running gradlew with no arguments executes the default task, which is named build. It’s equivalent to the following:

$ ./gradlew build

(The build task may take several minutes to complete).

Once you’ve built the site, you can once again use Gradle to serve the site using a local, in-memory web server:

$ ./gradlew serve

You can now access the site from your browser at the location http://localhost:8000.

Note: Currently, not all links work in the local preview since the preview server doesn’t implement the rewrite rules used in production. If you encounter a 404 when clicking on a link in the site navigation, try adding ".html" to the URL in the location bar.

When you want to stop the preview server, simply press Ctrl+c.

To run a full build and launch the preview server in one shot, combine the build and serve tasks:

$ ./gradlew build serve

Building a Page for Local Preview

This repository includes a Gradle build script that you can use to build a documentation page for local preview.

./gradlew buildHtmlSingle -Pfile=<asciidoc-filepath>

Building the Site for Staging

The Gradle build script is also capable of building the site for staging and syncing the output to the staging server. The extra tasks and configuration needed for these operations are added when the profile property has the value staging. You can set this property by passing the flag -Pprofile=staging to the gradlew launch command.

To instruct Gradle to clean, build, and publish the staging site, execute the following command:

$ ./gradlew clean publish -Pprofile=staging

Note: The staging site combines the assets from the staging branch of mule-docs-site-assets with the content from the master branch of mule-docs.

Building the Site for Production

The Gradle build script is also capable of building the site for production and publishing it to git. The extra tasks and configuration needed for these operations are added when the profile property has the value prod. You can set this property by passing the flag -Pprofile=prod to the gradlew launch command.

To instruct Gradle to clean, build, and publish the production site, execute the following command:

$ ./gradlew clean publish -Pprofile=prod

Notes:

• The first time you execute this command, it may run for a very long time (depending on connection speed) since it must clone the publish (aka build output) repository anew.

• To prevent the publish task from pushing the new commit to the remote repository, pass the flag -PdryRun to the gradlew launch command.

MuleSoft Docs Style Guide

The following sections describe the MuleSoft Docs publishing style.

Content

Style	Correct Example	Incorrect Example
Use active text instead of "will", "you’ll", "won’t", or "we’ll".	This feature initializes and merges your code.	This feature will initialize and merge your code.
Obfuscate login credentials in illustrations and code	The client secret is 4242424242424242-ABADDOG	My password is foobar123
Only use RFC-1918 IP addresses, for example, IPv4 addresses: 10.0.0.0 - 10.255.255.255 (10/8 prefix) 172.16.0.0 - 172.31.255.255 (172.16/12 prefix) 192.168.0.0 - 192.168.255.255 (192.168/16 prefix)	Set the server address to 10.1.1.42	For example, set the address to 42.42.42.42.
Use the example.com domain	For example, [email protected]	[email protected]
Omit "please"	Contact MuleSoft Customer Support.	Please contact MuleSoft Customer Support.
Separate options with > and don’t cast the string in bold	File > New > Mule Project	File → New → Mule Project
Replace "in order to" with "to"	To start the procedure,	In order to start the procedure
Omit "then"	Click this and that	Click this, and then click that
Refer to variables in inline text as string literals	replayID	"replayID", replayID
Omit button ellipses	Click Test Connections.	Click Test Connections…​.
Omit "on" with click	Click Test Connections.	Click on Test Connections.
Init-cap words in headings	Default Value Setting	Default value setting
Spell out i.e. and e.g.	Create a connector, for example, for Salesforce	Create a connector, e.g. for Salesforce
Don’t put code examples in a screenshot	Put code in a source block	screenshot
Put a period outside a quote string	Don’t say "will".	Don’t say "will."
Use the Oxford comma	a, b, and c	a, b and c
Omit the trademark symbol	Anypoint Platform	Anypoint™ Platform™

AsciiDoc Conventions

• Only start tables with [%header%autowidth.spread] — this sets the table and column widths automatically.

• Start and end tables with |=== — adding extra equal signs only makes more complex source and adds unnecessary characters to files.

• Don’t use the [tabs] notation. Provide separate sections for To Configure Using the Visual Editor and To Configure Using the XML Editor or Standalone.

• Omit linenums option on 1-line code examples.

• Put multi-word examples in a source block instead of a long tick marked string.

• Only XML or XML procedures can be in an XML tab. It’s illogical to put a screenshot in the XML tab.

• Restrict tables to 2 or 3 columns - multi-column tables can be very difficult to read.

• Wrap code example lines at spaces, or for Java after a dot. Code lines should be less than 60 characters, especially if you use the // <n> notation for callouts

• Don’t reference code examples by line numbers. Instead, use // <n> in the code example and reference the notation in the text below the code example.

• Lists in the AsciiDoc source that use a bullet glyph (U+2022) as the marker are recognized as lists.

Lists

Rule	Description	Example
Imperative before lists	Before starting a list, provide a starting sentence that starts with "to" that describes the task you want people to provide. Also, don’t start a bullet or numbered list after a heading without a starting sentence.	To set the values:
Insert a period at the end of a sentence or bullet list item	Perform these tasks.	Perform these tasks
Start each item in a bullet list or numbered list with a capital letter	Start list items that are not reserved words with an init cap	* Ensure all required fields are set.
Start number list items with an action	Number list items only start with an action such as Click, Set, etc.	1. Click the plus sign to the right of Connector Configuration.

Font Changes

Don’t use font changes except for Note:. If referencing a field, initial capitalize each letter of each word regardless of how shown in the UI. For example, instead of using Connector Configuration, use Connector Configuration.

Headings

• Sections describing procedural content must start with To, such as To Configure the Connector.

• Sections describing concepts must start with About, such as About the Connector.

• No special characters in headings.

• Init-cap each word in a heading.

• Don’t put a colon at the end of a heading.

• Ensure headings are in order, h1 > h2 > h3 > h4. Don’t skip levels such as h2 > h5.

• Only one H1 per doc at the top of the file.

• Don’t number headings.

Word Choices

• JSON not Json

• POJO not pojo or Pojo

• MOJO not mojo or Mojo

• ID not id or Id

• Java not JAVA

• Anypoint Studio not Mule Studio

Don’t spell out common acronyms such as POJO, JSON, MOJO, REST, SOAP, MQ, UI, IT, IP, TCP/IP