Skip to content

Conversation

S-Haime
Copy link
Member

@S-Haime S-Haime commented Aug 19, 2025

Relates to #506 and #2347

This is the first round of updating help texts and descriptions. Includes:

  • Simple punctuation and typo changes (adding periods, capitalisation, minor typos).
  • Clarified help texts and descriptions. Currently focused on interfaces accessed through the manager interface + things I ran into as I went (where making a note would take me longer than just addressing it). Primarily aimed to help users understand fields.
  • Added/updated descriptions in the HTML of some of the pages.
  • Made checkboxes easier to use, based on user feedback and Freshdesk experience (and occasionally, when documenting, being confused myself). Users sometimes struggle with the 'So ticking the box does....?' issue, so I have tried to make this explicit.
  • Added a few hyperlinks to helptext, going to see how this looks / if I may wish to repeat it elsewhere.
  • Added clarifications to email setting descriptions. This aims to make it easier to understand what is in the email template / who it is sent to, without needing to open the email template itself.

Feedback point:

  • Currently, following the Google Styleguide, we use bold to refer to UI elements. I started doing this in the help text. I'd like to hear your thoughts on it.
  • Please check everything is correct around sharing and open peer review. It's not the part of JW with which I am the most familiar.
  • Is it clear(er)? Does it make sense?
  • I have largely avoided touching the workflow element texts, as I wanted to check if I am going in the right direction with this, so any issues would be good to know about.

Notes:

  • I am aware there are many, many more descriptions and help texts, and other elements to address. I'll have to get to them eventually.
  • There are a few pages where shifting things around may make it easier to use; I can return to that when we do the back office redesign. There are also settings I didn't completely understand. I'm tabling these for later.
  • This will introduce more temporary inconsistency around capitalisation. I can try and have a go at this in the near future, but will need to check if none of it would affect underlying structures/forms etc. It may also be worth overriding the default Django behaviour of how it forms the display names for settings.
  • There is a repeating line around translation: "Before translations become available you must create the object in the base language (English)." that may need editing at some point. (I ran it past a range of people and none felt confident they knew what it meant/what to do with that information. Though a good number did guess correctly, so it's not the most urgent.)
  • The top of the Licence manager page could do with a 1-2 line description, but I wasn't 100% confident I wouldn't break the page.

Final note:
My apologies if some of it is nitpicking! But I wanted to grab as many of those small bits as I could, whilst I was doing this work. Both to save someone else having to do it and to make Janeway as nice as I can :D (My intentions were pure, even if my lines changed are many.)

S-Haime added 25 commits August 18, 2025 10:07
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
@S-Haime S-Haime requested a review from mauromsl August 19, 2025 15:16
@S-Haime S-Haime added the documentation Ideas for new or improved user documentation label Aug 19, 2025
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
@ajrbyers
Copy link
Member

ajrbyers commented Aug 21, 2025

Note: This will require a management command to update all the setting descriptions. Should this be run at update?

@S-Haime S-Haime assigned S-Haime and unassigned mauromsl Aug 21, 2025
@S-Haime S-Haime marked this pull request as draft August 21, 2025 08:58
@S-Haime S-Haime removed the request for review from mauromsl August 21, 2025 08:58
S-Haime and others added 24 commits August 21, 2025 15:31
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
Signed-off-by: Siobhan <148049561+S-Haime@users.noreply.github.com>
@S-Haime S-Haime marked this pull request as ready for review October 3, 2025 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Ideas for new or improved user documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants