Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#30780 closed Cleanup/optimization (fixed)

Make "Getting Help" documentation much more prominent.

Reported by: Shai Berger Owned by: Gabriel Augendre
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Abdul Aziz Tetteh Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: yes

Description (last modified by Mariusz Felisiak)

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. Fixed in PR969.
  1. 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
  1. (moved to 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 issue templates.

Change History (16)

comment:1 by Mariusz Felisiak, 5 years ago

Summary: Make "Getting Help" documentation much more prominentMake "Getting Help" documentation much more prominent.
Triage Stage: UnreviewedAccepted

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 code.djangoproject.com (see e.g. Better UX for website newticket page).

comment:2 by Shai Berger, 5 years ago

Description: modified (diff)

I believe you meant djangoproject.com so I opened 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".

comment:3 by Abdul Aziz Tetteh, 5 years ago

Cc: Abdul Aziz Tetteh added
Owner: changed from nobody to Abdul Aziz Tetteh
Status: newassigned

comment:4 by Abdul Aziz Tetteh, 5 years ago

Owner: Abdul Aziz Tetteh removed

comment:5 by Abdul Aziz Tetteh, 5 years ago

Status: assignednew

comment:6 by Abdul Aziz Tetteh, 5 years ago

Owner: set to nobody
Status: newassigned

comment:7 by njkaz, 5 years ago

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

comment:8 by Gabriel Augendre, 5 years ago

Owner: changed from nobody to Gabriel Augendre

I'm willing to work on this :)

comment:9 by Gabriel Augendre, 5 years ago

Has patch: set
Last edited 5 years ago by Gabriel Augendre (previous) (diff)

comment:10 by Mariusz Felisiak, 5 years ago

Patch needs improvement: set

comment:11 by Mariusz Felisiak, 5 years ago

Description: modified (diff)

comment:12 by Mariusz Felisiak, 5 years ago

Patch needs improvement: unset
Triage Stage: AcceptedReady for checkin

comment:13 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In c07b4bce:

Refs #30780 -- Moved "First steps" section to the top of index page.

comment:14 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

Resolution: fixed
Status: assignedclosed

In 307c63f9:

Fixed #30780 -- Improved visibility of Getting Help FAQ in tutorials.

comment:15 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In 00b436a:

[3.0.x] Refs #30780 -- Moved "First steps" section to the top of index page.

Backport of c07b4bce2c1d05308144aec86422d4cd2b45d818 from master

comment:16 by Mariusz Felisiak <felisiak.mariusz@…>, 5 years ago

In 8e432718:

[3.0.x] Fixed #30780 -- Improved visibility of Getting Help FAQ in tutorials.

Backport of 307c63f9a7c90a21368d8361cd76f48f372413ab from master

Note: See TracTickets for help on using tickets.
Back to Top