Gsod 2020 suggestions and dicussion

Hello, I’m Precious Ndubueze, a Django user and lover of Django. I’m a student at the University of Uyo here in Nigeria, I’m an Applicant for GSOD 2020. I’m an open-sourcer, a technical writer and developer although a beginner to the world of open-source and would be delighted getting to work on one of my favourite tools. I have gone through the contributing guide, and I came up with some few suggestions and I’m happy to get feedback and more suggestions to prepare my proposal Idea.
@carltongibson I had forwarded my suggestions to your email before I found my way here. Here is a copy of my document

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 belong to in getting started to contribute to this great framework.

I have written a few suggestions and goals I’ll work on to get started, I have towards making this goal attainable. Some suggestions aren’t mentioned here and I’ll be happy to get suggestions from you. Here are my suggestions:

Levelled Pages

A page should be created to guide different kinds of Contributors. This is not to replace internals but to segment the first section of the contributing guide as it can be overwhelming for beginners and redundant for advanced contributors and other segments.

Beginners sections will have collected arranged sections of the internals suited for beginners. Also an introduction to basics and a little guide of the codebase. Explanations of some keywords not familiar. Also, different ways to contribute, currently here should be the top section of the beginners’ sections.

Contributing FAQs and Top Sections

There should side sections of the top questions and sections of high interest to contributors.

Sectional Dos and Don’ts

Dos and Don’ts should not be scattered on each section but located at the end so not to discourage new contributors(with a note at the start not to skip the section)

Single Page

A lot of documentation such as Requesting and making features also documenting them (unlike here) should stand-alone pages.

Additional Suggestions

Most pages such as Triaging tickets section and more are too overwhelmed making important details lost in between(suggesting reduced documentation going straight to the point)

The writing code segment should be included in top sections and ending the beginners’ level and how to contribute to sections and also the underneath sections should be explained a little bit before leading somewhere else.

The mailing list section should be added at the beginning of the contribution guide(beginners side).

More internal links to sections in the documentation or beyond to enable straight to the point and still easy understanding.

Internal Index

The Internal Index should be edited to follow the new guide created and be easy to navigate.

@carltongibson please help look into this, for more clarification, here’s the link to the document. Thank you very much.

2 Likes

Hi. @gabbyprecious. Thanks for your post.

These kind of ideas seem in the right direction to me. Breaking up by levels makes sense. That feeling of overwhelm is what we’d like to change.

Kind regards
Carlton.

Hi @carltongibson thank you, do you have any suggestions so I can add to the project proposal I’m drafting.

Also I’ll be sharing this with the community and get more suggestions from them

Can I send a draft of the proposal to you before the application time to get feedback before applying?

It sounds like you have the idea. So then it’s your thoughts as the TW as to how we can do better. We’ll help you with any technical questions.

Happy to look at your ideas. :slightly_smiling_face:

Good day @carltongibson, I’ll like to know tools used for the current documentation and link to it where it’s been hosted for me to be all to contribute and get accustomed to.

Hi @gabbyprecious.

The out the Writing Documentation guide. It should get you started. :crossed_fingers:

We use Sphinx.

Let me know if you have any difficulties.

Carlton.

Good day @carltongibson I’m done on the proposal and would like your view and input before submitting it in the application form. Here’s a link. I really will appreciate your input. Thank you very much for your help so far

Super! Let me take a look later on. :slightly_smiling_face:

1 Like

Hi @gabbyprecious — Looks good. I like the article of yours you linked to. Any other pieces you’ve got would be good to add too, even if they’re not necessarily Django, just to show your style and voice.

I’d re-jiggle slightly: I don’t think so much time is needed for the advanced level — that’s kind of what’s there in a way… — More then for really building out the beginner level stuff: someone who knows Django but wants to now contribute. If you can flesh out a couple of the bullet-points related to that, to bring out more of the vision you have, that would be good.

Looking forward to your submission!

Kind Regards,

Carlton

Hello @carltongibson, thanks so much for your correction. What I meant, by the advanced section, was restructuring the document into mainly two sections, pushing the beginners forward and edit and move back the current documentation to advanced section.
I have added my article to the document, my other articles are currently been worked on and can’t be published for now(hope that’s okay with you).
I will be submitting my application later today, and you could have another look before then. Thanks a lot for your help and contribution.

1 Like

Hi @gabbyprecious. I’m sure it’s great. Do submit!