(not sure if this should go in m.d.mdc or m.d.mdn, hope this is right)
tl;dr: Demo and screenshot of a mdn-navigation in last section.

I think there are some issues that prevents MDN from being a good
documentation site and think promotejs/arewefirstyet (that BTW promote
old url formats) and other SEO initiatives are a bit premature.
Currently I believe I am more likely to get an answer fast from e.g.
w3schools, although it might not be as comprehensive as MDN. You have
probably heard some of the comments before, but hopefully this is not to
redundant.

The primary problem, I think, is that the site feels slow. Quite a few
things could be done to speed it up:
- Don't use SSL
- Pre-generate all pages a static html files (there are only ~20k pages)
and handle redirects in mod_rewrite (the user state could be a iframe or
a tiny amount of inline JavaScript).
- Rewrite all links when rendering page content so no links point to
urls that are redirected. E.g. the link
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_...
in text "Method of Array" currently goes to url, that redirects to
another url.
- Remove/Reduce the use of JavaScript (especially from other domains), e.g.
- - The google search api seems to be loaded on every page even though
it is only used on the search page.
- - "tabzilla.js" could be inlined and do not need JavaScript
- - Persona is only needed when the button is clicked
- - Syntax-highlighting ought to be done on the server side
- - Most of the JavaScript seems only the be relevant for logged in
editors or for few pages (e.g. the video players).
- - jQuery is not really needed.
- The use of custom css-fonts seems to give a "flash of unstyled
content" which might be one thing that makes the site *feel* heavy. So
even though it is a cool feature, I think the price is to high in this
case. I think MDN shouldn't be a demo of every bell and whistle, but
rather aggressively strive to be the most useful, which in this case
implies fastest, on the net.

But the site is also difficult to navigate and to get an overview of for
several reasons:
- The site lacks primary navigation. Some pages have a breadcrumb either
in the top (in very dimmed colors) or in some non-standard way (e.g.
PR_CreateThreadPool in the NSPR api reference, that BTW have many broken
links), but it doesn't give a sense of what the related pages are.
- The tags in the bottom are close to useless for navigation. I assume
the system/editorial tags (like MakeBrowserAgnostic or
NeedsTechnicalReview) are useful for the editors, but none of the tags
are for users. The tag pages (e.g. /tag/JavaScript) are to messy and
unstructured to be used for navigation.
- The search is implemented such that it loads a new MDN page (which is
slow) and requires 3rd-party-javascript to be enabled, so it is the
worst of both worlds. But it also returns non-relevant results, e.g. it
returns results from other locales (at a minimum, translations should be
folded in to one result item), "meta pages" (like "$history", "$compare"
and talk) are included (although I think a blogpost mentioned some of
this was being fixed). On the search results page the items are very
tall and contains some variation of "| MDN - Mozilla Developer
Network"/"| MDN"/" - Mozilla Developer Network" and the domain and url
of the page, al of which is redundant and noisy.
- Obvious spam and junk content (e.g. /en-US/docs/aaaaaa), as well as
all the "... (External)"-pages should be completely deleted.
- Probably caused by the lack of navigation, I often get the feeling
that the same content exists in multiple places, and some of it on other
Mozilla sites, e.g.
https://addons.mozilla.org/en-US/developers/docs/sdk/latest/

The individual pages (to use an example
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_...
) also have some problems, I think:
- The urls are very long and a mix of upper- and lowercase. No need of
including all levels of ancestors in the path (in this case,
"JavaScript" could be "js" and "docs", "Reference", "Global_Objects",
and even "en-US" are kind of implied).
- The style of writing seems verbose with more of a prose-style than
that of a reference. E.g. when I have used this page, it has often been
to check the arguments for the callback. But this information is only
found described as prose in the second paragraph of the forth section.
If the syntax box (that doesn't really need to have its own header) was
simply something like "array.map(callback(item, index, array)[,
thisArg])", it would be easier and less error-prone to find the answer
quickly.
- The "Implemented in"/"ECMAScript Edition"-box is very prominent on the
page. But it is the least helpful information, since I suspect few know
of the top of their head what browser versions included what version of
the spec (or which part of the spec was included, and if it was bug
free). So this should at least be moved to the browser compatibility
section.
- The table of contents, and especially the "tags"- and "files"-links
under it, aren't really useful.
- The layout of the page ought to be much more compact, e.g. smaller
headings with no underlining, less padding in the syntax box, less
white-space everywhere. The dl/dt/dd that are used for parameters, would
probably be more readable/skimmable if it was put in a table.
- I also think that the brown color scheme communicate something
dull/dirty/old/heavy, as opposed to the light/fresh/happy blue scheme of
Addon SDK site (although it is perhaps a bit to "busy").

