Comments on: What would make MDC easier for you to use? http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/ Bits on the rampage: Eric Shepherd's blog. Wed, 01 Feb 2012 14:15:55 -0500 hourly 1 http://wordpress.org/?v=3.3.1 By: skierpage http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-88724 skierpage Wed, 08 Sep 2010 09:12:25 +0000 http://www.bitstampede.com/?p=1503#comment-88724 Andrew Sutherland at MoMo <a href="http://www.visophyte.org/blog/2010/09/07/documentation-for-complex-things-you-dont-basically-already-understand/" rel="nofollow">implemented the vision</a>! 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. Amazing. 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.

Amazing.

]]> By: sheppy http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84747 sheppy Tue, 09 Mar 2010 00:54:44 +0000 http://www.bitstampede.com/?p=1503#comment-84747 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 <b>preventing</b> localization. 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.

]]> By: Ptak82 http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84746 Ptak82 Mon, 08 Mar 2010 20:24:54 +0000 http://www.bitstampede.com/?p=1503#comment-84746 @LouCypher: I also want to back to MediaWiki! <b>Dekiwiki blocking Polish MDC localization.</b> @LouCypher: I also want to back to MediaWiki!

Dekiwiki blocking Polish MDC localization.

]]> By: LouCypher http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84728 LouCypher Sat, 27 Feb 2010 11:22:25 +0000 http://www.bitstampede.com/?p=1503#comment-84728 <blockquote>What would make MDC easier for you to use?</blockquote> Back to MediaWiki? :p

What would make MDC easier for you to use?

Back to MediaWiki? :p

]]> By: dria http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84686 dria Sat, 06 Feb 2010 23:12:00 +0000 http://www.bitstampede.com/?p=1503#comment-84686 Having some sort of barnstars system would be great :) Having some sort of barnstars system would be great :)

]]> By: Atul http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84669 Atul Wed, 03 Feb 2010 18:23:08 +0000 http://www.bitstampede.com/?p=1503#comment-84669 * 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. * 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.

]]> By: Elchi3 http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84667 Elchi3 Wed, 03 Feb 2010 15:27:29 +0000 http://www.bitstampede.com/?p=1503#comment-84667 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). Regards. 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).

Regards.

]]> By: skierpage http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84666 skierpage Wed, 03 Feb 2010 02:55:42 +0000 http://www.bitstampede.com/?p=1503#comment-84666 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". Regards. 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”.

Regards.

]]> By: sheppy http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84665 sheppy Tue, 02 Feb 2010 19:04:38 +0000 http://www.bitstampede.com/?p=1503#comment-84665 All you should need to do is simply: {{bug(515190)}} to display that link. All you should need to do is simply: {{bug(515190)}} to display that link.

]]> By: jlebar http://www.bitstampede.com/2010/01/28/what-would-make-mdc-easier-for-you-to-use/comment-page-1/#comment-84664 jlebar Tue, 02 Feb 2010 18:43:03 +0000 http://www.bitstampede.com/?p=1503#comment-84664 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 : <code> <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> </code> (I hope that came out right...) 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…)

]]>