Jan 282010

In a little over a week, I’m going to be having a meeting with some folks from MindTouch to discuss ideas for features that would make their software easier and better for collaborative documentation projects like ours.

Obviously, this is very exciting, and I’d like to be sure to bring lots of good ideas along with me when I go.

So, if you have thoughts on “big picture” ideas for improvements that would make the Mozilla Developer Center easier and better for collaborative documentation work, please drop me an email, or comment here, and I’ll sort through the ideas and bring them with me.

Update: “Performance” is not a “big picture” feature in the context of this request for ideas. Obviously there are performance issues. I’m talking about the actual creation, organization, and management of the documentation content itself here.

 Posted by at 11:48 AM

  39 Responses to “What would make MDC easier for you to use?”

  1. Performance. Every time I have to wait for a page to load or save is an interruption in my flow, and typically I’m editing docs as something I want to do quickly — before I forget! — and then get back to what I want. We need to look at the caching rules, the assets we load, and profile the crap out of the common (page load, editor load, editor save, editor actions, search) activities, I think.

  2. – Faster page loads.

    – An obvious way to edit a page in a plain textarea (so I can use an external editor). I do not edit pages frequently, which means being able to use an external editor is easier for me than figuring out the quirks of the wysiwyg editor. Apologies if that one is already there: I did not have a thorough look.

    – Please do not change the URLs again. I still have a lot of things in my urlbar history that simply do not work anymore and redirect to nonsensical or empty pages. I frequently use urlbar history to get at useful pages, because it’s faster than using the search and I haven’t had much luck with search in the past (this may have improved, I should try it again).

  3. – Faster page loads.

    – Get rid of the weird “Service Unavailable” error I keep seeing about 50% of the time I try to move from 1 MDC page to another.

    – Make the search work. Compare: https://developer.mozilla.org/Special:Search?search=forEach&type=fulltext&go=Search and http://www.google.com/search?hl=en&q=site%3Adeveloper.mozilla.org+forEach . All the pages on the second link are relevant, that I can see quickly, and on the first page, there’s a bunch of stuff that I have no idea how it ever got in there (eg. ” E4X for templating” or “myrules.mk”). Making the in-MDC search just do a google search would work for me. Right now it’s too tempting to use the in-page search functionality, and end up groaning when I see the non-useful results and then use the bookmark keyword I have for that google search instead.

  4. Performance is the major concern. And it’s even worse from Europe than from the US… So a way to set up _easily_ local mirrors for individuals or companies using moz would be an awesome plus for all of us. If such a mirroring system becomes available, I’ll install one immediately on my company’s network.

  5. OK, I obviously didn’t phrase this right. Performance is obvious. I’m talking about actual features here. What would make actually creating, organizing, and managing the content easier?

  6. Search is a primary feature, because MDC is a programmer reference database. It has also to have a good index somewhere as any good reference tool. Like mzz, I use to bookmark MDC pages to make my search easier and faster (actual MDC search is almost useless).

  7. My main concerns that I stumble over most of the time when I look are tags and search not working localized. I’m not sure if that ever made it to being a feature, but it’s surely stopping me in using either in using MDC.

    Other problems I have are not related to tikiwiki at all, either. Given that search doesn’t work, I try navigating, and if I don’t know that something in my url bar has it, the content is a *lot* of clicks away. That seems to be somewhat of a styleguide of mdc pages, making them as small as possible. Doesn’t help me to get around.

  8. Just starting with fixing missing interface docs would be nice. If at any point any page links to an nsI* that doesn’t exist, a big red flag should be thrown up to either find and generate the documentation for it or yell at someone to fix it. MDC is plagued with missing pages in many places.

  9. Search seems to be greatly improved since last time I experimented with it on MDC. That’s great! I’ll try to reproduce some of the bugs I saw in the past, but it seem greatly improved.

    We have to edit docs and update them a lot for the l10n community, especially as we try to eliminate all references to things like CVS and out-dated technologies. It’s sometimes frustrating to see those way outdated pages show up in search results when we’ve done a lot of work to update those pages. But, I suspect that we just have to manually edit each of these pages to either delete them, update them, and then redirect them to the newest content. Does that seem like the best way to update our content?

    I think there is some long-standing hope by many of our community members that MDC will migrate back to Media Wiki. But, I don’t think that is a realistic complaint at this stage. So, anything that can be done to make the wiki styles and markups work seamlessly would probably be appreciated by those who long for Media Wiki.

    I personally find the tagging somewhat confusing because when I click on a tag at the bottom, it gives me a long laundry list of pages with not much meta data about the pages or any info really.

    I also like the editing tool on Mind Touch’s Deki Wiki, but I realize that some might complain that it feels too much like a word processing editor and not traditional wiki style. This relates to the second point, but again might not be totally relevant if both wikis can read each style and mark up without any conflict.

  10. Echoing Axel: searching in any double-byte character set fails.


    I realize mutli-lingual search is not trivial, but for a wiki, it’s pretty much mandatory. Imagine not being able to search in English for “Addon”.

  11. Sorry- I should say that double-byte search needs to be refined so that the user does not have to select the language in order for search to work.

  12. I’m waiting to see bugs linked here https://bugzilla.mozilla.org/show_bug.cgi?id=519025 fixed. I won’t try editing anything in MDC again before that – I don’t want to see that nightmare again…
    Many/most of the bugs listed there are MindTouch bugs, so you have something to talk about with them.

    When I have to use MDC to find out about something (or many things at once), then the following problem makes me feel like I’d want to kill someone:
    -search not working (I don’t want Chinese results when using English MDC, or English, when using a localized MDC)

  13. There is one thing which would make MDC easier for me to use, and I know I won’t get it, so why should I mention it? OK, I will: going back to good old Wikimedia software, preferably with my favourite no-nonsense CologneBlue skin as one of the available options. All these new-fangled colours get in the way of understanding what is written; and having identical software powering all Wikipedia sites as well as the Mozillazine knowledge base and the MozillaWiki (and, it used to be, the MDC too), to name only a few (and, for Gen Kanai, using UTF-8 throughout, so no surprises with strange characters), eases the learning curve, since nothing of what was learn on the one site will have to be unlearnt on the next.

  14. Being able to preview things (including the {{}} things being applied) would be the most useful thing, I think. As it is I still have to make guesses then save and hope it’s right.

    It would be nice if I could get to the relevant templates (in my case, usually the interface ones) easier when I start a new article; as it is I have to find random bits in existing pages, and they’re all different and I have no idea which one I should be copying from.

    Being able to save from source view would be nice (I assume it would have to keep a wysiwyg view in the background to check things etc. though), as would being able to choose to default to source view. Yes, I realize you don’t like it, but that’s because you need to do things higher volume ;)

    As a user and not an editor, being able to download the wiki in some way (or select sections thereof) would be useful for when online access is unavailable.

  15. Edit the page in plain text (wiki style).

  16. Please let Firefox autocomplete my credentials on the login page.

  17. Almost everytime i use MDC (every day), i regret there is not an easy way to add comments at the bottom of the page with remarks and snippets from developers to developers. I’m not talking about editing the ‘official’ content of the page, but just something easy to say “When i use this method/component/interface, this tip is useful …” or “Be careful, this does not work in version xxx”.

    I also use a lot information from the PHP site (http://php.net/) and they use this commenting method. I find this extremely useful.

  18. Live search suggestions – Google Suggests, style – would be great for those times when you’ve got a rough idea what you’re looking for, but could do with some suggestions as to how to hone your search.

    I often use MDC as a reference for XUL elements or JS properties, and anything that makes it faster to get to the main reference page (rather than something in the XUL tutorial, for example) would help. Perhaps namespaces or some other sort of prefix would also make it easier to find the specific thing you’re looking for – xul:, html:, js:, svg: and so on, such that searching for “xul:button” would take you straight to the reference for xul buttons.

  19. Cool!

    I’m happy we do have support from MindTouch people to improve the wiki.

    There’s a list of bugs that is currently blocking Aviary.pl from working on MDC. I believe it affects more localizations: https://bugzilla.mozilla.org/show_bug.cgi?id=519025

  20. Lots of good suggestions here. I’m adding them to my list of things to bring up when I meet with them.

  21. Why are you asking? We’ve already suggested many concrete improvements for mdc. No substantive change results.

    Fewer, longer pages. Fewer fancy features, more straightforward design, faster loads. xulplanent content. Focus on mozilla API, not generic web api. More examples. Remove tags (their implementation is beyond stupid). Use external search engine.


  22. John, most of the stuff you said has nothing to do with the implementation of the software, but about the content itself. And we’ve already agreed that we both think that fewer, larger pages instead of all the broken up stuff would be better — it’s just a matter of not having anyone who has the time to do that work right now.

    This question is about the features of the software, not about how we use it.

  23. @sheppy: “it’s just a matter of not having anyone who has the time to do that work right now.”

    Back in days where MDC run on MediaWiki, we had plenty of community members editing MDC. Now they are all gone – all because of the migration to DekiWiki. Maybe it’s time to return to MediaWiki??

  24. Two things:
    1) A dump of all data. Something like this: http://download.wikimedia.org/
    2) Public APIs. I think DekiWiki already supports something like this: http://www.programmableweb.com/api/mindtouch-deki-wiki

    Both of these would allow the community to come up with novel and surprising ways of using MDC.

  25. Hey Sheppy,

    Echoing plain-text edit. I don’t mean to keep beating a still living horse, but I really like MediaWiki syntax and find the rich text editor pretty cumbersome.

    One feature I’d like to have, and don’t really have any suggestion on *how* to implement it, is offline support. I’d love to have a disc with a full copy of MDC on it that I could install on my computer. I was traveling today and really wished I had access. It could also be useful for people with slow internet connections.

  26. The WYSIWYG editor is really frustrating. Sometimes formatting looks OK when I’m editing, but when I view the saved page it’s different, e.g., there’s more vertical space than I asked for in between headings and the text that follows or in between list items. I’ll look at the source and see extra paragraphs or list items have been inserted. Sometimes I click the button to remove formatting from selected text and nothing happens. So I click other buttons that look related and usually resort to deleting my text and starting over. I’ll type in a code snippet but then can’t figure out how to close it and carry on with normal text. Similarly with lists. Inserting links is hard. I either have to browse through the entire MDC hierarchy using that tiny, slow-loading, modal window, or go find the precise URL elsewhere in MDC I want to link to as paste it in that modal window. When I start typing in that window it gives me suggestions from other localizations of MDC. I still haven’t figured out how to link to an anchor on the same page without using the full URL. Often I get it wrong, but I don’t know until I save the page because there’s no preview. Creating tables takes many clicks and many adjustments to set proper borders, BG colors, widths, etc., always ending in adjustments at the HTML level. After I click the Save button, it’s usually pretty slow loading the saved page.

    I understand that a motivation for WYSIWYG might have been to lower the barrier of entry, but if I didn’t really care about the projects I’m working on, I would have given up editing MDC long ago. When I go back to editing wikimo, it’s a breath of fresh air. It doesn’t get in my way.

    When comparing versions in history, the diffs are shown in the context of the entire page. That’s nice, but it means I have to strain my eyes to see where the changes are, especially for small changes in big pages. A simple diff up top in addition to the context below would be great. Also, formatting changes are not shown. I’ll often see a revision that says “No wording changes”, and I have no idea why the revision was made and to what.

    Search is bad. I always end up site-searching with Google.

  27. devmo feels disconnected from the web.
    The way sample code works feels too rigid and inflexible, especially for read-write web technologies. Many pages have lots of sample code on them (great), but it’s static fragments sitting on the page. There’s often no way to get to the actual program containing the code, if there ever was one. Every piece of code should have a link to the working program from which it’s extracted; better yet, every piece of code should just be extracted from sample code at page generation, instead of copy and paste. If the sample code is scripting or CSS code, I should be able to click and run the program it came from immediately. Give me a sandbox where I can make changes to the sample code and see the results immediately.

    devmo feels disconnected from the Mozilla source code.
    developer.mediawiki should link to the source code for the feature described in all of the lxr, mxr, hg, and David Humphreys wonder tool systems. E.g. https://developer.mozilla.org/en/nsString , link me to the damn source code for it.

    I seem to recall you mentioned some the dev.mediawiki code is generated from doc comments in the source code. Like interpolating sample code fragments, that should happen in a page generation step, not statically. I think you said it would be too difficult to seek code review for every doc comment change to source, but surely all the Hydra smarts and Mozilla build machinery can verify the assertion “This check-in is solely a change to comments.” It makes no sense to maintain documentation in source code and overlapping documentation in devmo, build one from the other.

    I saw a red “function ‘InterWiki’ failed” error. Googling for this gave 3700 results.

    I’m still getting results for languages other than English when I search from the main box, though it seems better than before — they’re showing up on the second page of results.

    The “in en” stuff on the end of search results is noise, the search results snippet needs highlighting of the search term, and the formatting of the “Previous 35 Next 35
    Search query used by API ” at the end of the page is poor.

    “Pages tagged with HTML:Canvas” lists a bunch of languages besides English.

    It’s not MediaWiki.

  28. James:

    1. Working on ways to get devmo available offline; I have no idea when or how that’ll be done yet. There is infrastructure there to export articles to PDF though, which is a start at least.

    2. Yes, the API is available and can be used to do a lot of very cool stuff.


    The sample code is static the way it is because of leftovers from MediaWiki. We’re using more and more dynamic samples as time goes by. This isn’t a matter of features for the wiki software, but how we’re using it. There simply aren’t enough people contributing new samples right now.

    We already have links to the source code for stuff; if you see places where links should be but aren’t, add them.

    We don’t automatically generate any of our documentation at this time. Auto-documentation tools aren’t adequate for the quality we want to achieve, especially given that we can’t freely edit the comments in the code without going through the same checkin process that true code changes require. That, too, has nothing to do with the wiki software itself.

    The “function InterWiki failed” errors are easy to fix, someone just needs to work on it. They’re a result of an error converting from MediaWiki. All that needs to be done to fix them is to replace “mediawiki.interwiki” with “interwiki” everywhere they occur. This is a time-consuming job that I don’t have time for; anyone that sees this error should fix it. I do when I spot them while working on other things.

    The search and tag pages showing stuff in the wrong languages is an annoying bug and I keep hassling the MindTouch guys about it. I will continue to do so.

    Let me be clear: we will NOT be changing back to MediaWiki, and every time someone brings up the idea, I die a little inside. Please stop. :)

  29. I don’t think the issue is so much whether we’re using MediaWiki per se, but whether we’re using a Wiki with sane plain-text syntax. For instance, here’s the code I used to add a link to a bug at https://developer.mozilla.org/en/DOM/window.onhashchange :

    <li><a href="https://bugzilla.mozilla.org/show_bug.cgi?id=515190" title="https://bugzilla.mozilla.org/show_bug.cgi?id=515190" class="external">Bug 515190</a> - <span class="bz_default_hidden" id="summary_alias_container" style="display: inline;"><span id="short_desc_nonedit_display">Hashchange event should be dispatched synchronously</span></span></li>

    (I hope that came out right…)

  30. All you should need to do is simply: {{bug(515190)}} to display that link.

  31. 1. You’re saying there is a way to say “Embed lines 13-18 of samples/C/HelloWorld.cpp, highlighting=c++” and it provides a link to the actual code and you can run it in the blue-sky vision way I described? Wow. I don’t see such a template! I just see lots of fragments of code inline, e.g. Building_an_Extension ; I have no idea how you manage them all and verify they continue to work.

    1a. How do I find which pages have embedded code in them, or which include complete samples? E.g. NSPR_API_Reference/Introduction_to_NSPR#NSPR_Sample_Code says it presents two samples, but I couldn’t find them.
    1b. Template:Embed_text should add the page to Category:Embedded files”, or if you specify a language for syntax highlighting, the subcategory:Embedded code snippets /javascript.
    1c. What’s an example of an area where the sample code is integrated approaching the way I described?
    1d. I guess I’m not explaining my vision in an inspiring way. Take say https://developer.mozilla.org/en/CSS3_Columns . It presents CSS code snippets, then repeats them inline so you can see the effect. This is prone to error (two copies to keep in sync, one full of HTML escapes), and non-interactive. Imagine if the CSS was in a textarea or Bespin and you could modify it and immediately see the sample text change. Imagine similar for JavaScript, XUL, canvas. SVG…

    2. Source code: Ahh, I see various Template:Source*, I’ve never noticed them browsing MDC. There should be one template for source that generates links to all of hg/lxr/mxr/DXR David-Humphrey-wonder-tool.

    3. I’m confused, do you use doc generation tools at all? If you do, how do you keep MDC and Mozilla source in sync?
    3a. If you do use doc tools, DevMo pages should indicate when parts of them were generated from source code.

    In writing this, I was stymied trying to find examples of these facilities in MDC. Is there a way to see what pages use a template? “Pages that link to Template:Source” or Template:Embed_text” doesn’t seem to show which pages invoke a template.

    The MDC Help link takes you to a page with an “Editing content” section, but that doesn’t link to How to Help or Getting Started (which are very useful!).

    Next time you ask for suggestions, you should link to “Why MDC uses MindTouch” and any other vision documents to encourage better (or less :-) ) debate.

    I’m sorry this is an incoherent mix of glitches, questions, and big picture. Your blog software wouldn’t let me link to MDC pages, it accused me of being “a bit spammy”.


  32. Ideas about l10n in short (time is money):

    -Create a list of the articles that are most in need of being translated for each language (sorted by hits).
    -Display the progress made by each localization team.
    -Compare article’s modification date against the modification date of the original English article and mark old articles.

    -Improve the search engine.
    -Readers should have the ability to rate articles to improve quality.
    -Mark not existing talk pages (red link color).


  33. * Flickr-like editing-in-place would be my most desired feature, personally. When I first read that MDC would be WYSIWYG, I interpreted that to mean that when I saw a typo, I could just click on it and edit the typo in-place, the same way I can fix a typo in a Flickr photo description. Instead, my locus of attention (the word that needs changing) disappears as I’m taken to a completely new page which loads the previous page in an editor and I have to re-find my original locus of attention. Combined with the fact that the new MDC is actually slower than the old MDC, this has actually resulted in me contributing less to MDC than I did when it was a MediaWiki install.

    * As far as improving MDC content goes, I think that it’s actually mostly a social issue rather than a technological one: contributors or outstanding articles are never recognized, for instance. Wikipedia features like “Featured Articles” and more social ones like Barnstars could be really nice here, as well as adding things to the front page that make MDC feel more like a community and less like a static documentation resource like MSDN could go a long way. Adding metrics information that makes it easier for others to figure out where they can contribute to make the biggest difference would also be awesome, e.g. a list of most-requested-for articles or most-linked-to articles that don’t exist yet.

    * A very simple “fallback” for the blank nsI* pages would be to automatically insert the IDL file for the interface from MXR in the page. In fact, providing a link to this even if there is content in the page would be really useful, because it’s a manual task I almost always have to do, and that newcomers who don’t know about MXR would be completely lost without.

    * To make it easier for others to contribute to making MDC easier to use, it might be nice to highlight a “MDC Addons” page or something, if one doesn’t already exist, which could contain Jetpacks/Addons/GreaseMonkey scripts that add cool functionality.

  34. Having some sort of barnstars system would be great :)

  35. What would make MDC easier for you to use?

    Back to MediaWiki? :p

  36. @LouCypher: I also want to back to MediaWiki!

    Dekiwiki blocking Polish MDC localization.

  37. Deki isn’t blocking the localization; you guys just don’t want to learn and come up with new ways to do things. None of the things that are commonly complained about area really honestly preventing localization.

  38. Andrew Sutherland at MoMo implemented the vision!
    Live code samples in page: yes.
    Double-click to edit code snippet in Bespin: yes.
    Immediately see the effect of your edits: yes.
    Unobtrusively include entire sample program on page, not just fragment: yes.
    Auto-link keywords in code fragments to documentation tooltips: yes.