Editor requirements for MDN revamp

As we work toward improving the user experience on MDN, we're evaluating the possibility of switching to a different editor, or at least making significant changes to how we use CKEditor, the editor we currently use. This article will look at the features we need in an editor so we can better evaluate our options.

Ideally, it would be possible to mark each page with what type of page it is and provide a customized editing experience for each type. Possibly we might also provide boilerplate for each to offer predetermined page layout for each.

Open questions and random ideas

• Can we use the ribbons concept to do all compatibility information, rather compatibility tables on every page? Basically, you'd have bars down the side of the page for each browser, with the version compatibility for each browser included there, but the ribbon missing for each browser in any part of the text that's not supported in that browser?
• How much can we do with boilerplate for each type of page? Is it possible to reduce the amount of UI needed by instead of having lots of buttons for general HTML stuff instead having on a DOM reference page a button to insert the boilerplate for a DOM interface, property, or method when you create the page?
• Can we automatically convert appropriate terms into links so users can just write and let the platform handle this chore? If I write the sentence "You can use window.setTimeout() to do this.", it would be fabulous if window.setTimeout()" were automatically given <code> styling and turned into a link to the appropriate page in the DOM reference. Could this be done using something similar to how spell check as you type works, with squiggles underneath the text to indicate that a link will be created for you, and let you do something like right-click the term to disable it if the automatic detection is wrong?

Things needed everywhere

Regardless of the type of content being worked on, we need these basic capabilities:

