paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-04 05:53:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Add initial project ideas page for GSoD.

Browse Source
This commit is contained in:
Tim Abbott
2019-04-19 14:42:23 -07:00
parent 6e1a67015f
commit edd7a1ab53
1 changed files with 344 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

344
docs/contributing/gsod-ideas.md Normal file
View File

@@ -0,0 +1,344 @@
```eval_rst
:orphan:
```
# Google Season of Docs
## About us
[Zulip](https://zulipchat.com) is a powerful, open source team chat
application. The core web app is written in Python and uses the Django
framework. We also make a cross-platform mobile app, an Android app, 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](../), 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
generally have 10-15 GSoC students each summer, depending on how many
high-quality applications we receive. 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.html) for details on
getting involved.
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 and we had 10 (+3) students in 2018.
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
[Our guide for having a great summer with Zulip](../contributing/summer-with-zulip.html)
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.
We also recommend reviewing
[the official GSoD guide](https://developers.google.com/season-of-docs/docs/tech-writer-guide).
Finally, keep your eye on
[the GSoD timeline](https://developers.google.com/season-of-docs/docs/timeline). The
student application deadline is June 28, 2019.
## 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](..//subsystems/documentation.html)
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
[#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) on
[the Zulip development community server](../contributing/chat-zulip-org.html)
(use your name as the topic).
We highly encourage you to take notes on anything you noticed or were
confused by while gaining familiarity with the project provide that as
feedback to the community, either via starting threads in the
chat.zulip.org community or opening a pull request (if you are
reasonably confident what the solution is).
If you're looking for a next place to contribute, doing the same
process with some of our other documentation is a great way to help
while gaining familiarity with Zulip.
## 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
you 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 as well as some thoughtful feedback or discussions
on how we can improve the system.
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:
* Details on any experience you have related to the technologies that
Zulip has, or related to our product approach.
* Links to materials to help us evaluate your level of experience and
how you work, such as personal projects of yours, including any
existing open source or open culture contributions you've made,
technical writing you've done or edited (blog posts, public
documentation, etc.) and/or any bug reports you've submitted to open
source projects.
* 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 mentors
to remind themselves of your contributions. Threads in
chat.zulip.org talking about Zulip's documentation are considered
valuable contributions worth mentioning here.
We expect applicants to be fluent in (technical) English writing. For
some projects, experience with the technologies relevant to their
project is a plus, but not essential as long as we're confident you
can learn (and there are many places where lack of experience makes
one better able to understand the perspective of a new user trying to
understand the documentation). 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).
While only one contribution is required to be considered for the
program, we find that the strongest applicants make multiple
contributions throughout the application process, including after the
application deadline.
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.html), and otherwise
being good members of the community.
## Mentors
We have several Zulip contributors who are interested in mentoring
projects. We usually decide which contributors are mentoring which
projects based in part on who is a good fit for the needs of each
student as well as technical expertise. You can reach us via
[#GSoC](https://chat.zulip.org/#narrow/stream/14-GSoC) on
[the Zulip development community server](../contributing/chat-zulip-org.html),
(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 a response to requests for feedback
quickly.
However, the first and most important thing to do for building a
strong application is to show your skills by contributing to a large
open source project like Zulip, to show that you can work effectively
in a large project (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. Just make sure you don't make the same mistakes next time).
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 developing 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 need to do research on the
Zulip codebase, read issues on GitHub, 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.html) 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 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](../tutorials/documenting-api-endpoints.html) for
writing API documentation built by a student last summer based on the
OpenAPI standard with built-in automated tests, but there are a dozens
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 goals 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.
* 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 built a nice markdown-based system for the steps sections
having a heading section showing different clients that provides a
nice way to adjust these pages; this project would be to take
advantage of that system to create .
**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 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 topics, like the topic model and catching 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.