#30780: Make "Getting Help" documentation much more prominent.
--------------------------------------+------------------------------------
Reporter: Shai Berger | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
--------------------------------------+------------------------------------
Old description:
> Issues like https://github.com/django/djangoproject.com/issues/947 show
> up very often, I think they are more common than actual website issues.
> Each and every time we close such an issue with "go get help in proper
> channels", it's a little failure -- for the submitter, of course, but
> also for us. I think we can try harder to make the correct channels more
> prominent. Here's a list of potential action items:
>
> 1. The whole "Getting Help" section on the documentation front page sits
> only in the side bar, below obviously-less-interesting stuff like the
> navigation tools. It is easy to miss it entirely.
> 1. We could make it one of the first sections in the list -- I
> suspect that the first three sections should be "First steps", "Getting
> help", and only then "How the documentation is organized".
> 2. I'd also consider making a link to .../faq/help/ float on the
> documentation page, like the language and version selectors do now.
>
> 2. The tutorial mentions "where to get help" in an admonition very close
> to its beginning, but then it is never repeated, and it is easily
> forgotten by the time anyone actually needs it.
> 1. Make the admonition link to the faq, and mention the links to get
> help which are present on every documentation page
> 2. Repeat the admonition, at least once on every tutorial page
>
> 3. The ticket-creation form for the Django code -- the one I'm filling in
> now -- has a list of things for a (first-time) submitter to consider,
> under the heading "Please read this first"; I believe this list greatly
> reduces the amount of support-tickets filed on this tracker. A similar
> thing can be done for the djangoproject.com repo using
> [https://help.github.com/en/articles/manually-creating-a-single-issue-
> template-for-your-repository issue templates].
New description:
Issues like https://github.com/django/djangoproject.com/issues/947 show up
very often, I think they are more common than actual website issues. Each
and every time we close such an issue with "go get help in proper
channels", it's a little failure -- for the submitter, of course, but also
for us. I think we can try harder to make the correct channels more
prominent. Here's a list of potential action items:
1. The whole "Getting Help" section on the documentation front page sits
only in the side bar, below obviously-less-interesting stuff like the
navigation tools. It is easy to miss it entirely.
1. We could make it one of the first sections in the list -- I suspect
that the first three sections should be "First steps", "Getting help", and
only then "How the documentation is organized".
2. I'd also consider making a link to .../faq/help/ float on the
documentation page, like the language and version selectors do now.
2. The tutorial mentions "where to get help" in an admonition very close
to its beginning, but then it is never repeated, and it is easily
forgotten by the time anyone actually needs it.
1. Make the admonition link to the faq, and mention the links to get
help which are present on every documentation page
2. Repeat the admonition, at least once on every tutorial page
3. (moved to [https://github.com/django/djangoproject.com/issues/948
relevant repo]) ~~The ticket-creation form for the Django code -- the one
I'm filling in now -- has a list of things for a (first-time) submitter to
consider, under the heading "Please read this first"; I believe this list
greatly reduces the amount of support-tickets filed on this tracker. A
similar thing can be done for the djangoproject.com repo using
[https://help.github.com/en/articles/manually-creating-a-single-issue-
template-for-your-repository issue templates].~~
--
Comment (by Shai Berger):
I believe you meant [https://github.com/django/djangoproject.com/issues
djangoproject.com] so I opened
[https://github.com/django/djangoproject.com/issues/948 an issue] there.
The idea behind 2.1 is to make the admonition more memorable by providing
a non-disruptive action that can be taken immediately without really
cutting the workflow. This would work especially well with 1.2's floater:
"Hey, just glance at the bottom-left corner, there's a link there you
should be aware of, and then continue reading".
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:2>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/063.dea4b9fbf57395e5aaa1664743b3cbae%40djangoproject.com.
