714044 - (tbkbd-docnew-tracker) [Meta] Explore ways of improving Documentation for Thunderbird Keyboard Shortcuts (general correctness, completeness, usability, functionality / reorder, restructure the list / add alternative sorting etc.)

Status: RESOLVED WORKSFORME

(Thunderbird :: Help Documentation, defect)

Description

[Thomas D. (:thomas8)]

+++ This bug was initially created as a clone of Bug #714041 +++

Current documentation:

Keyboard Shortcuts list (1) in its current version (2) at the time of posting this bug is not very user-friendly; it leaves a lot to be desired in terms of correctness/accuracy, completeness, structure, and functionality (you name it). To begin with, the first major section of that list, "Message Functions" is apparently not sorted in any transparent way, apart from some loose relations between individual entries.

"Message functions" section (and probably other sections, too) is currently (2):
- not sorted by command captions
- nor sorted by command sequence in TB's menus
- nor sorted by shortcut key's
- nor sorted by assumed importance/frequency of usage
- nor sorted by meta grouping of related functions
where "not sorted" means "not fully/recognizably/transparently sorted".

The UX of this document is scary.
I don't have time for the details right now, but we need to explore ways of improving the documentation. I've made a small start in (3), but this needs a lot more love and care.

Expected documentation (draft):

1) Check each and every entry if it still applies, and remove/fix/improve outdated/wrong/misleading entries
2) Chose sorting criteria for the current list; make it known in the document and resort/regroup entries accordingly
3) Create missing entries, duplicate entries where necessary (depending on topical sorting criteria of 2)
4) Implement feature to allow sorting of the list by various criteria like those mentioned above, e.g. 
- by command caption (alphabetical)
- by menu sequence (loosely, strictly with captions etc.)
- by "meta" functionality/topic-related
- by keyboard-shortcuts
- by importance/frequency
- or combinations thereof
This probably requires a tabular/database-driven internal/external structure.

This bug is intended to be a starting point for ideas, I'd expect full proposals and implementation to go into dependent bugs.

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
(2) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5138
(3) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5396

Comment 1

[Thomas D. (:thomas8)]

(In reply to Jim Porter (:squib) from Bug 713979 Comment 5)
> I think what we really want to do to fix the issues in comment 1 is to write
> a tool that extracts the keyboard shortcuts from our code automatically.
> Then we don't have to rely on fallible humans to keep up-to-date. I was
> thinking about doing this, in part to figure out what shortcuts we have
> available, but I've been too busy.

Of course that's a valid approach. Not so straighforward, though, because we probably want more than just an alphabetical list of all commands. I suspect it will be a lot of work, if at all possible, to realize the goals of comment 1 in a fully automated way. Semi-automated with added value by fallible, yet intelligent humans might be best. This bug is here as a starting point to discuss our options.

Comment 2

[Thomas D. (:thomas8)]

Please note when adding dependent bugs:

We also have another, similar tracking bug where dependants can be added:
Bug 714031 - [Meta] [SuMoMo] Thunderbird Keyboard Shortcuts *Documentation* Tracker Bug

Bug 714031 is a catch-all bug for tracking anything that relates to TB keyboard shortcuts documentation, including all the everyday issues like updates, corrections etc.

This bug (bug 714044) focuses on more general/lasting ways of structurally/functionally/automatically improving then main Documentation page of Thunderbird Keyboard Shortcuts (see URL).

Intersections of dependent bugs are possible, I'd expect that any dependants of this bug might be a subset of dependants of bug 714031, but not vice versa: we don't want all the small details (dependants of bug 714031) here unless they are structural in nature. The difference might be fuzzy sometimes, but imo it's worth trying. Otherwise, it's a starting point for evolution. We need to start somehow, somewhere. :)

Otherwise, bug 713979 is a catch-all tracker for any bugs about the *implementation* of keyboard shortcuts in the TB product:
Bug 713979 - [Meta] Thunderbird Keyboard Shortcuts Tracker Bug

Comment 3

[Ludovic Hirlimann [:Usul]]

http://support.mozillamessaging.com/en-US/search?q=keyboard shows two kb articles - shouldn't they be merged ?

Comment 4

[Thomas D. (:thomas8)]

(In reply to Ludovic Hirlimann [:Usul] from comment #3)
> http://support.mozillamessaging.com/en-US/search?q=keyboard shows two kb
> articles - shouldn't they be merged ?

Ludo, you're a star! Thanks for pointing this out... the respective documents are:
a) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
b) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts-searching

