Versionen vergleichen

Learn about the Mozilla Support (SUMO) Knowledge Base and how it works.

Learn about the Mozilla Support (SUMO) Knowledge Base and how it works. __TOC__ = What is Knowledge Base? = The Knowledge Base is a wiki with superpowers: *'''Special wiki markup''' – Although we use MediaWiki markup (like Wikipedia) for most things, our wiki is designed specifically for Mozilla Support and uses some custom markup (called [[How to use For|<nowiki>{</nowiki>for}]]) so that we can show one set of instructions to Windows users, for example, and another to Mac users. *'''Review system''' – Because we want to be sure that people get correct and up-to-date information, edits to our articles have to be reviewed and approved before they become live. *'''Translations''' – Most of our users speak a language other than English. We have a whole system for translating the English articles in our Knowledge Base into other languages. = Audience & scope of the Knowledge Base = Since [https://support.mozilla.org/products Mozilla products] are used by millions of people at all skill levels, the Knowledge Base should be written for a general audience rather than one very familiar with computer techniques and terminology. We mainly cover features (like tabs, bookmarks and sync) and fixing problems (like crashes or problems loading websites). We don't cover every feature, setting or problem. Instead, we look at what users tell us (in article discussions, support forums, article views) and use our experience and judgment to decide exactly what to cover. = What topics don't we cover in the Knowledge Base? = * Tricks or hacks for modifying a product, such as ''about:config'' advanced preference configuration * Developer and advanced features like the web console {note}'''Note:''' Troubleshooting articles are often an exception to these rules. If a common problem can only be fixed with a “hack”, we'll document that. These rules also don't apply to [/products/firefox-enterprise Firefox for Enterprise] articles, which are written for IT Administrators who want to configure Firefox on their organization's computers.{/note} = Organizing our work = == How do we prioritize what we work on? == '''We mainly work on articles in order of their popularity.''' This generally represents our users' priorities. Currently, the [/contributors/most-visited top 20 articles] account for over half of all views. Making our top article more helpful can potentially help as many people as improving the bottom 100 articles. We keep track of changes that need to be done in [/contributors/need-changes this dashboard]. It's sorted by article rank so that you can easily see what should be worked on first. '''Exceptions:'''<br> Of course, popularity isn't the only priority. These exceptions also need to be taken into account. *'''Breaking issues''' – Occasionally, new issues are reported in our support forum that are best dealt with by updating a Knowledge Base article. *'''Anticipated demand''' – Occasionally we'll update an article in anticipation of a new feature or feature change. The current article may not have a particularly high rank, but we're reasonably sure based on experience and marketing plans that these articles will become popular. *'''Mobile documentation''' – Because Mozilla products for mobile devices such as Firefox for Android and Firefox for iOS have comparatively few users, their articles can't be expected to “compete” with desktop Firefox articles. The articles for these products should be considered in the context of the relative demand for documentation of features and issues related to the individual product. *'''Linked articles''' – These are articles linked from inside products or mozilla.org. == Desktop priority == #'''Windows''' – With about 90% of our users on Windows, this is a no-brainer. For now, we should be making screenshots for Windows (preferably Windows 10) if you can only make one. #'''Mac''' – The current version (macOS 13.0 Ventura as of October 2022) #'''Linux''' – Use Ubuntu for screenshots. '''Mobile''' *'''Android''' – 4.0 + (4.0, 4.1, 4.2, 4.3, etc.). <!-- Needs review and update for current process (Are we still doing this?) '''Localization:'''<br> In order to minimize work for localizers, our aim is to have updates to the top 20 articles done on a six-week basis. How that works is that non-essential updates (updates for new features, minor fixes and improvements) to these articles are done in English but not marked ready for localization right away. Four weeks before a product release, we'll mark the changes to the top 20 articles ready for localization. We'll try to keep these articles stable for the next six weeks. Sometimes, breaking issues or mistakes may require us to change the articles again. Every six weeks or so we'll create a prioritized list ([/forums/l10n-forum/708538 example]) as a guideline for localizers based on our experience with English.--> == Where do we talk about articles? == We generally have two types of conversations about knowledge base articles: *'''Individual articles''' – Each article has its own Discussion forum, accessible under Editing Tools.<br>[[Image:SUMOEditingToolsDiscussion]]<br> Registered users can post feedback about the articles here, and we can discuss what revisions the article needs, the relative merits of revisions and issues related to the article. *'''The Knowledge Base as a whole''' – We discuss ideas and issues with the overall KB strategy, policies and software in the [/forums/knowledge-base-articles/ Knowledge Base discussions] forum. <!--Needs review and update for current process (Are we still doing this?) ==How do we keep articles up to date with the latest version of Mozilla's products?== There are multiple versions of Mozilla's products being built at once. We refer to these as “trains”. Each train moves from one channel (or track to continue the train metaphor) every six weeks. We have Nightly, Aurora, Beta and Release channels. For six weeks, new features and fixes are added to these products while it's on the Nightly channel. Then, that version moves to the Aurora channel for testing. After six weeks on Aurora, it moves to Beta. And finally, after six weeks of testing on Beta, that version becomes the Release version of the product. In order to keep up with changes to products, our documentation writing follows a six week cycle also. [[Image:doc schedule]] ===Doc Cycle Weeks 1 - 4=== *'''Localize Beta''': Once the articles have been finalized (in the previous cycle), there will be four weeks to localize them before release. We'll have marked revisions as ready for localization, so they'll show up on Localization dashboards. **'''Note''': In the two weeks previous to this, we may have also made updates based on feedback from the last release that will also be included in this batch of articles to localize. *'''Draft Aurora''': We'll have four weeks to draft new articles and updates to existing articles. We'll follow the '''[https://wiki.mozilla.org/Features/Release_Tracking Release Tracking]''' page to identify which changes and additions will need documentation. *'''Track Nightly''': We'll follow the '''[https://wiki.mozilla.org/Features/Release_Tracking Release Tracking]''' page to identify which changes and additions will need documentation. The tracking of Firefox features is an ongoing process that will continue through its Beta phase, but, after the move to Aurora, the main changes should only be the possible removal of a feature. *'''Archive''': Since our products, services and documentation will be changing as new versions are released, we'll use this time to evaluate whether there are any articles that are: **Obsolete because our products and services have changed. **Obsolete because they get so few views as not to be of concern to the vast majority of users. ===Doc Cycle Weeks 5 & 6=== *'''Update Release''': A new version of Mozilla's products will have been released so, if necessary, we'll be able to go back and make adjustments to our documentation based on feedback from the support forums. *'''Finalize Beta''': Once Aurora moves to the Beta, we'll have two weeks to finalize these articles that were drafted. During this time we'll: **Add screenshots and screencasts if necessary **Review and approve the articles **Mark the final revision as '''[[#w_ready-for-localization|Ready for Localization]]''' *'''Begin Tracking the new Nightly''': A new release will now be on the Nightly channel. --> == How do I keep up with what's going on? == *'''[http://blog.mozilla.com/sumo Mozilla Support (SUMO) blog]''': The latest project updates and developments are discussed here. *'''[[Contributor News & Resources]]''': This is another good source of information – it's updated every week or so. *'''[/forums/contributors SUMO community discussions]''': This is where contributors talk to one another. *'''[/forums/knowledge-base-articles KB discussions]''': This is the place where we discuss general topics about the KB. *'''[/forums/l10n-forum Localization discussions]''': This is the place where we talk about localizing SUMO. <!-- Below will be moved to a new article about "Guidelines to write a new KB article" = Creating a new article = If you think there's an article that we need to add to the Knowledge Base, here's how to get it done. {note}Be sure to search the KB to see if there is already an article for the topic you want to document{/note} #'''[/en-US/kb/new Create a new article]''' and fill out the form using the source for another article as a guide. #Draft the article content. #Check your work using the {button Preview Content} button. #Click the {button Submit for Review} button and include the reason for drafting the article in the comment. #*Doing this gets the article on the KB Dashboard to let people know that the article is waiting for editing or review. #*The article won't be public until it's been reviewed and approved. == Style == '''We want Mozilla Help to be usable by all users. This means we're writing for a general audience rather than one very familiar with computer techniques and terminology.''' *The person you're writing for doesn't know how to change preferences or add a toolbar button without step-by-step instructions. *Assume that people haven't changed any of the default product or operating system settings. *Conversational writing style – Use an informal, active style similar to the way you'd speak to someone in person. *Images and video – Using images and video to explain things along with text is not only the next best thing to being there to help in person, they are an easy way of including multiple learning styles and repetition. For more information, see '''[[How to write Knowledge Base articles]]'''. == Markup == Our wiki uses MediaWiki syntax along with a few special things for styling buttons, keys, menus, etc. See the '''[[Markup chart]]''' for a list and examples. == <nowiki>{</nowiki>for<nowiki>}</nowiki> == '''[[How to use For]]''' contains instructions and examples for showing and hiding instructions for different Firefox versions and operating systems. == Templates == We have a list of [/kb/category/60 templates] that we use in articles so that the same bit of instruction doesn't have to be re-written, localized and kept in sync across multiple articles. '''[[How to use Templates]] '''explains how it works. == Screenshots & Screencasts == '''We should make sure that articles are written to work without images or videos.''' Though both images and videos are important and greatly increase the helpfulness of an article, they can’t be mandatory. Localizers should feel free to use or delete them as they see fit. --> = Adding and removing articles = == Proposing new articles == Our knowledge base is what makes our entire support effort scale to serve hundreds of millions of Firefox users. The most efficient thing we can do is answer people's questions about Mozilla's products and services with an article. But articles don't come without a cost. Each one has to be written, localized and maintained. With many features and issues already documented, it's often a better use of our collective time to make existing articles better. Before you start creating new articles, let's go over some things you should consider first: '''Do we really need this article?'''<br> These are the main reasons why we add a new article to the Knowledge Base though it often makes more sense to update or add to an existing article. *'''New features''' – User facing features that are likely to generate a lot of interest and questions from users. This may be an inherent aspect of the feature, a result of marketing and in-product links or a combination of the two. *'''New issues''' – Issues that have many recent threads and votes in the support forum. *'''High impact''' – Critical, time-sensitive issues that need temporary documentation (e.g., [[Firefox startup crash with G DATA security software]]). ==Archiving articles== To ensure our Knowledge Base remains focused on the most current and pressing user inquiries, we periodically review and archive articles that no longer reflect the latest versions of Mozilla products or services user concerns. Archiving is not the end of an article; it's a way to signal that the content might be outdated or less relevant to our current user base, while still preserving its historical value and access for those who might need it. ===How it works=== Staff and contributors with reviewer privileges can mark an article as obsolete. This is done by editing the article's ''description page'' accessible through the ''Edit Article Metadata'' option under ''Editing Tools''. An archived article is removed from all dashboards, including localization dashboards, and it won't appear in normal search results. However, any existing direct links to the article will still work. A banner will be displayed at the top of the article to inform readers that it is no longer being maintained and might be out of date. Archiving is reversible. Should the need arise, contributors can revisit the {button Edit Article Metadata} page and uncheck the ''Obsolete'' option, bringing the article back into active status. ===Considerations before archiving=== *'''Low views:''' Articles attracting less than 1500 visits per month are candidates for archiving. *'''Few recent reports:''' The lack of recent threads or votes in the support forum suggests the article addresses a lesser concern. *'''Low impact:''' Articles whose removal is unlikely to cause significant issues. Product changes: Articles related to issues that have been resolved or features that have changed significantly. ===Guidelines for archiving KB articles=== When deciding to archive an article, consider the following to ensure the decision aligns with the best interests of our user base and the accuracy of our Knowledge Base: *'''Obsolescence and irrelevance:''' Articles should be archived if the content is no longer relevant to the current versions of Mozilla products or services. For details, see Firefox version support policy for Knowledge Base content. *'''Redundancy:''' Content that has been superseded by more comprehensive articles or duplicated across multiple articles without adding unique value should be archived to streamline the knowledge base. *'''Historical content:''' Articles that serve more as a historical record rather than providing practical, current support may be archived to keep the active knowledge base focused on user support. ==Restrict visibility== The Restrict Visibility feature is a recent addition aimed at enhancing the flexibility of content management within the SUMO platform. This feature allows specific articles to be visible only to designated groups, such as staff members or certain contributors, enabling the distribution of sensitive or early-stage content in a controlled manner. [[Image:Restrict visibility feature]] ===How it works=== Restrict visibility empowers staff and contributors with reviewer privileges to manage the accessibility of articles to specific audiences. This feature is important in controlling the dissemination of sensitive or early-stage information that's not yet intended for the broader public. Here's how it operates: *'''Setting restrictions:''' A staff member or contributor with the necessary privileges can restrict an article's visibility. This is achieved by navigating to the article's Description page and selecting the appropriate visibility settings from the "Edit Article Metadata" section found under Editing Tools. *'''Impact of restriction:''' Once an article is set to restricted visibility, it becomes inaccessible to the general public and only visible to staff members and designated groups (like specific contributor circles, NDA'd contributors, etc). This action removes the article from general search results and public dashboards, though direct links to the article remain functional for those with access. *'''Visibility indicators:''' Articles with restricted visibility will feature indicators or banners to clarify their status to viewers who have access. This alerts them that the content is restricted and may contain information not yet public or intended for a specific audience. *'''Reversibility and Adjustment:''' The restrict visibility setting is not permanent and can be adjusted as the need for restriction changes. Staff and contributors with the appropriate privileges can return to the article's metadata settings to modify visibility restrictions, making the article available to a broader audience or adjusting the groups that have access. ===Considerations before restricting visibility:=== Before applying the Restrict Visibility feature to an article, it's crucial to weigh the following to ensure the feature is used effectively: *'''Audience necessity:''' Ensure the content is indeed intended for a specific audience and not beneficial for the wider user base. *'''Content sensitivity:''' Assess the sensitivity of the information to determine if restricted visibility is warranted. *'''Impact on forum support:''' Consider whether restricting the visibility of the article could negatively impact users who might otherwise benefit from the information, and if so, seek alternative methods to address any concerns. *'''Temporal relevance:''' For content that is only temporarily sensitive (for example, features under embargo until a certain date), plan to adjust visibility settings once the information is no longer restricted. ===Guidelines for restricting visibility:=== *'''Pre-release content:''' Ideal for articles detailing upcoming features or products that are not yet public. *'''Targeted communication:''' Enables the sharing of information with specific groups within our community, such as NDA'd contributors or locale leaders, without making the content public. *'''Sensitive information management:''' Useful for content that, due to its sensitive nature, requires restricted access. = Article review guidelines = To learn about guidelines for reviewing Knowledge Base articles, see [[Article review and approval guidelines]]. = Complete Knowledge Base guidelines = If you're really interested in editing and writing documentation, here are a few resources that should help explain how we do things: '''Create new support articles''' * [[Write articles for the Knowledge Base]] — Guide to writing techniques and styles that we use to make articles more engaging and effective. For the mechanics of actually creating or editing articles, see: ** [[Create a new Knowledge Base article]] – Steps for creating a new article, along with some sample wiki markup to get you started. ** [[Anatomy of a Knowledge Base article]] – Explains the basics of how articles are built. ** [[Article Description]] – Explains how to write description for a support article. '''Improve existing support articles''' * [[Improve the Knowledge Base]] – Learn how to improve SUMO Knowledge Base. * [[Edit a Knowledge Base article]] – Steps for editing an existing article. '''Other guidelines''' * '''[[About the Knowledge Base]] — An overview of the mechanics of our Knowledge Base (You're here!)''' * [[How to make screenshots]] — A step-by-step guide to creating screenshots to use in articles. * [[Article review and approval guidelines]] – Reviewer guidelines for Knowledge Base. * [[Add images and screenshots to Knowledge Base articles]] — Explains how to add screenshots to articles and have them display correctly. * [[Markup cheat sheet]] – The most commonly used wiki markup in our articles. * [[Markup chart]] — Wiki markup reference. It gives examples and shows the markup that produces them. * [[How to use "For" tags|How to use <nowiki>{</nowiki>for}]] — Special wiki markup that lets us show instructions ''for'' different application versions (for example, Firefox 115) and operating systems such as Windows and macOS. * [[Using Templates]] — Templates are reusable pieces of content. You can include a complicated set of step-by-step instructions in multiple articles by using a template. * [[When and how to use keywords to improve an article's search ranking]] — Explains when adding keywords to an article is appropriate. * See more guidelines on Knowledge Base contribution [https://support.mozilla.org/en-US/products/contributor/kb here].