I tried to implement a mockup of a navigation as an addon to get an idea
of if it would make the site feel different and I think it does. The
addon can be found here and I added a screenshot in the data-folder for
those that do not want to run un-vetted addons:
https://builder.addons.mozilla.org/package/153894/latest/
Note that:
- The structure is based on ".../en-US/docs/all", so all pages should be
represented so the menu should be complete. But I have tried to merge
redirects and talk pages using some heuristics and this process probably
introduced errors (but could easily be created on the server).
- I have structured some of the content manually (e.g.
https://developer.mozilla.org/en-US/docs/FC_CloseSession ). This is
process is far from complete (as e.g. illustrated by the many items
under "Other"), but this is exactly the problem with the current site.
Some of the structure is probably also wrong. But I do believe that
every page could be placed into some hierarchy with one parent, that
would seem logical to most users and that most editors could agree on.
- I am not suggesting that the navigation should be implemented as
JavaScript or that new pages should be loaded inline (nor that a 2MB
json-file should be used). This is a mockup. Instead the navigation
should be rendered as plain html. The navigation could perhaps be
progressively enhanced with JavaScript to allow expanding and
collapsing, but the navigation might also just be some more traditional
menu. The instant search should of course also be performed on the server.
- All the aliases (i.e. the pages redirecting to the page) is show in
the little yellow "..." popup box. This is primarily for debugging and
shouldn't be included.
- To illustrate how different "satellite documentation sites" could be
tied into MDN I added the addon api documentation so the navigation also
appears there.
- The addon also "fixes" some of the layout problems, e.g. replaces the
lists with tables, reduces the heading size and underline, removes some
spacing, remove the table of contents.

--
Anders

Hi Anders,

This was indeed the right place to send your comments. Thank you for the feedback - it is appreciated! We are starting up a project to redesign MDN and will add your comments to the list of things to review and prioritize, either as part of the redesign or as platform fixes/features. Many of the issues you mentioned are already on our radar to fix, and I'll add the others to my review/issue list as well.

thanks,
-ali

ali spivak
MDN Product Manager, Mozilla
408-859-8260
aspi...@mozilla.com

Hi Anders,

thank you very much for your comments.

Improving the performance of the MDN is one of our major concern. We
have a meta bug that track all the ideas. (
https://bugzilla.mozilla.org/show_bug.cgi?id=783527 ) Feel free to open
new bugs and make them depend on it. I replied in more details to some
of your specific points in the text below.

I also agree with you about navigability. It is currently very poor. I
often have problem to go back from a js method to the related js object.
The standard breadcrumbs are not useful for that, so several part added
a second level of breadcrumbs to fix this. This is a temporary fix and
we want to completely rework the navigability of the web site in the
next months.

Thank you for your help

--
Jean-Yves Perrier

On 26/09/2012 13:06, Anders Holb ll wrote:

I'm not convinced by this one. At least not for the moment. I would like
to see the other speed improvements first (especially as these will
drastically lower the amount of connection to open).
We have a bug (bug 671794) filled for this one, it is on hold for the
moment.
Yes, this one is a big problem. I have filled bug 783534 and bug 783527
about these. It kills us outside the US.
We plan to have our own search in the future, we will remove the script
at that point.
That's a possibility, I don't know how often it is changed. Anyway,
having an Expires time further away than 15 minutes is a must be (for
primed cache).
Yes, that's something that will help the perception of speed. I don't
think we have a bug opened for this one.
Can we be more specific? That way we can fill precise bugs :-) We
shouldn't load JS needed only by editors outside the $edit pages (we
have already fixed some).
We plan a redesign of the theme, so the FOUC effect should be taken care
on the new theme.
The navigation is a catastrophe right now and is, with performance,
among the top priority for the redesign. I often got search after a
search, not able to navigate away, in a sensible way, from the page I found.
The editorial tags are in the progress of going away, we have another
system now. We just don't had the time to remove the existing ones.

I proposed to redesign the tag pages to be more useful: bug 777312

We have blocked their indexing by Google, but it will take some time
until their will be de-indexed.

We changed the title of our pages to " | MDN", but this change has not
yet propagated to the whole Google cache, that's why you see some
incoherence here.

- Obvious spam and junk content (e.g. /en-US/docs/aaaaaa), as well as
all the "... (External)"-pages should be completely deleted.