And yes, this definitely needs action...:

First Aid
- Fix wrong information on b) where we still have complete nonsense like Ctrl+Shift+F for Quick Filter!?
- At least, both documents should have LINKS to each other???

Long Term
- Consider merging of a) and b). Actually, my first thought on a) was "why on earth don't we bundle up all the search shortcuts in their own section?
- Find out how wrong shortcut can survive on b) while I had already posted an explicit correction of a) and the TB8 release notes. I suppose there should be someone responsible for ensuring the quality of such information, and it should be the same person for both documents?

Comment 5

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #4)
> b) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts-searching
> First Aid
> - Fix wrong information on b) where we still have complete nonsense like
> Ctrl+Shift+F for Quick Filter!?
> - At least, both documents should have LINKS to each other???

I've fixed b), review pending:
- correction of new quick filter bar shortcut (Ctrl+Shift+K)
- reorder current list of search shortcuts (TB8+)
- add link to keyboard shortcuts page

Comment 6

[Thomas D. (:thomas8)]

Who is responsible for keeping main "Keyboard Shortcuts" documentation (1) up to date? That article is a book of fairy tales, really. An estimated 30% of keyboard shortcut entries are just plain wrong, outdated, misleading in the then-current version which I found (2) ... I've made first basic corrections (3), but I keep finding more nonsense every time I look at this (for details, see dependent bugs). Worse, this is the master document from which all other languages will derive their translations, so we are spreading wrong information about Thunderbird shortcuts. We really need a mechanism to ensure the quality of that document. Something like a litmus test, where before each new release, somebody checks *all* the shortcuts if they still apply. Ideas?

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
(2) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5138
(3) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5396

Comment 7

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #6)
> but I keep finding more nonsense every time I look at this
> (for details, see dependent bugs).

Fwiw, for the details you need to look at dependent bugs of bug 714031 alias tbkbd-doc-tracker.

Comment 8

[Thomas D. (:thomas8)]

(In reply to Thomas D. from comment #6)
> Who is responsible for keeping main "Keyboard Shortcuts" documentation (1)
> up to date? That article (2) is a book of fairy tales, really.

Not only is it a book of fairy tales, but also a lot of stories are missing... :(
Bug 716254 lists as many as 28(!) keyboard shortcuts currently missing from the documentation, looking at current revision at the time of this post (3).

(1) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts
(2) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5138
(3) https://support.mozillamessaging.com/en-US/kb/keyboard-shortcuts/revision/5396

Comment 9

[Blake Winton (:bwinton) (:☕️)]

(In reply to Thomas D. from comment #6)
> Who is responsible for keeping main "Keyboard Shortcuts" documentation (1)
> up to date? That article is a book of fairy tales, really.

I believe, according to the laws of Bugzilla, that you are now.  ;)

Later,
Blake.

Comment 10

[Ludovic Hirlimann [:Usul]]

I'm going to +1 blake on this one. Thomas how do you feel about updating the documentation (it's wiki based) ?

Comment 11

[Thomas D. (:thomas8)]

(In reply to Blake Winton [On vacation until Jan 9th] (:bwinton - Thunderbird UX) from comment #9)
> (In reply to Thomas D. from comment #6)
> > Who is responsible for keeping main "Keyboard Shortcuts" documentation (1)
> > up to date? That article is a book of fairy tales, really.
> I believe, according to the laws of Bugzilla, that you are now.  ;)
> Later, Blake.

Ooops... *trying-to-dodge-the-boomerang* ;)
Look how Blake spends his holidays (claiming to be "on vacation until Jan 9th"... but still busy recruiting volunteers to do the work!)... ;)

Well, volunteers come and go... I was thinking that documents as crucial as "Keyboard Shortcuts" would deserve a paid member of Mozilla to keep an eye on them...

Of course, there is an easy solution here:
Just make me a paid member of Mozilla! :) (Which I'll gladly accept, seriously... and you'd benefit from years of commitment and experience in Thunderbird, BMO and SUMOMO)

Comment 12

[Matt]

Bugzilla is not used for the creation or modification of user facing support documents. As this bug appear to be entirey about the keyboard shortcut document I suggest continuing any discussion if the article discussion forum on Support.mozilla.org

https://support.mozilla.org/en-US/kb/keyboard-shortcuts/discuss