Hi @carltongibson , I’m Joel Olawanle, a technical writer, a frontend developer, and an open sourcerer. I have contributed to big projects like the Wikimedia Style’s Guide and many others via GitHub. I have used Django in the past and I believe contributing to Django would really be great for me.
I went through Django’s expectation for this year’s Season of Docs and discovered it’s targeted towards structuring the Contributing Guide.
I went through the Contributing Guide and here are few points:
- Firstly, Considering the structure of the current documentation it may seem a little difficult for intending contributors to navigate from one section to another easily. In the sense that contributors need to return to the Contributing to Django page to be able to navigate to other far apart sections.
For example:
If a contributor is on the Triaging Tickets page and needs to navigate to the Localizing Django page, He/She will have to return to the Contributing to Django page to be able to navigate which is not supposed to be.
To solve that problem:
-
We could have a sidebar which would be fixed containing a list of
all the section or
2. We could introduce another section to contain the
list of all sections or
3. Place a link to the Contributing to Django page on every section. -
Secondly, In every doc we should always avoid repetition as it only tends to make the docs bulky and boring. While going through the docs I discovered that below every there are easy navigation links to either the next section or the previous section which is awesome.
Then when I looked at the side towards the Browse section and still saw a repetition of the next and previous link. I believe having them at the bottom of each section should be enough as many users already know that a page should have a next and previous link below.
We could leave the Browse section to only contain links to the
- Table of Content
- General Index and
- Python Module Index which is necessary.
- Finally, I believe it becomes too boring when contributors or intending contributors visit the Contributing to Django page and every time have to read those boring notes before getting to the sections list.
It’s cool to have ways in which they could contribute but it shouldn’t be the first thing users get to see every time they get to that page.
I think after a little introduction to what Django is (anyone intending to contribute should have a basic understanding of Django) the next thing should be the list of all sections(Table of Content) for contributors to easily navigate to what they want.
The whole area of joining Django Communities like the forum, mailing list, IRC channel and the rest could be
- on another page and then added to the list of sections or
- added to the Advice for new contributors page or
- at the bottom of each section.
All these are some of my opinions to make Django docs clearly structured. Like I said these are few points. I hope to be selected so I could work on the docs and so we could brainstorm on many more ideas to make the docs really cool.