Removing broken pages
John J. Barton
by some clever query/template/db operation?
For example, if the page:
https://developer.mozilla.org/en/XUL/Method/removeProgressListener
was removed, then we might find that a search engine would give a
different and more useful answer when we look for
"removeProgressListener". Specifically we might be lead to a different
MDC page where the object or interface is described.
I understand these pages have some automatic relation to a parent page
and the key content is included in that parent page. If we could exploit
this automatic relation one last time, then we could improve the
documentation system easily.
jjb
Colby Russell
> For example, if the page:
> https://developer.mozilla.org/en/XUL/Method/removeProgressListener
> was removed, then we might find that a search engine would give a
> different and more useful answer when we look for
> "removeProgressListener". Specifically we might be lead to a different
> MDC page where the object or interface is described.
Just fix the page.
--
Colby Russell
John J. Barton
I can't see a way to delete the page. If I delete all of the content
will the page be deleted? Or will someone just revert the change? Would
the contributors to MDC agree not to revert the change (assuming it
actually deleted the page), to see if we can get the search to work
properly?
Just to be clear, the page I want to be the documentation for
"removeProgressListener" is:
https://developer.mozilla.org/en/nsIWebProgress
but it does not show up in Web searches.
jjb
Sheppy
wrote:
> I can't see a way to delete the page. If I delete all of the content
> will the page be deleted? Or will someone just revert the change? Would
> the contributors to MDC agree not to revert the change (assuming it
> actually deleted the page), to see if we can get the search to work
> properly?
Please don't do that. What's wrong with the documentation on that
page?
As per the MDC how-to documentation on the site, if there's a page you
want deleted, leave the content intact and tag the page with "Junk".
However, I don't agree that this page should be deleted. If there's
something wrong with it, fix it, don't just delete it.
Eric Shepherd
Developer Documentation Lead
Mozilla Corporation
http://www.bitstampede.com/
John J. Barton
> On Nov 23, 10:56 am, "John J. Barton" <johnjbar...@johnjbarton.com>
> wrote:
>
>> I can't see a way to delete the page. If I delete all of the content
>> will the page be deleted? Or will someone just revert the change? Would
>> the contributors to MDC agree not to revert the change (assuming it
>> actually deleted the page), to see if we can get the search to work
>> properly?
>
> Please don't do that. What's wrong with the documentation on that
> page?
1. The method must be applied to an object. That object or even the fact
that there is an object is not mentioned.
2. The parent reference is incorrect.
3. The related methods and fields are not listed.
4. The information content on the page on the entire page is ten words
and three of those are in the method name.
>
> As per the MDC how-to documentation on the site, if there's a page you
> want deleted, leave the content intact and tag the page with "Junk".
>
> However, I don't agree that this page should be deleted. If there's
> something wrong with it, fix it, don't just delete it.
It is the existence of this page that is the bug. The content in the
unreferenced but great parent page at
https://developer.mozilla.org/en/nsIWebProgress is better than this
page. The page and all pages like it are noise. Removing all of them
would dramatically and instantly improve MDC. Please give up on this
pedantic and pointless approach, it does not work for us.
jjb
Mike Shaver
<johnj...@johnjbarton.com> wrote:
> It is the existence of this page that is the bug. The content in the
> unreferenced but great parent page at
> https://developer.mozilla.org/en/nsIWebProgress is better than this page.
> The page and all pages like it are noise. Removing all of them would
> dramatically and instantly improve MDC. Please give up on this pedantic and
> pointless approach, it does not work for us.
Would it suffice to simply hide them from search engines, since they
are mostly an implementation detail? That seems like something that
could be done systematically, without losing the maintenance win of
the templated transclusion.
When you say "remove the page", do you really mean "manually copy its
contents into all places that currently include it, and then remove
the page"?
Mike
John J Barton
> On Mon, Nov 23, 2009 at 12:20 PM, John J. Barton
> <johnj...@johnjbarton.com> wrote:
>> It is the existence of this page that is the bug. The content in the
>> unreferenced but great parent page at
>> https://developer.mozilla.org/en/nsIWebProgress is better than this page.
>> The page and all pages like it are noise. Removing all of them would
>> dramatically and instantly improve MDC. Please give up on this pedantic and
>> pointless approach, it does not work for us.
>
> Would it suffice to simply hide them from search engines, since they
> are mostly an implementation detail? That seems like something that
> could be done systematically, without losing the maintenance win of
> the templated transclusion.
I don't understand how the current solution is a maintenance win. If you
open https://developer.mozilla.org/en/nsIWebProgress and login to MDC,
then you can edit just removeProgressListener entry by hovering over the
title. Yes, its a bit obscure and the editor is a bit slow, but its not
slow enough to justify a whole page for one method.
>
> When you say "remove the page", do you really mean "manually copy its
> contents into all places that currently include it, and then remove
> the page"?
I mean "automatically copy its contents in the the place that it belongs
then remove the page". If the page is included more than one place then
the secondary places need links, and perhaps doing this automatically is
harder than manual. But I guess this is not the case, it's just one
inclusion.
jjb
Colby Russell
> I don't understand how the current solution is a maintenance win. If you
> open https://developer.mozilla.org/en/nsIWebProgress and login to MDC,
> then you can edit just removeProgressListener entry by hovering over the
> title. Yes, its a bit obscure and the editor is a bit slow, but its not
> slow enough to justify a whole page for one method.
The problem is that the nsIWebProgress page should also be transcluding
this one as well, but it doesn't. It's troublesome because the
nsIWebProgress page gives a (fuller) IDL-like definition of the method.
We could change it to transclude this page (as well as the respective
page for the other methods and properties), but the IDL-like definitions
contain more information, so we'd be reducing the usefulness there.
What should really happen is to do the transclusion, but to make the
text on the removeProgressListener page (and all other methods across
the XUL docs) to read more like the IDL-like definitions currently in
nsIWebProgress.
> I mean "automatically copy its contents in the the place that it belongs
> then remove the page". If the page is included more than one place then
> the secondary places need links, and perhaps doing this automatically is
> harder than manual. But I guess this is not the case, it's just one
> inclusion.
MediaWiki has the functionality to aggregate transcluding pages
automatically, but we lost this in the Deki move.
--
Colby Russell
John J Barton
> John J Barton wrote:
>> I don't understand how the current solution is a maintenance win. If
>> you open https://developer.mozilla.org/en/nsIWebProgress and login to
>> MDC, then you can edit just removeProgressListener entry by hovering
>> over the title. Yes, its a bit obscure and the editor is a bit slow,
>> but its not slow enough to justify a whole page for one method.
>
> The problem is that the nsIWebProgress page should also be transcluding
> this one as well, but it doesn't. It's troublesome because the
> nsIWebProgress page gives a (fuller) IDL-like definition of the method.
Yes, the nsIWebProgress page gives a fuller definition of the method.
But it is not a problem and it is not troublesome: it's just fine.
> We could change it to transclude this page (as well as the respective
> page for the other methods and properties), but the IDL-like definitions
> contain more information, so we'd be reducing the usefulness there.
Yes, the nsIWebProgress page is great, no need to change it.
>
> What should really happen is to do the transclusion, but to make the
> text on the removeProgressListener page (and all other methods across
> the XUL docs) to read more like the IDL-like definitions currently in
> nsIWebProgress.
Here we disagree. We don't need those other pages at all. They don't add
value, they distract us and the search engines. Just delete them.
>> I mean "automatically copy its contents in the the place that it
>> belongs then remove the page". If the page is included more than one
>> place then the secondary places need links, and perhaps doing this
>> automatically is harder than manual. But I guess this is not the case,
>> it's just one inclusion.
>
> MediaWiki has the functionality to aggregate transcluding pages
> automatically, but we lost this in the Deki move.
Luckily we don't need this functionality. The transclusion model is not
a good one anyway, as we can see by looking at the MDC pages that use it.
I use the MDC pages a lot, they are critical to my work. These pointless
leaf pages are very frustrating.
jjb
Colby Russell
> Luckily we don't need this functionality. The transclusion model is not
> a good one anyway, as we can see by looking at the MDC pages that use it.
MDC doesn't use transclusion *enough*. If you want to update something,
you have to change it in every place it occurs. That's no good.
--
Colby Russell
John J Barton
Where else is removeProgressListener used?
More generally, in what pages would a method call description be used
other than the page that describes the method calls for an object or
interface? To me, any other use is a bug: the use should refer to the
method call description in the object page by link.
jjb
Colby Russell
> More generally, in what pages would a method call description be used
> other than the page that describes the method calls for an object or
> interface?
Speaking generally, these are what the transclusions are used for and
exactly what I'm referring to. You remove the leaf pages and you break
the pages that transclude it.
> To me, any other use is a bug: the use should refer to the
> method call description in the object page by link.
Okay then, in that scenario, what are you linking to? To "refer to the
method call description in the object page by link", the link still has
to point to a page like this, transclusion or not, and your complaint is
entirely about the existence of such a page.
--
Colby Russell
John J Barton
> John J Barton wrote:
>> More generally, in what pages would a method call description be used
>> other than the page that describes the method calls for an object or
>> interface?
>
> Speaking generally, these are what the transclusions are used for and
> exactly what I'm referring to. You remove the leaf pages and you break
> the pages that transclude it.
But let's not speak generally. Let's be specific. What other pages
include removeProgessListener? Once we decide, "oh well none". Then we
can return to general ask: how many method description leaf pages like
removeProgressListener are included other places? Are these good
designs?. I think will be "very few" and "no". But let's be specific: do
you have examples?
I think transclusion bad period. It says the content of this page is
context free. That means the information in the page is close to zero
because the method name itself contains almost all of the information
for a method call that does not depend on context.
>
>> To me, any other use is a bug: the use should refer to the method call
>> description in the object page by link.
>
> Okay then, in that scenario, what are you linking to? To "refer to the
> method call description in the object page by link", the link still has
> to point to a page like this, transclusion or not, and your complaint is
> entirely about the existence of such a page.
>
Link to
https://developer.mozilla.org/en/NsIWebProgress#removeProgressListener
and place an anchor on the span with id removeProgressListener
jjb
John J Barton
> John J Barton wrote:
>> More generally, in what pages would a method call description be used
>> other than the page that describes the method calls for an object or
>> interface?
>
> Speaking generally, these are what the transclusions are used for and
> exactly what I'm referring to. You remove the leaf pages and you break
> the pages that transclude it.
Let me give you a different answer, in hopes you will see things from my
perspective.
Oh, fine, use transclusions. Just don't show them in the user interface
and don't let search engines see them.
As you describe it, transclusions are a workaround for a poor
technology. We can't express the idea that a few identical lines about
removeProgressListener are used in eight places in the documentation
unless we pull those lines out into a separate file and include it the
eight references. It does not follow that users should have to read the
documentation out of context. Let users see the eight places as results
from the search engine. Leave out the ninth (inclusion) result because
it is just confusing. And for sure avoid the case where the search only
shows the inclusion.
Just be clear, I made up the eight places here. I think in reality there
is only one place removeProgressListener is included and it does not
show up in searches.
jjb
John J Barton
https://developer.mozilla.org/en/XUL/Method/addTabsProgressListener
jjb
John J. Barton
> For example, if the page:
> https://developer.mozilla.org/en/XUL/Method/removeProgressListener
> was removed, then we might find that a search engine would give a
> different and more useful answer when we look for
> "removeProgressListener". Specifically we might be lead to a different
> MDC page where the object or interface is described.
Note that for some reason some leaf pages are slightly better simply by
having a title that includes the context of the leaf. For example,
searching for 'opener mdc', gives
https://developer.mozilla.org/en/DOM/window.opener
The title at least gives you a hint about the object.
Unfortunately the break crumb is wrong:
# Mozilla Developer Center
# DOM <<< *not* a page that refs window.opener, or even 'window'.
# window.opener << Ack, 'window' not listed
Moreover, the page that should benefit from transclusion,
https://developer.mozilla.org/en/XUL/window
does not list "opener".
And https://developer.mozilla.org/en/DOM/window does list opener but
does not include anything from the window.opener page.
Here is alternative suggestion to solve the particular MDC problem
above: block search engines on the leaf pages. This would instantly make
MDC more valuable. If I really want the leaf info, its only a click away.
jjb
Mike Shaver
<johnj...@johnjbarton.com> wrote:
> Here is alternative suggestion to solve the particular MDC problem above:
> block search engines on the leaf pages. This would instantly make MDC more
> valuable. If I really want the leaf info, its only a click away.
Isn't that what I suggested a week ago? I'm still in favour!
Sheppy, what do you think?
Mike
John J. Barton
> On Mon, Nov 23, 2009 at 12:20 PM, John J. Barton
> <johnj...@johnjbarton.com> wrote:
>> It is the existence of this page that is the bug. The content in the
>> unreferenced but great parent page at
>> https://developer.mozilla.org/en/nsIWebProgress is better than this page.
>> The page and all pages like it are noise. Removing all of them would
>> dramatically and instantly improve MDC. Please give up on this pedantic and
>> pointless approach, it does not work for us.
>
> Would it suffice to simply hide them from search engines, since they
> are mostly an implementation detail?
If this is what is possible, then yes this would be a great improvement.
jjb
Sheppy
> <johnjbar...@johnjbarton.com> wrote:
> > Here is alternative suggestion to solve the particular MDC problem above:
> > block search engines on the leaf pages. This would instantly make MDC more
> > valuable. If I really want the leaf info, its only a click away.
>
> Isn't that what I suggested a week ago? I'm still in favour!
I have no idea if that's possible, and I'm still not sure I understand
the complaint here. Wouldn't it make more sense to, you know, fix the
articles that people consider unhelpful instead of working around it
by blocking those pages from showing up in searches?
Mike Shaver
> I have no idea if that's possible, and I'm still not sure I understand
> the complaint here. Wouldn't it make more sense to, you know, fix the
> articles that people consider unhelpful instead of working around it
> by blocking those pages from showing up in searches?
The problem is that the component pages for individual members are
showing up higher than the more useful pages with context. The
fragment pages are an implementation detail that we should hide as
much as possible. (I don't believe we have any links to the fragment
pages, for example, but I may not be searching MDC correctly.)
Mike
Sheppy
> The problem is that the component pages for individual members are
> showing up higher than the more useful pages with context. The
> fragment pages are an implementation detail that we should hide as
> much as possible. (I don't believe we have any links to the fragment
> pages, for example, but I may not be searching MDC correctly.)
Are they just an implementation detail? Is there really any reason at
all to have these in separate pages? If not, why not move that content
into the body of the main page instead of embedding content from a
separate page like we do now?
Maybe there is a good reason for why it's done the way it is now, but
I don't know what it is. If Dria is watching this thread, perhaps she
could comment on why it's done this way.
John J. Barton
> On Nov 30, 12:27 am, Mike Shaver <mike.sha...@gmail.com> wrote:
>
>> <johnjbar...@johnjbarton.com> wrote:
>>> Here is alternative suggestion to solve the particular MDC problem above:
>>> block search engines on the leaf pages. This would instantly make MDC more
>>> valuable. If I really want the leaf info, its only a click away.
>> Isn't that what I suggested a week ago? I'm still in favour!
>
> I have no idea if that's possible, and I'm still not sure I understand
> the complaint here. Wouldn't it make more sense to, you know, fix the
> articles that people consider unhelpful instead of working around it
> by blocking those pages from showing up in searches?
Let me try again:
A search for 'addTabsProgressListener' lead to
https://developer.mozilla.org/en/XUL/Method/addTabsProgressListener
This page should not be fixed because it should not exist in the first
place. The three sentences of documentation here are not useful because
we don't have any context. We don't know what object the method applies
to. We don't know what other methods the work together with this method.
If we supply this context, then we have duplicated the page that
should be the parent of this page, if it were not so broken.
Or another way: if we fix this page we need to:
1) Correct the breadcrumbs --> Can't edit these!
2) Correct the back reference --> Unintelligible markup used!
3) Add the link to the object, --> Would change the page title!
4) Add the related methods --> Makes the page a duplicate.
I hope this makes the issues clearer.
jjb
Sheppy
wrote:
> Sheppy wrote:
> > On Nov 30, 12:27 am, Mike Shaver <mike.sha...@gmail.com> wrote:
>
> >> <johnjbar...@johnjbarton.com> wrote:
> >>> Here is alternative suggestion to solve the particular MDC problem above:
> >>> block search engines on the leaf pages. This would instantly make MDC more
> >>> valuable. If I really want the leaf info, its only a click away.
> >> Isn't that what I suggested a week ago? I'm still in favour!
>
> > I have no idea if that's possible, and I'm still not sure I understand
> > the complaint here. Wouldn't it make more sense to, you know, fix the
> > articles that people consider unhelpful instead of working around it
> > by blocking those pages from showing up in searches?
>
> Let me try again:
>
> This page should not be fixed because it should not exist in the first
> place. The three sentences of documentation here are not useful because
> we don't have any context. We don't know what object the method applies
> to. We don't know what other methods the work together with this method.
> If we supply this context, then we have duplicated the page that
> should be the parent of this page, if it were not so broken.
>
> Or another way: if we fix this page we need to:
> 1) Correct the breadcrumbs --> Can't edit these!
> 2) Correct the back reference --> Unintelligible markup used!
> 3) Add the link to the object, --> Would change the page title!
> 4) Add the related methods --> Makes the page a duplicate.
>
> I hope this makes the issues clearer.
This returns me to the question: is there actually any reason to keep
these little pages around at all? Why not just merge them all back
into the main article... I don't think they're actually embedded from
anywhere else anyway. If we adjust the formatting of the parent page
so that there's an anchor for each function, property, etc, we can
change links to go to the appropriate section on the parent page and
get rid of the little leaf pages.
John J. Barton
> On Nov 30, 11:06 am, "John J. Barton" <johnjbar...@johnjbarton.com>
> wrote:
>> Sheppy wrote:
> This returns me to the question: is there actually any reason to keep
> these little pages around at all? Why not just merge them all back
> into the main article... I don't think they're actually embedded from
> anywhere else anyway. If we adjust the formatting of the parent page
> so that there's an anchor for each function, property, etc, we can
> change links to go to the appropriate section on the parent page and
> get rid of the little leaf pages.
+1
jjb
Sheppy
So -- who has the time to do that work?
Nickolay Ponomarev
The idea was to avoid duplication of content in cases where an
attribute/method/property is shared across multiple elements. I don't
believe such sharing is common, given that the common-to-all-elements
attributes etc. are not included on each element's page.
Old discussion:
http://groups.google.com/group/mozilla.dev.mdc/browse_frm/thread/33446a9f57db6583/b94061a8015f6e5f?tvc=1#b94061a8015f6e5f
Can you "use a bot to flatten the pages" (to quote Mike from 2006 :) in
deki?
Nickolay
Sheppy
> On Mon, Nov 30, 2009 at 11:04 PM, John J. Barton <
>
>
>
> johnjbar...@johnjbarton.com> wrote:
> > Sheppy wrote:
>
> >> On Nov 30, 11:06 am, "John J. Barton" <johnjbar...@johnjbarton.com>
> >> wrote:
>
> >>> Sheppy wrote:
>
> >> ...
>
> > This returns me to the question: is there actually any reason to keep
> >> these little pages around at all? Why not just merge them all back
> >> into the main article... I don't think they're actually embedded from
> >> anywhere else anyway. If we adjust the formatting of the parent page
> >> so that there's an anchor for each function, property, etc, we can
> >> change links to go to the appropriate section on the parent page and
> >> get rid of the little leaf pages.
>
> The idea was to avoid duplication of content in cases where an
> attribute/method/property is shared across multiple elements. I don't
> believe such sharing is common, given that the common-to-all-elements
> attributes etc. are not included on each element's page.
>
>
> Can you "use a bot to flatten the pages" (to quote Mike from 2006 :) in
> deki?
I bet we can, actually. Deki is crazy scriptable. Anyone have time to
tackle this job? I'd love to see us do this. Although we might want to
finish the discussion in another thread about possible reformatting of
the DOM reference content first.
Sheppy
Colby Russell
> I bet we can, actually. Deki is crazy scriptable. Anyone have time to
> tackle this job? I'd love to see us do this. Although we might want to
> finish the discussion in another thread about possible reformatting of
> the DOM reference content first.
>
> Sheppy
Except Deki fails on the "pages that link here" front, since it still
doesn't list transclusions. Finding pages that reference any given page
to be flattened in an automated way would only be possible with a
database dump and running a custom script over the MDC corpus. As far as
I can tell.
--
Colby Russell
Sheppy
I'll talk to the guys at MindTouch about that.
Sheppy
Colby Russell
> But let's not speak generally. Let's be specific. What other pages
> include removeProgessListener?
Hard to tell, since Deki doesn't have this feature.
> I think transclusion bad period. It says the content of this page is
> context free. That means the information in the page is close to zero
> because the method name itself contains almost all of the information
> for a method call that does not depend on context.
Actually, I do agree with this. I made my previous comments under the
impression that there were quite a few objects that did have shared
interfaces along the lines of DOM, but there aren't very many, some
shared attributes/properties/methods are context-sensitive. On the other
hand, we have attributes like tabindex.
--
Colby Russell
Sheppy
OK, let's just see if we can start changing from using transclusion to
just having the content in place. Transclusion causes more problems
than it solves.
Sheppy
OK, your MDC-fork concept is not going to fly. Don't fork the content.
Fix it in place. Forking the content is only going to make the problem
worse. Unless someone can come up with an incredibly, remarkably good
reason why forking the content is a good idea, I'm deleting this fork
you created today.