Skip to content

Instantly share code, notes, and snippets.

@gabbyprecious
Last active April 30, 2024 11:06
Show Gist options
  • Save gabbyprecious/962b2bf0af6314b58e5864a0125f3923 to your computer and use it in GitHub Desktop.
Save gabbyprecious/962b2bf0af6314b58e5864a0125f3923 to your computer and use it in GitHub Desktop.
GSOD Project Report: Rewrite Django Contributing guide

GSOD Project Report: Rewrite Django Contributing guide

The goal of Django’s contribution guide like every other documentation is to guide user, open-source contributors in this case on how and where they can contribute to making Django better and sustainable.

There’s always a need to make documentations especially one that greatly affects the community and Django itself.

The goal of Django for this 2020 Google Summer of Docs is to make the Contribution guide less overwhelming, accessible, and welcoming to contributors. This is a goal which is essential as it encourages contributors, getting started to contribute to this great framework.

Project Goals

  • Restructure the document
  • Write a more relatable friendly documentation
  • Segmenting the contents into two main parts (Beginners and Advanced Contributors section)
  • Construct a guide and style for new technical writers/contributors, to keep the docs up to date and follow standards.

Community Bonding

During this stage, my mentor and I decided on the right channels for communication, and feedback. I also interacted with the django-developer community and got information, challenges and ideas they had towards the contribution guide. My mentor and I also had a call with other core Django contributors and came up with ideas for the new contribution gide.

Work Done during Documentation Development Stage

  • Reviewed existing contributing guide.
  • Identified core contribution areas.
  • Mapped existing content on to ideal structure
  • Implemented changes on guide:
Task Progress PR Link Published
index page Done django/django#13981 Yes
new contributors and contribution page Done django/django#13967 Yes

Last phase involved:

PR #13967 — Improved the sign posting around the guide to ensure contributors are channeled to the appropriate content for them. PR #13981 — Restructured the guide introductory material to be clearer, advertise the identified contribution pathways, and give equal representation to valued non-code related aspects of contributing. (In so doing we were able to place code-related material where it belongs, in the code-related contribution sections, rather than on the introductory page.) Both of these are published on the latest Django 3.2 docs (or will be as soon as the second PR is merged.)

In addition we made various stylistic changes to make the guide more friendly and engaging as we went.

Highlights

  • Met awesome people in the Django community
  • Learnt about working collaboratively on a big project, with many stakeholders, like Django.
  • Got mentored by Carlton Gibson and Mikey Ariel
  • Got more involved and better understanding with Django codebase
  • Contributed to Django!

Remaining work.

Predictably, there were lots of ideas for smaller content changes that came up but which we didn't yet have the time to implement fully. These can be fulfilled as incremental changes as we go. The fundamental restructuring is complete.

@carltongibson
Copy link

Changes are published as soon as merged.

@carltongibson
Copy link

Hey Gabby.

Extra consideration: you learnt about working collaboratively on a big project, with many stakeholders, like Django.

Work done involves speccing the requirements too — the work here wan't just the PRs.

Established needs:

New contributors have repeatedly cited the overwhelming nature of the Contributing Guide when looking to get started.

  • Reviewed existing contributing guide.
  • Identified core contribution areas.
  • Mapped existing content on to ideal structure
  • Implemented changes on guide.

Last phase involved:

  • PR #13967 — Improved the sign posting around the guide to ensure contributors are channeled to the appropriate content for them.
  • PR #13981 — Restructured the guide introductory material to be clearer, advertise the identified contribution pathways, and give equal representation to valued non-code related aspects of contributing. (In so doing we were able to place code-related material where it belongs, in the code-related contribution sections, rather than on the introductory page.)

Both of these are published on the latest Django 3.2 docs (or will be as soon as the second PR is merged.)

  • In addition we made various stylistic changes to make the guide more friendly and engaging as we went.

Remaining work.

Predictably, there were lots of ideas for smaller content changes that came up but which we didn't yet have the time to implement fully. These can be fulfilled as incremental changes as we go. The fundamental restructuring is complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment