643021 - Design new wiki / edit page

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: Wiki pages, defect)

Description

[Jay Patel [:jay]]

As discussed today during our Kuma 1.1 design meeting, the requirements are on the wiki here: https://wiki.mozilla.org/MDN/MDN:Kuma_Meeting_2011-03-18#1.1_Requirements

Please ask any new questions that come up and mockups here so we can track progress.

Thanks!
- Jay

Comment 1

[Jay Patel [:jay]]

Assigning to chowse so he can attach his first round of mockups.

Sheppy/Janet:  Can you please take a look at the current mockups and provide your initial feedback on how the layout and visible feature feels?   Anything missing?  Stuff we need to consider removing or adding based on your doc writing experience and wish list? https://wiki.mozilla.org/MDN/MDN:Kuma_Meeting_2011-03-18#1.1_Mockups

Comment 2

[Chris Howse [:chowse]]

Wireframes:

http://people.mozilla.com/~chowse/drop/mdn/wiki/v1/
http://people.mozilla.com/~chowse/drop/mdn/wiki/v1/00_All.pdf

Comment 3

[Jay Patel [:jay]]

I like what Chowse has done for v1... a few specific things that stood out to me:

1. The tabbed interface works well to maximize the screen real estate for the main editing window.
2. I like the simple edit article where the title and url/slug are not editable (except for the links visible for admins).
3. Having the main action buttons in the upper right fits the overall style of the rest of the site and I think will help us improve visibility of the wiki-ness of MDN if we can put the edit button on all the pages in the same place.

The only ideas I have for future needs are:

1. It would be great to have a way to highlight sections of the article that are code snippets or other "templated" blocks... and give the user the option to just edit that piece of the content.
2. #1 would require a unique UI to allow the user to edit a section of the page within the contest of the full page.

No idea if that's something that will even be necessary, but just thought of it so wanted to share.  I'll let Sheppy and Janet chime in on the value of something like that.

Comment 4

[Chris Howse [:chowse]]

