We would like to introduce a new resource that allows everyone to contribute a solution-based documentation.
Gradle Cookbook is an open-source collection of recipes, guides and examples for the Gradle Build Tool. This is a complementary resource to the Gradle User Manual, which covers core capabilities maintained by the Gradle team.
The Gradle Build Tool ecosystem is huge, including many plugins, integrations, developer tools, and other components. Not all of them can be covered in the Gradle User Manual, which represents core documentation maintained for each Gradle release.
Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there. Even for us, it has been difficult to maintain documentation in such a way, and many pages need to be updated. Kudos to @lkasso for doing that incrementally
So, we decided to build a second resource as an extension to the Gradle User Manual, with the following in mind:
Gradle Cookbook remains an official resource under community.gradle.org.
It is not a second-class citizen, just another structure not tied to the Gradle release cycle
Pages should be focused on offering solutions to end users for particular use cases,
hence the Cookbook
We follow the Wiki-alike collaboration style, with a lower barrier to contribution than gradle/gradle. Over time, some sections can get explicit maintainers/reviewers.
We use Documentation-as-Code, with simple Markdown or Asciidoc files used as a source
Minimizing duplication. We can include documentation from other sources under the Gradle GitHub organization
Open Question
Should the final implementation be on a new GitHub repository?
What content to move over from docs.gradle.org and other resources? We have a draft list.
What new content do users want to see/contribute?
Scope
## Tasks
- [x] Initial Skeleton and Contributor Guidelines - #37 and #43
- [x] Migrate Gradle on CI to the Cookbook
- [ ] https://github.com/gradle/community/issues/88
- [ ] https://github.com/gradle/community/issues/89
- [ ] https://github.com/gradle/community/issues/90
- [x] Port https://github.com/gradle/gradle/pull/28406 to the new location
- [ ] Start the Solutions for Android listing
- [ ] Update docs.gradle.org to use the new resource for the migrated content. Maybe, just redirects in the newer versions and `current`
- [ ] Add PDF generation for the cookbook
- [ ] Announce the new resource
We would like to introduce a new resource that allows everyone to contribute a solution-based documentation.
References
#docs
on the Gradle Community SlackWhy and How?
The Gradle Build Tool ecosystem is huge, including many plugins, integrations, developer tools, and other components. Not all of them can be covered in the Gradle User Manual, which represents core documentation maintained for each Gradle release.
Moreover, being tied to the Gradle release contribution process and the release cycle makes it more difficult to contribute there. Even for us, it has been difficult to maintain documentation in such a way, and many pages need to be updated. Kudos to @lkasso for doing that incrementally
So, we decided to build a second resource as an extension to the Gradle User Manual, with the following in mind:
community.gradle.org
. It is not a second-class citizen, just another structure not tied to the Gradle release cyclegradle/gradle
. Over time, some sections can get explicit maintainers/reviewers.Open Question
Scope