This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Django
- Technical writer:
- Gabbyprecious
- Project name:
- Rewrite Contribution guide to be more user-friendly and easily navigated
- Project length:
- Standard length (3 months)
Project description
ABSTRACT
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 year's 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, which I myself belong to in getting started to contribute to this great framework.
Current State
The current stage of the documentation which can be found here, is not really much of a guide as it is too overwhelming and not well structured and leads to less understanding of contribution in Django and not welcoming to new contributors.
Project Goals
I discussed my suggestions for the documentation with my mentor, Carlton Gibson in the forum and he approves that it will help with the overwhelming issue with the current documentation. Here are the goals I plan on achieving restructuring the document: Restructure the document Add sectional Dos and Don’ts Create single pages for trivial sections like Requesting and making features Reduced and straight to point documentation Glossary for words Internal Index built to follow the new guide 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.
The current documentation is already targeted at advanced contributors, and doesn’t give chance to new and beginners contributors both to open source and Django, here are some additional contents for beginners: Section that guides different set of contributors(technical writers, designers and developers) A page that documents first timer issues and easy issues that can be solved. Take a few sections in current documentation, rewrite and add to the beginners section. Sections that explain key points or words used in the advanced section.
Timeline
Here will be a breakdown on how I want to work on the project goal as listed above with the calendar provided by Google.
Community bonding week( August 17 - September 13) Get to engage more with the community Continue contributing to the documentation Getting more suggestions from Contributors More study of current Documentation and intended tools Week 1 - week 4 Start out on sectioning documentation based on Levels Create the beginners section of documentation Week 4 - 6 Curating Dos and Don’ts Writing out sectional Dos and Don’ts Additional pages for sections Week 7 - 9 Rewrite and move current documentation to Advanced Contributor guide Reduced Documentation Week 10 - 12 Prepare Glossary Update Internal Index to new documentation Create a guide and style for incoming technical writers/contributors
Tools
Sphinx - current tool for current documentation. Read the Docs.
Why this Project?
I’m a core believer in well written documentations and articles to encompass everyone in part of the world. Aside from that, I’m also a lover of Django and Open source as a whole. I have been meaning to contribute to Django as a beginner and I think this is a perfect way to contribute to my favourite tool, while also getting acquainted with the codebase to offer more contribution as a developer(and a technical writer). It will be pleasant and beautiful to work with an organisation that aligns with my views and has been a great tool to my whole career.
Why am I the right person for this project?
I believe I’m the right person based on the following accounts: I have been contributing to Django by writing articles to help beginners understand the concept of Django more. Being a developer and one looking forward to contributing to Django, I understand the need of fellow developers and how to document it well for them. I’m a team player and will work well under less or more supervision of my mentor Carlton Gibson.