zulip/docs/contributing/gsod-ideas.md

:orphan:

Google Season of Docs

About us

Zulip is a powerful, open source team chat application. Zulip has a web app, a cross-platform mobile app for iOS and Android, a cross-platform desktop app, and over 100 native integrations, all open source.

Zulip has gained a considerable amount of traction since it was released as open source software in late 2015, with code contributions from over 500 people from all around the world. Thousands of people use Zulip every single day, and your work on Zulip will have impact on the daily experiences of a large and rapidly growing number of people.

As an organization, we value high-quality, responsive mentorship and making sure our product quality is extremely high -- you can expect to experience disciplined code reviews by highly experienced engineers. Since Zulip is a team chat product, your GSoD experience with the Zulip project will be highly interactive.

As part of that commitment, Zulip has over 150,000 words of documentation for developers, much of it designed to explain not just how Zulip works, but why Zulip works the way that it does.

Our history with Google Open Source Programs

Zulip has been a GSoC mentoring organization since 2016, and we aim for 10-20 GSoC students each summer. We have some of the highest standards of any GSoC organization; successful applications generally have dozens of commits integrated into Zulip or other open source projects by the time we review their application. See our contributing guide for details on getting involved with GSoC.

Zulip participated in GSoC 2016 and mentored three successful students officially (plus 4 more who did their proposed projects unofficially). We had 14 (+3) students in 2017, 10 (+3) students in 2018, and 17 (+1) in 2019. We've also mentored five Outreachy interns and hundreds of Google Code-In participants (several of who are major contributors to the project today).

Expectations for technical writers

At minimum, you'll need native or near-native written fluency in English, and some public-facing writing you can show us.

We also recommend reviewing the official GSoD guide, and keeping your eye on the GSoD timeline. The application deadline is June 28, 2019.

Our guide for having a great summer with Zulip is focused on what one should know once doing a GSoC project with Zulip; while it is written for the GSoC student audience, it should give you a feel for how we interact with and mentor committed contributors.

What makes a great Zulip contributor also has some helpful information on what we look for during the application process.

Getting started

For many of our project ideas, you'll be working inside a Zulip development environment (because the documentation is implemented as markdown in the main Zulip repository, and can be previewed using tools in the Zulip development environment). See our documentation on documentation systems for details on our various existing documentation systems.

In part due to past work by a technical writer, Zulip has a well-documented and easy to setup development environment for a project of its scope. Use our first-time Zulip developer guide to get your Zulip development environment set up. If you have any trouble, please speak up in #documentation on the Zulip development community server (use your name as the topic).

Application tips, and how to be a strong candidate

You'll be following GSoD's application process instructions. And we'll be asking you to make at least one successful submission of work (e.g. a pull request) before the application deadline, to help us assess your work and ability to collaborate in an asynchronous online community like Zulip.

For GSoC, students who we accept generally have 5 or more pull requests merged or nearly merged (usually including at least a couple that are significant, e.g. having 100+ lines of changes or that shows they have done significant debugging).

For GSoD, we hope to get a similar level of confidence about your abilities during the application process, through some combination of looking at your past work and collaborating with you on small preparatory projects for your summer. For example, for working on our REST API docs, we'd love to see you contribute documentation for at least one endpoint.

Getting started earlier is better, so you have more time to learn about the organization, make contributions, and make a good proposal.

Your application should include the following:

• Links to materials to help us evaluate your level of experience and how you work, including any technical writing you've done or edited (blog posts, public documentation, etc.), existing open source or open culture contributions you've made, and/or any bug reports you've submitted to open source projects.
• Details on any technical experience you have, if any.
• Some notes on what you are hoping to get out of your project.
• A description of the project you'd like to do, and why you're excited about it.
• Some notes on why you're excited about working on Zulip.
• A link to any contribution(s) to Zulip to make it easy for us to remind ourselves of your contributions. Threads in chat.zulip.org talking about Zulip's documentation are considered valuable contributions worth mentioning here.

We expect applicants to have near-native fluency in English writing. For some projects, a technical background is a plus, but not essential as long as we're confident you can learn. General programming and/or sysadmin skills are also a plus: for some projects, work on the underlying tooling could make the technical writing easier to do, and for others, feeling comfortable with testing the instructions can be valuable.

We also expect applicants to be able to edit their work effectively, and communicate clearly about the reasoning behind their ideas (as well as which parts of their work they have concerns about and would appreciate extra attention on).

We are more interested in candidates if we see them submitting good bug reports, helping other people on GitHub and on chat.zulip.org, and otherwise being good members of the community.

Mentors

We have several Zulip community members who are interested in mentoring projects. We usually decide which members are mentoring which projects based in part on who is a good fit for the needs of each writer as well as technical expertise. You can reach us via #documentation on the Zulip development community server, (compose a new stream message with your name as the topic).

Zulip operates under group mentorship. That means you should generally post in public streams on chat.zulip.org, not send private messages, for assistance. Our preferred approach is to just post in an appropriate public stream on chat.zulip.org and someone will help you. Your mentor will of course be paying close attention to these conversations, and you will likely exchange many private messages with them about what to work on next, but we prefer to review work publicly because it lets us ensure you get responses quickly.