• Must work on both desktop and mobile (Android/iOS/Firefox OS) [above some minimum screen width?]
• Find/replace
• Spell checking (ideally with support for not checking anything that's inside <code> or <pre> blocks).
• Pages with advanced access privileges: we may want to allow editing the page's raw HTML, with no restrictions on what can be done in the content. This will let us create more complex, less wiki-like pages as needed for special product content and the like.
• The goal is to avoid having to ever drop into HTML editing to get the content to look and work right, with the possible exception above. Ideally, we won't need a "Source mode" option at all. Note that nowadays, the HTML source mode is often used to fix problems when CKEditor get lost (like </ul> added in the middle of a list and impossible to remove), or to remove unexpected <p>&nbsp;</p> added during regular editing. The quality of the generated HTML is important.
• The save buttons and the box for adding a revision comment must be close to one another. Ideally, all of these would also be close to the tag box.
• Should always be easy to select the SEO summary text from the introduction; currently this option is tucked into the Style drop-down.

Things we'd like to have everywhere

• Inline editing; this would be awesome but can be dropped if we lose too much other stuff to get it.

Things we don't need

We should not need buttons for color or font selection on any page. The goal is to use CSS for all styling. In theory we should be able to do away with a "source mode" option.

Page types and features needed

Different page types need different capabilities and user options and controls. The following sections cover this for each type of page.

Landing pages

Link to page type description

• Easy support for creating headers for sections on the landing page, with the appropriate styles (see the headers on the CSS landing page for example).
• Ability to add and easily edit definition lists (<dl>); we use these to present titles and summaries of the articles.
• Easy creation of a link to all pages matching a specific tag (for the "View all" link we typically have at the bottom of lists of articles on landing pages).
• Easy support for badging items in the definition list as being related to a specific product or version, or as non-standard, etc. We might, for example, offer a drop-down menu listing available badges, some of which might pop up a dialog asking for details (such as what version(s) of the product the badge should reference).
• Support for ensuring the content created is responsive to screen size (that is, presented in 2 columns on a large screen, or just 1 on a small screen).
• Support for easily linking to subpages. There are two ways to do this, and we probably want to support both:
  • A button that simply inserts a template call that builds the definition list automatically using all subpages of the landing page.
  • A button that brings up a dialog that lets you choose a subpage of the landing page. Choosing the subpage populates a "Summary" edit box with that page's summary, and lets you edit it before inserting the item into the definition list; the page's title would be used for the <dt> and the edited summary for the <dd>.
• Other controls needed: link/unlink, bold, italic, <code>, insert image, headings, note and warning boxes.
• Easy generation of links to content in references, using the cssref, domxref, and so forth templates probably.
• Compatibility table generation.
• Support for actions boxes (like the CSS landing pages) to help people finding important things in long lists.

Tables of contents/indexes

Link to page type description

Must have

• Ability to quickly create A-Z headings. One click, and the headings are all inserted. Nice handling of letter holes: automatic generation of range of letters like G — T
• Adaptive display. These often involve a very large number of very short titles (for example on the CSS Reference page). Ideally these are presented using several columns on large screens, but in a single column on a phone.
• Easy generation of links to content in references, using the cssref, domxref, and so forth templates probably.
• Support for easily linking to subpages. There are two ways to do this, and we probably want to support both:
  • A button that simply inserts a template call that builds the definition list automatically using all subpages of the landing page.
  • A button that brings up a dialog that lets you choose a subpage of the landing page. Choosing the subpage populates a "Summary" edit box with that page's summary, and lets you edit it before inserting the item into the definition list; the page's title would be used for the <dt> and the edited summary for the <dd>.
  • Keep in mind that often these links will be to API terms, and we will need to style them in that case, or add parentheses after the titles if they're methods.
• For TOCs for series of articles, support easily creating a "Next page" button to go to the first page of the series.
• Easy support for badging items as being related to a specific product or version, or as non-standard, etc. We might, for example, offer a drop-down menu listing available badges, some of which might pop up a dialog asking for details (such as what version of the product the badge should reference).
• Other controls needed: link/unlink, bold, italic, <code>, insert image, headings, note and warning boxes

Nice to have

Articles

Link to page type description

Must have

• Support for Ribbons system once we have that; ability to highlight a section of text then click a button to apply a ribbon; this would likely bring up a dialog asking you to specify what ribbon to add by choosing a product and version range the text applies to. Keep in mind that a given block of text may have multiple ribbons indicating the compatibility information for multiple browsers.
• Support for inserting and managing live samples.
• Support for inserting previous, next, and prevnext links to link series of articles together.
• Other controls needed: link/unlink, bold, italic, <code>, insert image (with good alt attribute), headings, note and warning boxes.
• Embed video (if possible without using youtube, but ...). Support for popcorn.js.
• Compatibility table generation and management.
• Tables.
• Lists: DL, OL, UL; we use all of these frequently.
• Automatic management of special ribbons indicating that the page's content is about an experimental or non-standard API, in coordination with the compatibility tables.

Nice to have

Reference pages

Link to page type description

Must have

• Other controls needed: link/unlink, bold, italic, <code>, insert image (with good alt attribute), headings, note and warning boxes
• Compatibility table generation and management.
• Easy support for badging items in the definition list as being related to a specific product or version, or as non-standard, etc. We might, for example, offer a drop-down menu listing available badges, some of which might pop up a dialog asking for details (such as what version(s) of the product the badge should reference).
• Support for easily linking to subpages. There are two ways to do this, and we probably want to support both:
  • A button that simply inserts a template call that builds the definition list automatically using all subpages of the landing page.
  • A button that brings up a dialog that lets you choose a subpage of the landing page. Choosing the subpage populates a "Summary" edit box with that page's summary, and lets you edit it before inserting the item into the definition list; the page's title would be used for the <dt> and the edited summary for the <dd>.
• Support for Ribbons system once we have that; ability to highlight a section of text then click a button (or choose a ribbon to apply from a drop-down menu) to apply a ribbon; this might need to bring up a dialog asking you to specify what ribbon to add by choosing a product and/or version range the text applies to. Keep in mind that a given block of text may have multiple ribbons indicating the compatibility information for multiple browsers.
• Live samples.
• Tables.
• Syntax box style.
• Automatic management of top banners (experimental, non-standard, ...) in relation to compatibility tables.

Nice to have

• Can we figure out a way to automatically build lists of the methods, properties, and so forth that are subpages? Would be awesome if we could have the lists on these pages stay up to date without having to remember to fix them after adding new subpages.

Reference subpages

Link to page type description

Must have

• Other controls needed: link/unlink, bold, italic, <code>, insert image, headings, note and warning boxes
• Compatibility table generation and management.
• Ribbons.
• Live samples.
• Tables
• Lists: DL, OL, UL

Nice to have

Tabular data pages

Link to page type description

Must have

• Table controls right in the toolbar, since all content on these pages are tabular.
• Other controls needed: link/unlink, bold, italic, <code>, insert image, note and warning boxes
• Lists: DL, OL, UL
• Ribbons
• Autogeneration of specific "class" for lines (tabular data pages acts as a database table for other templates)

Nice to have

Templates

Link to page type description

Must have

• Use a code editor.
• Provide links to JavaScript and KumaScript documentation.

Nice to have