The page begins with a brief summary of the document suite for which this is an index or table of contents.
Index or TOC
Then comes a section entitled either "Index" or "Table of Contents". The contents of this section are as follows:
For an index, this is a multi-column area divided up by letter of the alphabet, with items for each page in the suite. For an example, see the CSS Reference.
Table of contents
A table of contents is a simple
<ol> (ordered list) of the chapters and, optionally, one or two heading levels deep, of the documents comprising the "book." For example:
The recent changes list is a list of changes to articles in this set of content that have changed recently. For example, on the CSS Reference index page, this would be a list of recent changes to articles in that reference.
This section describes details of the editing experience for TOC/index pages.
Note: We will probably want to establish a privilege group for editing of landing pages. In fact, probably two groups: one group that has privileges for editing any landing page, and then another group with per-landing page privileges, to allow configuration of people with special permission to edit given zones' landing pages. This will let us give product managers for given topic areas permission to edit their topic's landing pages.
- There is nothing on the sidebar(s) on landing pages that the user needs to be able to edit.
Editing features needed
- Add "Related topics" box
- This button would create the "Related topics" box at the bottom of the page. Only one such box is allowed per page.
- "Link to all subpages" button
- This button would insert appropriate KumaScript template to automatically insert links to all subpages. There are two forms of this: (1) a simple list of links, with the text being the title of the destination page; (2) a definition list with the titles being the page titles (linked to the pages) and the descriptions being the pages' summaries.
- "Insert alphabetical index" button
This button would insert, in essence, the APIListAlpha template, which generates an alphabetical list of all subpages,
<code>styled. This would be used for lists of API terms.
- Definition list buttons
We need the buttons for creating
<dl>elements, as well as for
<dd>. We also need to be sure that editing of and deleting these works reliably (it can be a little quirky right now) if we want to remove source editing eventually; currently you have to resort to source mode sometimes to fit problems with the lists. These lists would be used when we need to include pages that aren't subpages.
- Bullet list button
We need a button for creating
<ul>s, for the offsite link list, for example.
- Insert image button
- We need to be able to insert images, to use a product or technology logo somewhere on the page (most likely in the intro area).
- Link/unlink buttons
- We need to be able to create and remove links.
- Bold/italic buttons
- We should allow creating bold and italic text.
- API/function name button(s)
We need buttons for styling text as the name of a class/interface/function name. Ideally these would have different classes on the
<code>element for the different types of these, and would automatically create the appropriate link to that term's page, but that may be a long-term goal.
Editing features NOT needed
There are things we expressly do not want to have available in the editor:
- Foreground/background color
- Code samples
- Justification (left/center/right)
- Bullet lists
- Ordered lists