Update Infinispan Developer and Configuration Guides - JBoss Community

About JBoss Community

JBoss Community is a community of open source projects. The community hosts a large number of projects that are written in various programming languages. The primary language is Java. But there are also projects that are written in Ruby, PHP, Node and other languages. Project categories range from better testing support over IDEs, application servers, application and performance monitoring, IOT, machine learning to micro-services.

Infinispan (https://infinispan.org/), part of JBoss community, is an in-memory, distributed data store. It’s a fast-paced open source project teamed with energetic, yet laid-back, developers and community contributors. It’s a small team but we get lots done while trying to inspire the best in ourselves and each other.

As a technology offering, Infinispan is used as an application caching layer for high performance and fault-tolerant access to data. Infinispan is also sponsored by Red Hat and used in several large organizations to ensure business continuity. Because Infinispan is quite elastic by nature, it scales easily and is suited for cloud-native applications and efficient resource usage.

About the project

Problem

The Infinispan documentation set has recently expanded to include user stories for our Kubernetes Operator while also adopting a more task-oriented, topic-based approach to content development. 

There is still a hefty backlog of content to organize, restructure, and edit into more discrete topics and assembled into end-to-end procedural user stories. We also still have a good bit of documentation effort required to apply terminology consistency guidelines and do more mundane things like making sure anchors and IDs conform to standards that we’ve established.

We’re looking for a technical writer who is tech-savvy and likes to roll up his/her sleeves and dig into projects. This is a good opportunity for a junior writer to gain experience with an open-source project and build a portfolio. Writers with more experience might find opportunities for learning modern technology usage patterns, improving continuous delivery pipelines for documentation, and contributing to overall content strategy.

Scope

As part of this initiative, the Infinispan team want to do the following things with our Developer Guide and Configuration Guide:

Analyse community discussions and support forums, like our Zulip channel and Stack Overflow, to identify improvements to the content. 

Perform general documentation maintenance tasks to ensure that asciidoc files adhere to naming conventions, anchors and IDs are standardized, terminology and style is consistent with project guidelines.

Create validation mechanisms for code and configuration examples.

Rewrite several monolithic chapters as topic-based procedural user stories.

Improve graphics by converting to SVG format where necessary and applying a common Infinispan look and feel.

Provide feedback on the overall experience of contributing towards Infinispan documentation and identifying any bottlenecks or challenges that can be improved to foster more community involvement.

Measuring project success

By the end of this engagement, topic IDs in the Infinispan documentation set will be 100% in compliance with our standard format.

We will also calculate how many reference topics there are in the documentation set versus the number of procedures. One of our goals is to have more procedures than reference in our documentation. Reference content is included in xsds, Javadocs, or otherwise generated from source code. We feel that good documentation is task-oriented so a measure of success is to increase the ratio of task to reference.

Additionally we will engage our community with this documentation effort through our site blog and Twitter account. We plan to announce this effort to our community by openly discussing plans for improvement, highlighting improvements as we make them, and issuing calls to action to solicit feedback and community responses.

Our community has provided us with feedback about both our Developer and Configuration Guide recently, stating that there is too much complexity in some areas of the documentation and it is often difficult to understand. A key measure for success is to lower the incident rate of recurring comments and questions from our community in those specific areas.

We hope to increase the number of community driven PRs to our documentation and will record and measure them over time.

Project budget

Additional information

We have 2 potential mentors for this project. One of the mentors is a senior technical writer at Red Hat. The other mentor is an engineer who works with technical writers daily.

JBoss Community has been part of Google Summer of Code consecutively for 9 years. JBoss Community has also participated in Google Code-in in 2018. We have built a strong community and GSoC played an important role in that. Google Season of Docs admins in our community are the Google Summer of Code admins and they have experience in running these kinds of programs in JBoss Community.