[Django] #30780: Make "Getting Help" documentation much more prominent
Django
------------------------------------------------+------------------------
Reporter: Shai Berger | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 1 |
------------------------------------------------+------------------------
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].
--
Ticket URL: <https://code.djangoproject.com/ticket/30780>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
--------------------------------------+------------------------------------
Reporter: Shai Berger | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by felixxm):
* stage: Unreviewed => Accepted
Comment:
I agree with points 1.1, 1.2, and 2.2. I'm not sure about 2.1. The 3rd
point should be open as an issue in
[https://github.com/django/code.djangoproject.com/issues
code.djangoproject.com] (see e.g.
[https://github.com/django/code.djangoproject.com/issues/87 Better UX for
website newticket page]).
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:1>
Django
--------------------------------------+------------------------------------
Reporter: Shai Berger | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Old description:
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
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Abdul-
Type: | Aziz-T
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Abdul-Aziz-T):
* cc: Abdul-Aziz-T (added)
* owner: nobody => Abdul-Aziz-T
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:3>
Django
--------------------------------------+------------------------------------
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Abdul Aziz Tetteh):
* owner: Abdul Aziz Tetteh => (none)
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:4>
Django
--------------------------------------+------------------------------------
Reporter: Shai Berger | Owner: (none)
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Abdul Aziz Tetteh):
* status: assigned => new
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:5>
Django
--------------------------------------+------------------------------------
Reporter: Shai Berger | Owner: nobody
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Abdul Aziz Tetteh):
* owner: (none) => nobody
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:6>
Django
--------------------------------------+------------------------------------
Reporter: Shai Berger | Owner: nobody
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Comment (by njkaz):
To be able to build the djangoproject repository locally using docker
compse, some changes to the Dockerfile were needed, just letting you know,
that this PR is still open, but I think it's necessary to be merged to see
the documentation when you build the website from scratch using docker /
docker-compose:
https://github.com/django/djangoproject.com/pull/954
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:7>
Django
-------------------------------------+-------------------------------------
Type: | Augendre
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Gabriel Augendre):
* owner: nobody => Gabriel Augendre
Comment:
I'm willing to work on this :)
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Gabriel Augendre):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 1
Changes (by felixxm):
* needs_better_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 1
Description changed by felixxm:
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. (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].~~
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. ~~
[https://github.com/django/djangoproject.com/pull/969 Fixed in PR969].
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].~~
--
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by felixxm):
* needs_better_patch: 1 => 0
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"307c63f9a7c90a21368d8361cd76f48f372413ab" 307c63f9]:
{{{
#!CommitTicketReference repository=""
revision="307c63f9a7c90a21368d8361cd76f48f372413ab"
Fixed #30780 -- Improved visibility of Getting Help FAQ in tutorials.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"c07b4bce2c1d05308144aec86422d4cd2b45d818" c07b4bce]:
{{{
#!CommitTicketReference repository=""
revision="c07b4bce2c1d05308144aec86422d4cd2b45d818"
Refs #30780 -- Moved "First steps" section to the top of index page.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"00b436adf46a332bf73d49e0a96fdf57f0cb499e" 00b436a]:
{{{
#!CommitTicketReference repository=""
revision="00b436adf46a332bf73d49e0a96fdf57f0cb499e"
[3.0.x] Refs #30780 -- Moved "First steps" section to the top of index
page.
Backport of c07b4bce2c1d05308144aec86422d4cd2b45d818 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: Shai Berger | Owner: Gabriel
Type: | Augendre
Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 1
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"8e432718b80d8dc3bbcf727dcaced67599a3ee53" 8e432718]:
{{{
#!CommitTicketReference repository=""
revision="8e432718b80d8dc3bbcf727dcaced67599a3ee53"
[3.0.x] Fixed #30780 -- Improved visibility of Getting Help FAQ in
tutorials.
Backport of 307c63f9a7c90a21368d8361cd76f48f372413ab from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30780#comment:16>