(In reply to comment #3)
> 2. I like the simple edit article where the title and url/slug are not editable
> (except for the links visible for admins).

Is renaming/slug editing only available to admins? Not that it has a big effect on the UI, but I assumed it was available to anyone.

Speaking of slug editing, what affect does this have on intrawiki links? It's not clear to me how you specify the link's target. Is it just an ordinary URL? Is it an article's slug? If an article's slug changes, will references to it be updated, or a redirect added?


> 1. It would be great to have a way to highlight sections of the article that
> are code snippets or other "templated" blocks... and give the user the option
> to just edit that piece of the content.

Interface-wise, this shouldn't be hard. Inserting or marking an area as a code block would be no different than adding a table. How gracefully CKEditor can support this, or how it will look in source mode, is an open question.

> 2. #1 would require a unique UI to allow the user to edit a section of the page
> within the contest of the full page.

There are 2 ways we could handle this:

* Editing a section opens the standard editing page, and scrolls down to the
  section being edited. A bit less seamless, but much simpler for maintenance.
  The downside is a new page load, and the entire page must be opened in the
  editor.

* Open the editor in-place, as DekiWiki is currently implemented. This would
  require duplicating some of the editor UI in the main page UI (floating
  toolbar and buttons) as wells as some extra styling to distinguish editable
  from non-editable content. The up-side is edits can be made in small chunks
  (loading the CKEditor w/ an entire page could be expensive). The downside
  is increased code and UI complexity.

Comment 5

[Eric Shepherd [:sheppy]]

(In reply to comment #1)
> Assigning to chowse so he can attach his first round of mockups.
> 
> Sheppy/Janet:  Can you please take a look at the current mockups and provide
> your initial feedback on how the layout and visible feature feels?   Anything
> missing?  Stuff we need to consider removing or adding based on your doc
> writing experience and wish list?
> https://wiki.mozilla.org/MDN/MDN:Kuma_Meeting_2011-03-18#1.1_Mockups

Those look pretty good. I'm assuming the drawing of the toolbar in the editor is just a placeholder rather than intending to indicate what the actual contents of the toolbar would be.

I'm not convinced we need a separate "search result summary"; what happens if nothing is put in there? Does a summary get generated automatically from the contents of the article?

Comment 6

[Eric Shepherd [:sheppy]]

(In reply to comment #3)

> 1. It would be great to have a way to highlight sections of the article that
> are code snippets or other "templated" blocks... and give the user the option
> to just edit that piece of the content.

Yes. In general, being able to do this would be a big help.

> 2. #1 would require a unique UI to allow the user to edit a section of the page
> within the contest of the full page.

Being able to edit just a section of the page is a must-have item. Having to pull up the entire page in the editor can be problematic, especially for large pages that have a lot of complex content (the editor gets really slow if you have lots of tables in it, for example).

Comment 7

[Eric Shepherd [:sheppy]]

(In reply to comment #4)

> Is renaming/slug editing only available to admins? Not that it has a big effect
> on the UI, but I assumed it was available to anyone.

IMHO only people with special privs should be allowed to edit slugs. It might be something that we will eventually re-assign so that all users have that privilege, but right now it seems like it would be better to restrict how many people can do it.

> Speaking of slug editing, what affect does this have on intrawiki links? It's
> not clear to me how you specify the link's target. Is it just an ordinary URL?
> Is it an article's slug? If an article's slug changes, will references to it be
> updated, or a redirect added?

Ideally, references would be updated. Currently, when we establish links, we use the URL to the article.

I'll be honest, I still don't understand what the point to the slug is. It sounds like an extra way to reference an article that's not really needed; that's what the URL is for. I think it overly complicates things.

> * Open the editor in-place, as DekiWiki is currently implemented. This would
>   require duplicating some of the editor UI in the main page UI (floating
>   toolbar and buttons) as wells as some extra styling to distinguish editable
>   from non-editable content. The up-side is edits can be made in small chunks
>   (loading the CKEditor w/ an entire page could be expensive). The downside
>   is increased code and UI complexity.

FWIW, this is how Deki does it, and I happen to like it, although it occasionally does odd things with scrolling and sizing of the edit box (although those issues have mostly gone away in recent updates of the software).

Comment 8

[Jay Patel [:jay]]

(In reply to comment #4)
> (In reply to comment #3)
> > 2. I like the simple edit article where the title and url/slug are not editable
> > (except for the links visible for admins).
> 
> Is renaming/slug editing only available to admins? Not that it has a big effect
> on the UI, but I assumed it was available to anyone.

We decided that slugs should only be edited by admins or trusted users, since we want to keep the URL paths consistent and clean.

> Speaking of slug editing, what affect does this have on intrawiki links? It's
> not clear to me how you specify the link's target. Is it just an ordinary URL?
> Is it an article's slug?

This needs to be sorted out.  I'm guessing we should keep a mapping of all wiki urls and slugs... and honor both.  

>If an article's slug changes, will references to it be
> updated, or a redirect added?

And keep track of all changes to the slug and setup appropriate redirects.   However, I do want to make it possible for us to reclaim slugs so that we don't lost them with each change.   This will require us to think about how we want to do it in the UI and set some guidelines/rules.   Here are a couple of things to keep in mind:

1. If a slug is changed and the old one is not liberated/freed, we need to setup rewrites.
2. If a slug is changed and the old one is liberated/freed, when a new page is created with that same slug, we might want to consider adding a note/message/alert that says something like "Looking for <old slug page title/url/path?" and offer them a link to that page.   This will help make sure old/stale links take people to the appropriate place.

We definitely need to think this through... and i'm sure this is a common issue with slug implementation, so hopefully webdev has some best practices and advice here.


> > 1. It would be great to have a way to highlight sections of the article that
> > are code snippets or other "templated" blocks... and give the user the option
> > to just edit that piece of the content.
> 
> Interface-wise, this shouldn't be hard. Inserting or marking an area as a code
> block would be no different than adding a table. How gracefully CKEditor can
> support this, or how it will look in source mode, is an open question.

Cool... any type of visual aid to help readers and editors identify special content within the text would be awesome.

> > 2. #1 would require a unique UI to allow the user to edit a section of the page
> > within the contest of the full page.
> 
> There are 2 ways we could handle this:
> 
> * Editing a section opens the standard editing page, and scrolls down to the
>   section being edited. A bit less seamless, but much simpler for maintenance.
>   The downside is a new page load, and the entire page must be opened in the
>   editor.
> 
> * Open the editor in-place, as DekiWiki is currently implemented. This would
>   require duplicating some of the editor UI in the main page UI (floating
>   toolbar and buttons) as wells as some extra styling to distinguish editable
>   from non-editable content. The up-side is edits can be made in small chunks
>   (loading the CKEditor w/ an entire page could be expensive). The downside
>   is increased code and UI complexity.

I like option #2... that is the reason I came up with this idea.  I want to improve performance and make it easier for people to make changes to small chunks of content.   If the development costs are too much or makes the UI overly complex, we can reconsider... but I think this would be a killer feature and make a lot of people happy.

Comment 9

[Chris Howse [:chowse]]

(In reply to comment #5)
> Those look pretty good. I'm assuming the drawing of the toolbar in the editor
> is just a placeholder rather than intending to indicate what the actual
> contents of the toolbar would be.

Yes. If you have time, I wouldn't mind doing an audit of the toolbar to decide how those controls should be organized. Something I'm considering is a single-line toolbar w/ the most common options, with a button that exposes all other controls. I'll attach an example.


> I'm not convinced we need a separate "search result summary"; what happens if
> nothing is put in there? Does a summary get generated automatically from the
> contents of the article?

That'll depend on what search technology we use. If our search provider supports excerpts that highlight where search terms were matched (a la Google search results), that's what I'd recommend. Failing that, we could generate an excerpt from the first few sentences of the article. I'd strongly encourage the former, though, even over an editor-provided result summary.

Comment 10

[Chris Howse [:chowse]]

Attachment: Collapsed/Expanded Toolbar Example

From Wordpress. Clicking the top-right toolbar button (or clicking Alt+Shift+Z) exposes the second row of the toolbar.

Comment 11

[Eric Shepherd [:sheppy]]

Something like that is fine. One thing I would really like us to have is the ability to customize the toolbar more easily than we can do in Deki. Having users be able to eventually tweak their toolbars based on the type of work they do would be extremely helpful.

However, that's a future issue to work out later.

Comment 12

[Chris Howse [:chowse]]

(In reply to comment #7)
> I'll be honest, I still don't understand what the point to the slug is. It
> sounds like an extra way to reference an article that's not really needed;
> that's what the URL is for. I think it overly complicates things.

AFAIK, the slug IS the URL path, minus the domain and locale portion. So if you were to drop it in to a wiki link, it should just work. If you don't want to customize the slug, you can safely ignore it and the wiki will generate it for you automatically.


> > * Open the editor in-place, as DekiWiki is currently implemented.
> 
> FWIW, this is how Deki does it, and I happen to like it, although it
> occasionally does odd things with scrolling and sizing of the edit box
> (although those issues have mostly gone away in recent updates of the
> software).

Given this and the performance concerns, I'll have to work this back into the designs.

There is another compromise between the two extremes: if you edit a section, it opens a new editor page, but only shows content from that section. This is the MediaWiki approach, e.g. https://wiki.mozilla.org/index.php?title=MDN/MDN:Kuma_Meeting_2011-03-18&action=edit&section=5

Comment 13

[Luke Crouch [:groovecoder]]

Slugs:

Slugs are effectively equivalent to url's. A slug of /JavaScript/A_re-introduction_to_JavaScript puts the page at http://developer.mozilla.org/JavaScript/A_re-introduction_to_JavaScript

In SUMO/Kitsune, and therefore Kuma, authors put "REDIRECT [[Target]]" to turn a page into a redirect page that sends a 302 with Target's url in the Location. If you want to reclaim that redirect page, you go to the page with ?redirect=no to edit the page and remove the REDIRECT.

Sounds like slugs are an important feature, so let's make sure redirects land in the very next release (1.2) after simple new/edit pages.

Editor:

CKEditor looks pretty customizable. Let's set the default controls for 1.1 and then we can look at lettings users customize their own set in a future release.

Sounds like partial-page editing is another big feature so maybe that's in 1.2 also?

Comment 14

[Luke Crouch [:groovecoder]]

comment should say "Sounds like *redirects* are an important feature, so ..."

Comment 15

[Luke Crouch [:groovecoder]]

should we update the wireframes with this feedback and get started?

Comment 16

[Eric Shepherd [:sheppy]]

Yeah, sounds like a plan. We'll be talking a lot on Thursday; I bet we can come up with a pretty good plan going forward this week!

Comment 17

[Chris Howse [:chowse]]

Updated mocks:

http://people.mozilla.com/~chowse/drop/mdn/wiki/v2/
http://people.mozilla.com/~chowse/drop/mdn/wiki/v2/00_All.pdf

99% complete. Still need to add documentation and changes to the 'This Page' menu. Please let me know any feedback you have.

These include a few features that might not make this release (e.g. drafts, page templates) but want to reserve space for in the near future.

Comment 18

[Luke Crouch [:groovecoder]]

> These include a few features that might not make this release (e.g. drafts,
> page templates) but want to reserve space for in the near future.

Yeah let's be sure today we know exactly what minimal features are expected for 1.1.

Comment 19

[Eric Shepherd [:sheppy]]

Those mockups are full of sexy. I have no complaints. And you all know how rare that is. :)

Comment 20

[Chris Howse [:chowse]]

And suddenly, documented mocks:

http://people.mozilla.com/~chowse/drop/mdn/wiki/v2/
http://people.mozilla.com/~chowse/drop/mdn/wiki/v2/00_All.pdf

These mocks contain a few features that may be beyond scope:

* DRAFTS. The wiki editor auto-saves a copy of your changes at regular
  intervals and can restore these changes if you leave the page or your browser
  crashes. This could be done with completely locally with sessionStorage and 
  CKEditor's getSnapshot feature.

* PREVIEWING. These mockups include the ability to preview the changes that
  have been made before committing them. As more content begins to use features
  that cannot be properly rendered by CKEditor (e.g. templates, code samples),
  it's important to be able to test your edits before committing. DekiWiki does
  not appear to currently support this.

* SECTION EDITING. These design treat editing as being done on a completely
  separate page, including section editing. For the latter to work, some
  extra content must be added to the edit page to provide context (see mockup 
  P5). On the plus side, this keeps all the editing code segregated from the
  page viewing code, and can allow for new functionality like previewing.

* PAGE TEMPLATES. As many Wiki pages seem to follow a common mold, I thought it
  would be useful to support page templates when creating new pages. A page
  template is an ordinary wiki article that is dropped in verbatim when
  creating a new page. For example, a 'Javascript Reference' article could
  provide the common page structure and headings (e.g. methods, parameters, 
  examples) and leave placeholders for actual content.

Comment 21

[Eric Shepherd [:sheppy]]

A few notes:

1. The current default toolbar we have on MDN's editor is not ideal; it's just the best we could come up with right now. Ideally we'd have buttons for <code> and for <h1>-<h3> added.

2. Will users be able to see drafts created by others? Or at least be able to see that drafts exist, so they know that work is in progress?