Thunderbird:Draft How To Edit SUMO KB Articles for Thunderbird One Pager

From MozillaWiki
Jump to navigation Jump to search

Intro to SUMO for new staff and volunteers

  • support.mozilla.org is the official first party support site for all Mozilla free products (all the Firefox products, and Thunderbird for Android and Thunderbird Desktop)
  • Its nickname is "SUMO" because we have to have acronyms for everything :-)
  • SUMO has many parts: Knowledge Base (KB) articles (user documentation), Product User Support Forums (also known as: "AAQ" for Ask a Question, "Community Forums" and "Questions"), Forums for contributors and staff for non product support discussion
  • SUMO is multilingual. The KB is in many languages. The Forums are in in English, Dutch, Italian, Turkish, Brazilian Portuguese, Spanish and a few other languages. The full list is in this KB article: Community Forums locale availability
  • The KB for Thunderbird Desktop and Thunderbird for Android are much like the KBs for other software products. There are many in-product links from TB Desktop and Android.
  • To write articles and respond to forum questions, you will have to create a SUMO account which means you will have to create a Mozilla Account (formerly known as Firefox accounts).
  • Every time you edit an article, a new revision is created. Each revision is numbered. For example the latest revision of New in Thunderbird Desktop as of this writing is revision 303575. You can see the revisions by clicking Show History on the right sidebar when you are logged into SUMO.

SUMO Markup (wikimedia style) versus Markdown

Common markup with markdown equivalents

  • external links: 
    [https://example.com this is a link to example.com] Markdown (MD): [this is a link to example.com](https://example.com)
  • internal i.e. to other SUMO articles links: 
    [[Thunderbird and Exchange|link to Thunderbird and Exchange] ] MD: no equivalent
  • headings: 
    ==This is a second level heading== MD: ##This is a second level heading
  • bold text: 
    '''bold text''' MD: **bold text**
  • images 
    [[Image:Image Title]] MD: ![alt text](Isolated.png "Title")
  • bullet list:
    * bullet point MD: * bullet point
  • numbered list:
    #numbered bullet point MD: 1. numbered bullet point

SUMO Markup extensions

  • button: 
    {button click this button}
  • button: 
    {menu click this menu item}

Figuring out what to write is the hardest part

  • For Mobile and Desktop the beta release notes are good and Google Doc: Monthly Release - Overview
  • Equally good is marketing's draft blog post for mobile and desktop but beware that marketing's emphasis is often not user issues and workarounds but what's new and improved. Support has to document issues, workarounds AND what is new and improved.

Narrate your work in a github issue

Workflow: As you write, backup your writing to a text file because browser based writing systems are fragile

  • Any time you add a sentence or paragraph, copy and paste the markup to a text editor like vim, vi, emacs, code, textedit, you can use Google Docs but it's not really designed for markup editing, whatever works for you, I use logseq but I am silly that way :-)
  • Suggested workflow but you can do anything you want: Write in a text editor, copy/paste into SUMO so if the browser crashes (or if you click on any link by accident which has happened to me 100s of times in the 10 years i have used SUMO) you won't lose your work

Get your revisions reviewed

  • @ mention Roland or Wayne in Matrix room: #tb-support-crew to get your revision reviewed or (less preferred) email #tb-support-crew topic box mailing list or email Roland directly roland AT thunderbird.net
  • if it's Linux ask Danny Colin or Heather Ellsworth to review
  • please ask for reviews publicly in #tb-support-crew (as well as email if you want) unless it's confidential
  • Staff: do not self approve until you have written at least 2 new articles and edited at least 10 articles.
  • Volunteers: For MZLA products only---> Once you have written at least 5 new articles and edited at least 10 articles, I am 100% on board with giving you the power to self approve assuming that's ok with Kiki and Konstantina (it might not be for good reasons, I'll follow up with K and K). For MoCo products, you likely won't be able to self approve and that's OK

SUMO is a wiki so your writing will be revised by others, be egoless :-)

  • Here is an exampled of markh2 (thanks Mark!), a veteran volunteer, correcting my markup: https://support.mozilla.org/en-US/kb/new-thunderbird-desktop/compare?locale=en-US&to=303575&from=303319 . I believe that 99% of Mark's edits in revision 303575 could have been detected and corrected by a markup Linter (without machine learning! but machine learning would make it even better) but somebody needs to write one for SUMO :-)
  • I know you are a native English speaker but non native English speakers often know English grammar better than you do :-). And they will correct you as they should :-)
  • In markdown, a blank line after a heading is needed. SUMO markup like wikimedia markup doesn't require a blank line. Volunteers will remove those blank lines. You have been warned :-)
  • Same for headings. No spaces before or after a heading tag i.e. '==heading 2==' instead of '== heading 2 =='
  • Volunteers and staff will also correct any violations of the SUMO Style guide (Writing guide for Knowledge Base articles) as they should. Also OK :-) !

Demo

Steps:

Unreviewed revisions edge case: If there are any unreviewed revisions, it's best to ask Roland or Wayne or any experienced KB reviewer. Generally you don't want to inadvertently overwrite others' legitimate revisions. This is a judgment call :-) that takes experience.

  • 2. We will add the following text to the Thunderbird 142 section and backup to our text editor just in case:
==Switch to the old Account Setup flow to fix issues when adding Hotmail accounts==
If you cannot add a ''''Hotmail''' or outlook.com account here's how to switch to the old Account Setup flow to fix the problem:
Click Thunderbird app menu {menu ☰} > {menu Settings} > Untick '''Create accounts in the new Account Hub''':

Next steps and what to read next

(please don't hesitate to ask questions, #tb-support-crew preferred but DMs ok)

Retrieved from "https://wiki.mozilla.org/index.php?title=Thunderbird:Draft_How_To_Edit_SUMO_KB_Articles_for_Thunderbird_One_Pager&oldid=1255649"