What could be better about MDC?
Eric Shepherd
better documentation posted is obviously a key component to that,
there's another area of improvement that needs to be addressed.
The site itself could use a redesign and new features. What kinds of
changes would you like to see to how the developer.mozilla.org site works?
I'm working on building a list of ideas for changes to improve
productivity for writers, encourage contributions, and make it easier to
find information.
If you've ever been stymied in getting something done with MDC, please
let me know what you'd do to fix it!
--
Eric Shepherd
Developer Documentation Lead
Mozilla Corporation
http://www.bitstampede.com
Benjamin Smedberg
> If you've ever been stymied in getting something done with MDC, please
> let me know what you'd do to fix it!
The bit I miss most often is a ready-access table of contents or tree
navigation system for reference material. I know I've missed this especially
in the JS documentation as well as NSPR and DOM references. On some sites
this takes the form of a sidebar frame or a popup TOC... I am hoping that
the RDF data system for breadcrumbs could be put to good use to
auto-generate TOCs.
--BDS
Nickolay Ponomarev
> The site itself could use a redesign and new features. What kinds of
> changes would you like to see to how the developer.mozilla.org site works?
>
Our Nutch-based search is much better than previous solutions, but it
has a few bugs (filed) that make me prefer site-specific google
queries to it:
- lack of useful snippets in search results and indexing the whole
wiki page instead of just content.
- inability to refine searches easily
- noticeable amount of unrelated results for certain queries due to
non-wiki pages being indexed.
The next thing I miss as an MDC user is better docs, really. This
includes docs _content_ (e.g. parts of the DOM reference could use
improvements) and documentation structure; sometimes it's hard to find
something I need, even though I know where to look. One-page TOC for
hierarchical references would be indeed very useful, as bsmedberg
noted.
As an editor, the "new user" spam on recent changes is very painful,
as well as occasional slow response times.
Nickolay
Brett Zamir
actually. But besides "more and better" documentation, I think we'd all
probably like to see the existing documentation updated where necessary
and filled out. Too many orange links around in core documentation, even
though they are often usually not so vital, as well as open questions on
the article pages which need some experienced developer to answer.
I mentioned before the idea of getting Rapid Application Development
with Mozilla on site (I'm still awaiting a reply from Prentice Hall), as
that was an excellent resource (wonderfully technical, but also as a
result in some places a bit obscure), but I wonder what could be done
about "Creating Applications With Mozilla", as that was a bit more
friendly to beginners, but also a bit obscure in parts. Are the authors
still around here? It does seem like the Open Publication License that
these books are published under could be compatible with Sharealike
given that a wiki also tracks contributors, but I'm not a legal expert.
Lastly, the biggest missing link, in my opinion, is good documentation
of the usage of XPCOM components. Of course there are many, but I think
of http://php.net/manual/en as a good example of covering quite a large
number of functions in a pretty thorough but easy-to-read way. That as
well as tips on how to use libraries, etc. to make access to XPCOM
components easier. I think we'd see a lot more powerful and creative
extensions and apps if developers could have access to
programming-for-the-masses documentation on these powerful components. I
don't simply mean tutorials here, but a less terse reference manual.
I know these are more content issues, but, as far as I'm concerned, the
design is good as it is.
Two unrelated questions:
1) I asked about whether we could add a link to the main page for
http://developer.mozilla.org/en/docs/XQuery ?
2) Can anyone with the know-how clarify the status of LiveConnect? It is
mentioned at http://developer.mozilla.org/en/docs/LiveConnect that it
may be removed from Mozilla 2.0? LiveConnect is powerful and intuitive
if you need to use Java (with the exception of try-catch blocks not
always catching errors as they are supposed to).
Brett
John J. Barton
> One of my goals is to make MDC more useful. While getting more and
> better documentation posted is obviously a key component to that,
> there's another area of improvement that needs to be addressed.
>
> The site itself could use a redesign and new features. What kinds of
> changes would you like to see to how the developer.mozilla.org site works?
>
> I'm working on building a list of ideas for changes to improve
> productivity for writers, encourage contributions, and make it easier to
> find information.
>
> If you've ever been stymied in getting something done with MDC, please
> let me know what you'd do to fix it!
>
that breadcrumb thing is just broken).
The search is not very useful because about 20% of the content I need is
not in MDC but on xulplanet. So I avoid the in-site search, its just
a waste of time. If I want MDC content I just use "foo mdc" in google.
If mdc site is not near the top I know it does not know foo.
John.
John J. Barton
> One of my goals is to make MDC more useful. While getting more and
> better documentation posted is obviously a key component to that,
> there's another area of improvement that needs to be addressed.
>
> The site itself could use a redesign and new features. What kinds of
> changes would you like to see to how the developer.mozilla.org site works?
>
> I'm working on building a list of ideas for changes to improve
> productivity for writers, encourage contributions, and make it easier to
> find information.
>
> If you've ever been stymied in getting something done with MDC, please
> let me know what you'd do to fix it!
>
A couple of more:
* Fewer Dead links. Yes I know the wiki paradigm is to insert the
link then fill in the page, but sections of MDC seem very incomplete
because they have links to pages that are not in progress. Concretely,
no auto-inserted links to pages that don't exist.
* Remove red "unfrozen" warnings. These are equivalent to airport
threat levels: so overused that they are meaningless. If the author of
the page has specific information that the interface is likely to change
or that it is really experimental, then the warning is fine.
* Change the Talk page entry from "Login required to edit" to clarify
the role of Discussion pages in MDC. Will someone read them? Do they
matter? Where should questions about the article be directed? Why are
the pages called "Talk" and the link to them "Discussion"?
* Pointers to example code. The very best thing about MDC is that it
has a large amount of example code. But more is better. Maybe LXR links
could be added in a section at the bottom using automatic search?
* A low overhead way of asking questions would be great for users (I
don't know about the folks who have to answer however). For example I am
on the nsIInputStream page. I'm confused: how do you open or create one
of these? There isn't any way to use the MDC page to ask the question
and then have the answer available for the next user.
Sheppy
> not in MDC but on xulplanet. So I avoid the in-site search, its just
> a waste of time. If I want MDC content I just use "foo mdc" in google.
Well, the goal is for MDC to have all the stuff you need so this isn't
necessary. :)
Sheppy
> Lastly, the biggest missing link, in my opinion, is good documentation
> of the usage of XPCOM components. Of course there are many, but I think
> ofhttp://php.net/manual/enas a good example of covering quite a large
> number of functions in a pretty thorough but easy-to-read way. That as
> well as tips on how to use libraries, etc. to make access to XPCOM
> components easier. I think we'd see a lot more powerful and creative
> extensions and apps if developers could have access to
> programming-for-the-masses documentation on these powerful components. I
> don't simply mean tutorials here, but a less terse reference manual.
I agree about the XPCOM documentation; it's very incomplete and non-
helpful right now. Unfortunately, I don't know enough about it to
write a proper set of documentation for it. If someone that knows
XPCOM really well could contribute some docs, even if they're not
great writers, I'd be thrilled to work with them to turn it into
pretty and useful documentation.