zulip/docs/contributing/gsod-ideas.md

```eval_rst
:orphan:
```

# Google Season of Docs

## About us

[Zulip](https://zulipchat.com) 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][oss-release] in late 2015, with
code contributions from [over 500 people](https://zulipchat.com/team)
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.

[oss-release]: https://blogs.dropbox.com/tech/2015/09/open-sourcing-zulip-a-dropbox-hack-week-project/

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](../index.html#welcome-to-the-zulip-documentation), 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](../overview/contributing.md) 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](https://developers.google.com/season-of-docs/docs/tech-writer-guide),
and keeping your eye on
[the GSoD timeline](https://developers.google.com/season-of-docs/docs/timeline). The
application deadline is June 28, 2019.

[Our guide for having a great summer with Zulip](../contributing/summer-with-zulip.md)
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](../overview/contributing.html#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](../documentation/overview.md)
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](../overview/contributing.html#your-first-codebase-contribution)
to get your Zulip development environment set up. If you have any
trouble, please speak up in
[#documentation](https://chat.zulip.org/#narrow/stream/19-documentation) on
[the Zulip development community server](../contributing/chat-zulip-org.md)
(use your name as the topic).

## Application tips, and how to be a strong candidate

You'll be following
[GSoD's application process instructions][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.

[instructions]: https://developers.google.com/season-of-docs/docs/tech-writer-application-hints

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](../contributing/chat-zulip-org.md), 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](https://chat.zulip.org/#narrow/stream/19-documentation) on
[the Zulip development community server](../contributing/chat-zulip-org.md),
(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](../git/overview.md) 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](https://zulipchat.com/api).  Zulip has a
[nice framework](../documentation/api.md) 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][api-docs-area] for good starter projects and
[this issue](https://github.com/zulip/zulip/issues/10044) 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.

[api-docs-area]: https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22area%3A+documentation+%28api+and+integrations%29%22

**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](https://blog.zulip.org).  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](https://stackshare.io/company/zulip/decisions)
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](https://blog.zulip.org/2016/10/13/static-types-in-python-oh-mypy/),
  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](https://web.mit.edu/tabbott/www/ksplice-blog.html) 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](https://zulipchat.com/help/) for how Zulip
works and how to accomplish useful tasks.  An example article is how
to [star a message](https://zulipchat.com/help/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](https://zulipchat.com/help/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 zulipchat.com).  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.