Writing Gradle Guides
This guide walks you through the process of writing a new guide for inclusion at the Gradle Guides site. These guides can take different forms—such as short, step-by-step tutorials or longer, more discussion-oriented pieces—but the process for writing and contributing them is the same.
The first step in creating a new Gradle guide is to submit a proposal to the gradle/guides GitHub repository. This is so that we, the Gradle Guides team, can work with you to determine the most appropriate subject, form and scope for the guide.
To submit your proposal:
Create a new issue at gradle/guides with a title that matches the suggested topic for the new guide. For example, "Publishing to private repositories" or "Creating fat JARs". The title should, in general, be a description of a task that a Gradle user might want to undertake.
Add a basic outline for the proposed guide, i.e. section headings
Engage with the team through this issue to nail down the final form of the guide
You don’t have to specify which form the guide should take in the initial proposal, but if you do, please express your preference as one of the following:
Short, step-by-step introduction (getting-started guide)
In-depth discussion about a single topic (topical guide)
Once the proposal has been accepted, the Gradle Guides team will create a new GitHub repository for your guide. You won’t be able to commit directly to that repository. Instead, you will use the standard fork and pull request workflow described here.
When your guide’s repository is ready, you’ll find a link to it in the issue created by you in the previous step. You should then:
That’s it! You’re now ready to work on the content for your new guide using the infrastructure provided by the project you just cloned.
The project provides everything you need to generate the HTML version of your guide and view the result. Just run the following commands in the guide’s root directory:
$ ./gradlew build (1) $ open build/html5/index.html (2)
|1||Run Gradle (via the Gradle Wrapper) to generate HTML from your guide’s AsciiDoc sources|
|2||Open the generated HTML file in your system’s default browser|
At this point, you should have an HTML page that has a title and some section headings, but nothing else. It’s your job to fill in the gaps! But before you start working on that content, it’s worth having a basic understanding of the project structure.
The structure of a Gradle guide repository is very simple, consisting of just two three components:
A directory called
contentswhich contains an entry point AsciiDoc source file called
A Gradle build script to process it into HTML (which later will publish it to the GitHub Pages site where the guides are hosted)
srcfolder where source code to support the guide is hosted. This source code would normally get build with the guide to ensure that the code snippets used in the guide is up to date.
The file you’ll interact with most as a guide author is
index.adoc, but it’s useful to know what the other files and directories are for as well. The following listing walks through each of the top-level directory entries:
. ├── README.adoc (1) ├── contents/index.adoc (2) ├── contents/images (3) ├── src/ (4) ├── build/ (5) ├── build.gradle (6) ├── gradle/ (7) ├── gradlew (8) └── gradlew.bat (9)
|1||GitHub README with some instructions.|
|2||AsciiDoc source for the guide.|
|3||Supporting images for the guide.|
|4||Supporting source code for the guide. Include these in the guide via the AsciiDoc
|5||Output directory for the build, where generated HTML for the guide can be found|
|6||Project build script, containing tasks for AsciiDoc processing and GitHub Pages publication. Familiarize yourself with the AsciiDoc attributes that the
|7||Gradle Wrapper storage directory|
|8||Gradle Wrapper Unix shell script|
|9||Gradle Wrapper Windows batch file|
Now you’re ready to work on your new guide’s content. You will edit the
contents/index.adoc file. You are welcome to create additional AsciiDoc files in the
contents directory and include them via the AsciiDoc
AsciiDoc is a plain text-based, UTF-8 compliant writing format, so you can use any text editor or IDE to work on
contents/index.adoc. Many of them have support for AsciiDoc syntax highlighting, which makes things easier. Once you’ve decided on an editor, just open the file and get writing!
New to AsciiDoc?
When you want to preview your changes, simply regenerate your guide’s HTML with the following build command:
$ ./gradlew build
(Again, the "dot-slash" syntax is used on Unix. On Windows, just type
gradlew or even
Then open or refresh
build/html5/index.html in your browser. It’s as simple as that.
Writing is usually an iterative process. You write a draft, it gets reviewed, you do a second draft, and so on. That’s why we recommend that you submit your guide for review as soon as you want feedback. To do so, initiate a pull request when you’re ready.
Your guide enters the review process at this point. Each step of a review involves either feedback (as comments) or edits (as commits) depending on the current stage of the process. That’s why it’s important for you to specify what type of review you want. Should the Gradle Guides team treat the current version of your guide as a first draft or something that’s ready to be published? Do you simply want feedback on the structure and overall tone, or do you want the team to check for and fix spelling and grammar issues? You don’t have to be too specific and the team will ask for clarification if necessary.
Whenever you have a new draft ready, push the changes to your fork and add a comment to the pull request saying what type of review you would like. The pull request will update automatically and the review will continue until both sides are happy with the result.
You’ll find your guide on the Gradle Guides site soon after the pull request is accepted and merged. Well done and thank you for the valuable contribution!
This guide documented the process to:
Submit a proposal for a new Gradle guide
Fork and clone the new guide’s repository
Work on the guide’s content according to style guidelines
Initiate a review of your guide
Now that you have some experience with it, we hope that you’re inspired to contribute more guides in the future!