However, the first and most important thing to do for building a strong application is to show that you can work effectively in a large project like Zulip (it doesn't matter what part of Zulip, and we're happy to consider work in other open source projects, even if it is years in the past). One skill that's particularly important to us is separating out your changes into individual git commits that are easy to read and understand and can be merged independently. For some projects that may involve complex refactoring of existing documentation, this skill will be very important; for others, it may not be relevant.

The quality of your best work is more important to us than the quantity; so be sure to check your work before submitting it for review, follow our coding guidelines, and make clear which parts of your work you're uncertain about (and don't worry if you make mistakes in your first few contributions! Everyone makes mistakes getting started.).

Once you have several PRs merged (or at least one significant PR merged, or the equivalent of this for projects that don't involve writing markdown code), you can start discussing with the Zulip development community the project you'd like to do, and develop a specific project plan. We recommend discussing what you're thinking in public streams on chat.zulip.org, so it's easy to get quick feedback from whoever is online.

Project ideas

These are the seeds of ideas; you will likely need to play with the product and talk with developers to put together a complete project proposal. It's also fine for you to come up with your own project ideas.

For many of our projects, an important skill to develop is a good command of Git; read our Git Guide in full to learn how to use it well. Of particular importance is mastering using Git rebase so that you can construct commits that are readable, are clearly correct and that explain why they are correct.

Project name: REST API Documentation

Fill in the gaps in Zulip's REST API documentation. Zulip has a nice framework for writing API documentation built by a student last summer based on the OpenAPI standard with built-in automated tests, but there are dozens of endpoints that are missing, several of which are quite important. See the API docs area label for good starter projects and this issue for a relevant TODO list.

Our goal for this system is to have something that is complete, accurate, and has automated tests for ensuring that it remains accurate as we extend the Zulip API over time. We have made some progress on the automated testing goal (e.g. the Python code examples in the documentation are actually run in a test suite), but there's definitely more to do.

Project name: Blog posts on Zulip technologies

There are a lot of interesting details about how Zulip works, how we've solved problems, etc., that could be turned into high-quality blog posts. Our lead developer, Tim Abbott, is efficient at writing draft blog posts with a lot of interesting content (e.g. the dozen or more articles by Tim Abbott on this StackShare page were written in about 1.5 hours total), but we don't currently have the capacity to do the polish work on these post drafts to turn them into something we can publish on our blog. We have in mind two types of posts:

• Major blog posts, similar to our mypy blog post, which aim to be the authoritative article on a topic and might be read by many 10,000s of people. The Zulip team did a lot of the work on the old Ksplice blog years ago, which has many more examples of the types of posts we would like to write.
• Shorter blog posts, more similar in content to one of our StackShare answers, but polished with more context to be something that is reasonable to publish on our blog.

Our goals for the Zulip blog include educating developers about some of the interesting technologies and techniques we use in Zulip, and so our aim is for all of our blog posts to be at a level of polish appropriate for something being read by many thousands of people.

A good candidate for this project would have a portfolio of technical blog posts they've written in the past.

Project name: User documentation for non-web apps

We have a lot of nice user-facing documentation for how Zulip works and how to accomplish useful tasks. An example article is how to star a message. In most cases, our documentation explains how to accomplish a task in the Zulip webapp, but doesn't cover how to do those tasks in Zulip's mobile and beta terminal apps.

We have recently built a nice markdown-based system to make it easy to show information for multiple platforms in a single tabbed widget. An example article using this widget is logging in. This project will likely take advantage of that system to build out documentation for our other apps.

The first step in this project will likely be working closely with the mobile team to name all the screens, icons and widgets.

Project name: Video tutorials on using Zulip

We frequently receive feedback from folks excited about Zulip that they would really appreciate having a few 1-3 minute videos explaining the Zulip model and how to use Zulip efficiently to help train the rest of their organization on the benefits of Zulip. We would hope to link to these videos prominently in the Zulip tutorial experience (both in-app and on the landing pages). The core Zulip team has a pretty good idea of how to explain Zulip, but does not have significant experience creating videos, and we would love to work with someone skilled at doing screencast tutorials of software to create something great here.

The goal for the summer would be to create ~3-4 videos covering a few key areas, like Zulip's topic model and how to catch up on messages efficiently with the keyboard.

If there's time, we could also do some lower-polish screencast versions of talks we gave at the Zulip Summit in 2018 that we'd love to make available to our contributor community (e.g. how to use Git really efficiently).

Circulating proposals

If you're applying to GSoD, we'd like for you to publicly post a few sections of your proposal -- the project summary, list of deliverables, and timeline -- some place public on the Web, a couple weeks before the proposal. That way, the whole developer community -- not just the mentors and administrators -- have a chance to give you feedback and help you improve your proposal.

Where should you publish your draft? We prefer Dropbox Paper or Google Docs (or even just a message in Zulip), since those platforms allow people to look at the text without having to log in or download a particular app, and you can update the draft as you improve your idea. In either case, you should post the draft for feedback in chat.zulip.org.

Rough is fine! The ideal first draft to get feedback from the community on should include primarily (1) links to your contributions to Zulip (or other open source or publicly available work) and (2) a paragraph or two explaining what you plan to work on. Your friends are likely better able to help you improve the sections of your application explaining who you are, and this helps the community focus feedback on the areas you can most improve (e.g. either doing more contributions or adjusting the project plan).

We hope to hear from you! And thanks for being interested in Zulip. We're always happy to help volunteers get started contributing to our open source project, whether or not they go through GSoD.