Yes, I completely agree. Deleting them is cumbersome now.

In fact we need both. We need the pure quick reference info to get
quickly the information that we already knew but forgot, and a more
verbose text for the first time we encounter the info. The audience is
both the seasoned developer and the more beginner one (but not complete
beginner) discovering new concepts.

Yes, I agree, most of these banners must be removed and the info
positioned elsewhere in the page.
We now have the possibility to remove the TOC on a page basis. So if the
topic driver does agree, this can be done know. (And I agree that "tags"
and "files" are completely useless)

Thanks again for the comments!
--
JYP

I didn't feel comfortable opening specific bugs as an outsider. But I'll
look around starting with the all bugs you mention. Thanks for the pointers.

But one thing I forgot to mention was that all doc pages (that should be
pre-generated as static files), should also have a far-future-expires
header, and use some variation of the self-updating scripts method
(though that presented in the context of JavaScript files). The update
check could perhaps piggyback on the login-check.
http://www.stevesouders.com/blog/2012/05/22/self-updating-scripts/
Or put an version number in the urls and remove them via the history api
Or use the application cache, i.e. create a manifest file for each
section (although the manifest doesn't seem to include a timestamp for
each file, so you are able to indicate what files should be refreshed)
or each file.

Then you should try the addon :)

I don't see how that is related. My comment was that the google api is
included on every page (and referenced from the mdn-min.js) even though
it is only used on the search page, so it could just be removed without
affecting the search.

It is so small (when the license blocks and the JavaScript is removed
and replaced with a css-transtion) that it should be in-lined. It could
be kept on the server side and refreshed e.g. once a day.

A quick search found http://pygments.org/ that looks usable.

Well one way of looking at it, could be that if you disable JavaScript
for the site, the visible change seems to be
- syntax-highlighting stops (but that should happen serverside)
- menu doesn't animate (which is nice, but could be a css-transition)
- login doesn't work (persona load should be delayed until clicked)
- The Mozilla tab doesn't work (but should not use js, as mentioned)
So no JavaScript is not needed for the normal pages. A less aggressive
approch is to go through
https://github.com/mozilla/kuma/tree/master/media/js and .../mdn (which
I assume is what is merged into mdn-min.js and wiki-min.js) and figure
out why it is there. To me it seems wiki-min.js is for editing.

To remove a font-reference or replace it with an image, seems to be tiny
change that don't have a strong dependency on a complete redesign.

Yep. That was the main point of the mockup. But it doesn't seem as much
a design issue. It is more an issue of what the information architecture
should be. Are you going to create a hierarchy (which I think is the way
to go), are you going to try to make the tag-system useful (which I
don't believe in), or something else.

I don't think adding descriptions to the pages will make them useful.
For most topics there are already pages that describe them, so this
would duplicate that. And if you just made a tag point to the page
describing the topic (e.g. /tag/javascript gets its description from
/docs/JavaScript), then you have created the hierarchy as
/docs/JavaScript -> /tag/JavaScript -> (pages tagged with the javascript
tag)

When shown in the MDN site, the titles should not contain "| MDN".

Perhaps, but my feeling is that the longer text now isn't more helpful,
it is just longer. Shorter doesn't imply less helpful, but it might take
longer to write.

Is there any page where the TOC is helpful?

Thanks for your reply.
--
Anders

On 9/26/2012 12:17 PM, Anders Holb ll wrote:

I regularly use the TOC on pages. This might just be personal
preference. Of course, one of the reasons I use the TOC is because I
often cannot tell if a heading is a subheading of another heading. Maybe
this could be made more clear with heading design.

Anders: Thanks very much for your many detailed comments! They are very
much appreciated.

Mark Giffin

That's interesting. Maybe I'm just off base. But at least it probably
should not be left to the personal preference of the topic drivers.

You could try to find out by using the "Stylish"-addon to fix the
headings and hide the toc and see if it works for you. That is what I
have been using.

Does the analytics measure if the links in the TOC is being clicked?
Since they are local links it might not. But on the topic of tag-pages,
the logs can probably tell if anybody is clicking through from tag-pages
(or even to the tag-pages).
--
Anders

On 9/28/12 9:59 AM, Anders Holbøll wrote:
Maybe it could be a user setting. That's actually what MediaWiki does:
you can set whether it should display TOCs for articles with more than 3
headings, for your own account.

--
Janet Swisher <mailto:jREMOVEswis...@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
Technical Writer/Community Steward