developer.mozilla.org thoughts
Apology: this is a little rushed and disorganized. Please help organize an agenda, principles of DevMo operation, and eventually, a task list that we can pipe into bugzilla. I'm not the guy to drive this project, but I will help and I want to kick it off well. I also have some strong opinions about how to proceed to get results quickly. Warning: I meant what I said in http://www.mozilla.org/events/dev-day-feb-2004/mozilla-futures/ about shamelessly imitating MSDN. I think many things about it that we can imitate are "good enough". (Don't let me start out all negative and whiny:) I'm concerned that we could spend too much time trying to find the "ideal" information architecture, but let's not. I'd be happy to hear fast proposals addressing the issues below that everyone reacts to by saying "yes, this is it." I personally think there is no ideal document hierarchy, and that flatter is better. Redundant links and indexes help. As we bring up DevMo, we should not worry about links working; until we "launch" the site to the masses, we must be able to fix mistakes as we go. Moving fast trumps moving with utmost care and caution. Bite-sized editing and fixing/polishing trumps "get all 100 pages perfect before releasing them." Marshalling volunteers with good reputations in parallel is key. All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers? Anyway, some top-down ripoff thoughts: MSDN has these links along the top: Top dark blue bar, right justified: Microsoft.com Home | Site Map Lighter blue gradient with MSDN logo on left Main toolbar, light blue gray bar: MSDN Home | Developer Centers | Library | Downloads | Code Center | Subscriptions | MSDN Worldwide Odd terminology: "Developer Centers" means "Topics"; "Code Center" means "Samples", it seems to me. Proposal: we have our own look, but with similar bars along the top: - highest has some few right-justified items to get to www.mozilla.org and a sitemap; - next has a gradient and a left-justified "DevMo" logo, or something as simple yet attractive and even more distinctive; - lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide We could leave out Subscriptions and Worldwide for now, or stub them out and call for volunteers. Library is where I think we should start building first and fastest. The three-frame UI seems good to me, but if someone has a better idea, please post it. The "MSDN Library Archive" hierarchy tree widget has these rows at the top level: Welcome to the MSDN Archive Component Development Data Access Enterprise Development Graphics and Multimedia Networking and Protocols Office Solutions Development Setup and System Administration Visual Tools and Languages Web Development Windows Development XML and Web Services When you go to Library from the toolbar, though, you get a list of Most Recent Articles. We will hope to get to the point of having so many articles, and such a stream of fresh ones, that we can or must do likewise, but for now, it seems better to me for us to have docs organized in a fairly flat category tree that organizes and includes at least: DOM (doron has a plan for these docs, I understand) DOM Inspector CSS Gecko Embedding APIs HTML Java JavaScript JavaScript Debugging APIs MathML Python SVG Venkman User Docs (there's a great site at http://www.svendtofte.com/code/learning_venkman/ -- maybe we could host it?) XBL XML XPath XPCOM XPConnect XPInstall XSLT XUL We definitely want tutorials organized by hot "How do I do X?" questions and scenarios. Guides and other longer docs that cover larger APIs and sets of APIs are needed. Architecture and user-interface laundry-list: - Need a graphical design strawman or mock-up that we can all nitpick into shape and agree on, soon. - How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.? - Do we want a wiki front end? Shaver has argued that we do, based on his recent experience. - What should we use for the repository? CVS is easy for us to set up, and a known quantity with admin support (http://despot.mozilla.org/). - We have doctor (the "edit this page" link at the bottom of every page on http://www.mozilla.org/) for easy update -- but someone, as Asa said, should really extend doctor to use Mozilla's content-editable support. Myk? - Should we let programmers use doc-comments to write primary API document source, and extract it via a javadoc style tool that grovels over the source tree, compiling XML or HTML from the extracted comments and their context? I think so. - Should we implement an idea of Ben Goodger's, doc-comment tags of some kind to bracket "best practi
Re: developer.mozilla.org thoughts
Brendan Eich wrote: (Don't let me start out all negative and whiny:) I'm concerned that we could spend too much time trying to find the "ideal" information architecture, but let's not. I'd suggest making decision based on how many contributors we have. We probably shouldn't consider too much about web developer documentation. Yes, it is important, but after IO and Rudman left since our separation from Netscape we are having no help on web dev doc, and I don't suppose the situation will change soon. As we bring up DevMo, we should not worry about links working; until we "launch" the site to the masses, we must be able to fix mistakes as we go. Moving fast trumps moving with utmost care and caution. Bite-sized editing and fixing/polishing trumps "get all 100 pages perfect before releasing them." agree, having short, intensive projects is a good way to get started Marshalling volunteers with good reputations in parallel is key. All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers? nominating fantasai and Simon Paquet :-) Proposal: we have our own look, but with similar bars along the top: - highest has some few right-justified items to get to www.mozilla.org and a sitemap; I'd suggest we avoid sitemap. Having the need for a site map usually indicate you are doing something wrong, and needing one when you are still small is a very bad sign. - next has a gradient and a left-justified "DevMo" logo, or something as simple yet attractive and even more distinctive; - lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide We could leave out Subscriptions and Worldwide for now, or stub them out and call for volunteers. don't we already have www.mozilla.org/community/ ? We will hope to get to the point of having so many articles, and such a stream of fresh ones, that we can or must do likewise, but for now, it seems better to me for us to have docs organized in a fairly flat category tree that organizes and includes at least: DOM (doron has a plan for these docs, I understand) DOM Inspector CSS Gecko Embedding APIs HTML Java JavaScript JavaScript Debugging APIs MathML Python SVG Venkman User Docs (there's a great site at http://www.svendtofte.com/code/learning_venkman/ -- maybe we could host it?) XBL XML XPath XPCOM XPConnect XPInstall XSLT XUL let's leave out CSS, HTML, MathML, XML, Python, and XSLT for now. Don't get too ambitious. We definitely want tutorials organized by hot "How do I do X?" questions and scenarios. Guides and other longer docs that cover larger APIs and sets of APIs are needed. Architecture and user-interface laundry-list: - Need a graphical design strawman or mock-up that we can all nitpick into shape and agree on, soon. - How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.? - Do we want a wiki front end? Shaver has argued that we do, based on his recent experience. yes we do. We should lock front page and top-level index pages though. - What should we use for the repository? CVS is easy for us to set up, and a known quantity with admin support (http://despot.mozilla.org/). CVS is a big hurdle for many new contributors, both in m.o and mozdev.org. What alternatives do we have? Let's go! DevMo! Do we have a schedule for this? I'm trying to get a International Month started on April or May, so I'd like to avoid bad time collision. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: Brendan Eich wrote: (Don't let me start out all negative and whiny:) I'm concerned that we could spend too much time trying to find the "ideal" information architecture, but let's not. I'd suggest making decision based on how many contributors we have. We probably shouldn't consider too much about web developer documentation. On the contrary, web developer documentation is probably the most important. We're trying to compete with MSDN, and the MSDN DOM references are the model. let's leave out CSS, HTML, MathML, XML, Python, and XSLT for now. Don't get too ambitious. CSS, HTML, XML, XSLT are part of the core requirements for this project. MathML needs someone to write docs, but let's not shoot them in the foot yet... More thoughts later... I'm not sure wiki suits our needs well at all, scalability-wise. --BDS ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers? I have one suggestion, lets mark up the site/navigation/documents in such a way that we can easily build an XUL frontend with additional ease of use features for those viewing the size with a Mozilla browser. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Since that *seems* to be the direction mf is taking (example the talk about MAB on Friday), I would agree. Fred wrote: Brendan Eich wrote: All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers? I have one suggestion, lets mark up the site/navigation/documents in such a way that we can easily build an XUL frontend with additional ease of use features for those viewing the size with a Mozilla browser. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: Proposal: we have our own look, but with similar bars along the top: - highest has some few right-justified items to get to www.mozilla.org and a sitemap; I'd suggest we avoid sitemap. Having the need for a site map usually indicate you are doing something wrong, and needing one when you are still small is a very bad sign. Ok -- I never use them, but someone must(?). They're all over the web. - next has a gradient and a left-justified "DevMo" logo, or something as simple yet attractive and even more distinctive; - lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide We could leave out Subscriptions and Worldwide for now, or stub them out and call for volunteers. don't we already have www.mozilla.org/community/ ? Not the same. Worldwide would be localized versions of developer.mozilla.org, if we follow the MSDN model. Definitely something for later, unless translators show up soon. We will hope to get to the point of having so many articles, and such a stream of fresh ones, that we can or must do likewise, but for now, it seems better to me for us to have docs organized in a fairly flat category tree that organizes and includes at least: DOM (doron has a plan for these docs, I understand) DOM Inspector CSS Gecko Embedding APIs HTML Java JavaScript JavaScript Debugging APIs MathML Python SVG Venkman User Docs (there's a great site at http://www.svendtofte.com/code/learning_venkman/ -- maybe we could host it?) XBL XML XPath XPCOM XPConnect XPInstall XSLT XUL let's leave out CSS, HTML, MathML, XML, Python, and XSLT for now. Don't get too ambitious. Placeholders, commented out if you like. - What should we use for the repository? CVS is easy for us to set up, and a known quantity with admin support (http://despot.mozilla.org/). CVS is a big hurdle for many new contributors, both in m.o and mozdev.org. What alternatives do we have? Myk's doctor CGI ("edit this page" links on the main site) with content-editable would make a decent front end. A wiki front end might placate anyone not happy with doctor. Let's go! DevMo! Do we have a schedule for this? I'm trying to get a International Month started on April or May, so I'd like to avoid bad time collision. DevMo should be under design and incremental construction this week. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Fred wrote: Brendan Eich wrote: All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers? I have one suggestion, lets mark up the site/navigation/documents in such a way that we can easily build an XUL frontend with additional ease of use features for those viewing the size with a Mozilla browser. Doron's redoing the DOM guide in XML, so we can generate various presentation languages. Sounds like a good idea if we can get the generation scripts hooked up and automated. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Le 03/03/2004 06:11, Benjamin D. Smedberg a écrit : CSS, HTML, XML, XSLT are part of the core requirements for this project. MathML needs someone to write docs, but let's not shoot them in the foot yet... Would it be possible to move most of the Netscape Devedge content moved to this new site ? There are valuable articles there which would probably require little or no rewrite for the mozilla portal. Pascal -- Pascal Chevrel - Mozilla Champion FAQ Mozilla/Netscape 7 en français : http://pascal.chevrel.free.fr/ Foros Mozilla en español : http://www.chevrel.org/es/foros/ ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
On 2004-03-03, Brendan Eich <[EMAIL PROTECTED]> wrote: > Clover wrote: > >>> Proposal: we have our own look, but with similar bars along the top: >>> - highest has some few right-justified items to get to >>> www.mozilla.org and a sitemap; >> >> I'd suggest we avoid sitemap. Having the need for a site map usually >> indicate you are doing something wrong, and needing one when you are >> still small is a very bad sign. > > Ok -- I never use them, but someone must(?). They're all over the web. I think people have them because everyone else does. I use them on occasion, but those occasions are generally when I've failed to find what I want using either the navigation/content links or whatever site search is available (before resorting to google). I don't think there's anything wrong with having the sitemap, but it shouldn't be necessary for people to use it to find things. >>> - What should we use for the repository? CVS is easy for us to set >>> up, and a known quantity with admin support >>> (http://despot.mozilla.org/). >> >> CVS is a big hurdle for many new contributors, both in m.o and >> mozdev.org. What alternatives do we have? > > Myk's doctor CGI ("edit this page" links on the main site) with > content-editable would make a decent front end. A wiki front end might > placate anyone not happy with doctor. Doctor is fine if you can make the changes there and then, but for the mozilla site, you (at least in theory) need a review, so you have to do awkward copy/paste operations from doctor into bugzilla, and it generally ends up being easier to retype the changes rather than attempting to get the patch from bugzilla back into doctor's web form. On the other hand, I don't like wiki either, from what little experience I've had. >>> Let's go! DevMo! >> >> Do we have a schedule for this? I'm trying to get a International >> Month started on April or May, so I'd like to avoid bad time collision. > > DevMo should be under design and incremental construction this week. Cool. I'd be happy to help, although I fear there may be a lack of contributors that understand the technical stuff well, and I'm not much good in that respect either. -- Michael ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
It seems like people are confused again on the target audience. Whether it would be web developers or mozilla developers. From what I read in the vicinity of this, be talks about mozilla developers, working on both the mozilla code itself or extensions. But even then, we should prolly define the target audience a bit stricter. Like, do we talk to people who wanna write extensions or do we talk to people who wanna fix table printing bugs (hi bernd). And if both, how do we make clear which audience a particular page targets? Axel ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: Apology: this is a little rushed and disorganized. Please help organize an agenda, principles of DevMo operation, One thing jumps out at me: is it too late to avoid calling it "DevMo"? Ick. Sounds like a lawnmower. :-) I'd like to call it "MozDev", but that name seems to be taken. We could call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. All that open source motherhood and apple pie aside, it's vitally important that we have an editor-in-chief who will set prose and web content style rules, rally writers and other editors to urgent tasks, police the prototype site for bugs, and lead in driving the buglist to zarro. Volunteers? Fantasai's been the voice crying in the wilderness on these issues for years. I nominate her :-) Whoever it is should receive near-unequivocal mozilla.org backing for their decisions in their domain, like a module owner. - lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide Questions for discussion: What's the difference between "Topics" and "Library"? Why are "Samples" separated out? Library is where I think we should start building first and fastest. The three-frame UI seems good to me, but if someone has a better idea, please post it. MSDN has this horrible hacky "sync toc" button. Can we do that automatically? - How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.? Surely some XML dialect? After all, we should eat our own dogfood. DocBook may be overkill, I don't know - we could define a simple subset and write a HOWTO. - Do we want a wiki front end? Shaver has argued that we do, based on his recent experience. In my experience, except for a few good apps like Wikipedia, wikis tend to produce the documentation equivalent of a BigBallOfMud, with broken links and circular references everywhere. The key problem with Wikis is that they make it very hard to be certain whether the information you are looking for actually is, or isn't, in there somewhere. You can hunt for hours and go round in circles very easily. - What should we use for the repository? CVS is easy for us to set up, and a known quantity with admin support (http://despot.mozilla.org/). As I understand it, despot's admin support doesn't let us do a load of things we'd want to - like delegation ("Bob, you can edit directory X, but not Y; Fred, you can edit Y and X but not Q"). Or if it does in theory, it doesn't scale. CVS is also a particularly bad choice for a system where documents are going to be moving around a lot. Its limitations in that area are well-known. - We have doctor (the "edit this page" link at the bottom of every page on http://www.mozilla.org/) for easy update -- but someone, as Asa said, should really extend doctor to use Mozilla's content-editable support. Myk? This sounds like a re-inventing of the wheel to me. Can we please use some content management software designed for managing web content? I don't give a stuff which one of the five thousand open source CMSes it is. But they all do the job they were designed to do better than CVS. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: I'd like to call it "MozDev", but that name seems to be taken. We could call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. If we're going to go big on the copying, how about "MozDN"? ;-) Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
On 2004-03-03, Gervase Markham <[EMAIL PROTECTED]> wrote: > Gervase Markham wrote: > >> I'd like to call it "MozDev", but that name seems to be taken. We could >> call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. > > If we're going to go big on the copying, how about "MozDN"? ;-) Good plan. Then we can receive a threat of legal action for trademark infringement as well as copyright infringement, and rename the project 4 times over the course of a couple of years as we try to find a name that's not taken. ;) -- Michael ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: On 2004-03-03, Gervase Markham <[EMAIL PROTECTED]> wrote: Gervase Markham wrote: I'd like to call it "MozDev", but that name seems to be taken. We could call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. If we're going to go big on the copying, how about "MozDN"? ;-) Good plan. Then we can receive a threat of legal action for trademark infringement as well as copyright infringement, and rename the project 4 times over the course of a couple of years as we try to find a name that's not taken. ;) MOD Mozilla Org Developer (Development) Ministry of Development MozMOD Mozilla Ministry of Development MODMoz Ministry of Development Mozilla MOD itself may be a little dicey as there are trademark considerations (tho none in the software industry currently) but MozMOD (or MODMoz) would alleviate those concerns The title does reflect the role as well, administration of the developers (development) or ministering to such. It allows for less or more central control as the current job holder envisages (less is more in this case tho). Developers could be advised by MozMOD without being controlled by it, it serving more or less as a central clearing house, which occurs to me is the intent. Rolls off the tongue better than MozDN (mozdown? mozdin? mozdun? mozdeein?) too ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
And on the seventh day Clover spoke: >> Marshalling volunteers with good reputations in >> parallel is key. >> >> All that open source motherhood and apple pie aside, it's vitally >> important that we have an editor-in-chief who will set prose and web >> content style rules, rally writers and other editors to urgent tasks, >> police the prototype site for bugs, and lead in driving the buglist to >> zarro. Volunteers? > >nominating fantasai and Simon Paquet :-) I feel honored, but my unemployment period will most likely end around the middle of March/beginning of April and then I can't contribute as much time as I did in the past. Simon -- Default QA Contact Firefox - Menus/Toolbars/Installer My Mozilla blog: http://www.babylonsounds.com/blog.html Join us on Bugday: Every Tuesday from 10 AM - 6 PM PST in the #mozillazine channel on irc.mozilla.org ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: Doron's redoing the DOM guide in XML, so we can generate various presentation languages. Sounds like a good idea if we can get the generation scripts hooked up and automated. Good to hear that. He said he would take over IO's DOM Ref doc, but I haven't seen any activity, so this's good news :-) ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Pascal Chevrel wrote: Le 03/03/2004 06:11, Benjamin D. Smedberg a écrit : CSS, HTML, XML, XSLT are part of the core requirements for this project. MathML needs someone to write docs, but let's not shoot them in the foot yet... Would it be possible to move most of the Netscape Devedge content moved to this new site ? There are valuable articles there which would probably require little or no rewrite for the mozilla portal. Yes. Mozilla Foundation is working on getting the rights to these docs. It didn't happen when the Foundation was spun out last summer, but it should happen shortly. More when I know more. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Axel Hecht wrote: It seems like people are confused again on the target audience. Whether it would be web developers or mozilla developers. From what I read in the vicinity of this, be talks about mozilla developers, working on both the mozilla code itself or extensions. Right. Web development in the sense of "I want to write an HTML page that works well in Mozilla and other top browsers" should not be our primary focus, I argue. The problem we're trying to help solve with documentation is answering the question "how do I develop this application or app-extension using XUL and other Mozilla platform components?" But even then, we should prolly define the target audience a bit stricter. Like, do we talk to people who wanna write extensions or do we talk to people who wanna fix table printing bugs (hi bernd). And if both, how do we make clear which audience a particular page targets? Good question. I don't have a slick answer, but it's important not to focus too much on the smaller markets (table printing bugfixers, although we welcome new help there as elsewhere) at the expense of the larger ones (extension authors, whole-XUL-app authors). We need a way to categorize and guide people quickly into the right area; we can stand to have an area for core C++ code docs to-do with Gecko table code, etc. -- but that's not first priority. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: Brendan Eich wrote: Apology: this is a little rushed and disorganized. Please help organize an agenda, principles of DevMo operation, One thing jumps out at me: is it too late to avoid calling it "DevMo"? Ick. Sounds like a lawnmower. :-) Or a beverage store (http://www.bevmo.com/productlist.asp?area=home) -- what's wrong with that? I'd like to call it "MozDev", but that name seems to be taken. We could call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. Try saying d.m.o. three times fast, over a phone, in a conversation where it might be confused with b.m.o. Fantasai's been the voice crying in the wilderness on these issues for years. I nominate her :-) Whoever it is should receive near-unequivocal mozilla.org backing for their decisions in their domain, like a module owner. Need to hear proposals from would-be owners. I'm open to all comers. - lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide Questions for discussion: What's the difference between "Topics" and "Library"? Why are "Samples" separated out? Why have any top-level other than "Library"? So people can find stuff fast without having to parachute into the site and then back out and try again. Library is a comprehensive, probably alphabetically listed archive. Topics is a guided tour by developer interest area, not by module, language, or standard. If the two really were the same, we could unify. It's interesting that MSDN did not. Library is where I think we should start building first and fastest. The three-frame UI seems good to me, but if someone has a better idea, please post it. MSDN has this horrible hacky "sync toc" button. Can we do that automatically? Yes, please. Their DHTML tree widget has lots of problems. I do *not* propose that we clone it -- there are much better ones around, and we can optionally generate XUL to serve to Mozilla user-agents. - How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.? Surely some XML dialect? After all, we should eat our own dogfood. DocBook may be overkill, I don't know - we could define a simple subset and write a HOWTO. Doron is already doing this for the DOM guide. I'll defer to him here. - Do we want a wiki front end? Shaver has argued that we do, based on his recent experience. In my experience, except for a few good apps like Wikipedia, wikis tend to produce the documentation equivalent of a BigBallOfMud, with broken links and circular references everywhere. Yeah. Strong editors needed, the Wiki is just the front end, and maybe the patch-tool if Doctor isn't right. As I understand it, despot's admin support doesn't let us do a load of things we'd want to - like delegation ("Bob, you can edit directory X, but not Y; Fred, you can edit Y and X but not Q"). Or if it does in theory, it doesn't scale. It allows us to give access only to a list of people. That's good enough to start with. Let's not get too fancy yet. CVS is also a particularly bad choice for a system where documents are going to be moving around a lot. Its limitations in that area are well-known. Right, but what's better? Are we really going to jump on the Subversion bandwagon and multiply risks we have to take on just to do DevMo, apart from the repository risks, by the risk of not-CVS and newer-than-CVS? - We have doctor (the "edit this page" link at the bottom of every page on http://www.mozilla.org/) for easy update -- but someone, as Asa said, should really extend doctor to use Mozilla's content-editable support. Myk? This sounds like a re-inventing of the wheel to me. Why? Doctor is here, it just needs new sidewalls. Can we please use some content management software designed for managing web content? I don't give a stuff which one of the five thousand open source CMSes it is. But they all do the job they were designed to do better than CVS. You mean like Zope, which last time this was tried, didn't keep version histories in any delta-encoded way, just blobs of old files in a db? How much more risk are we adding? Remember, for independent events, the multiplication principle applies. If we are launching ASAP, why wouldn't we use what we have now? /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Dan Gall wrote: Michael Lefevre wrote: On 2004-03-03, Gervase Markham <[EMAIL PROTECTED]> wrote: Gervase Markham wrote: I'd like to call it "MozDev", but that name seems to be taken. We could call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. If we're going to go big on the copying, how about "MozDN"? ;-) Good plan. Then we can receive a threat of legal action for trademark infringement as well as copyright infringement, and rename the project 4 times over the course of a couple of years as we try to find a name that's not taken. ;) Heh. Seriously, don't clone trademarks and acronyms. MOD Ambiguous, also a jargon-word. Mozilla Org Developer (Development) Ministry of Development I love Big Brother! MozMOD [. . .] Rolls off the tongue better than MozDN (mozdown? mozdin? mozdun? mozdeein?) too Agreed, but it's ambiguous, and it doesn't say "DEVeloper" up front and as clearly as DevMo does. I started this party, I still say DevMo is it -- move along. That is all. ;-) /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Benjamin D. Smedberg wrote: Clover wrote: Brendan Eich wrote: (Don't let me start out all negative and whiny:) I'm concerned that we could spend too much time trying to find the "ideal" information architecture, but let's not. I'd suggest making decision based on how many contributors we have. We probably shouldn't consider too much about web developer documentation. On the contrary, web developer documentation is probably the most important. We're trying to compete with MSDN, and the MSDN DOM references are the model. MSDN as model applies more to completeness, organization (where good), and style, not necessarily to content. We won't document Windows APIs on DevMo, after all. As I just posted recently, I continue to think DevMo's emphasis should be on XUL app and extension developers, with other areas (core C++ code, C++ or other XPCOM component writing, web page development, etc.) coming in at lower priority as contributors deem appropriate. DOM docs are good for XUL development, for sure. But DevMo need not recapitulate the contents of existing, cross-browser web devlopment resource sites, and should not put that cart ahead of the horse. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: Benjamin D. Smedberg wrote: Clover wrote: Brendan Eich wrote: (Don't let me start out all negative and whiny:) I'm concerned that we could spend too much time trying to find the "ideal" information architecture, but let's not. I'd suggest making decision based on how many contributors we have. We probably shouldn't consider too much about web developer documentation. On the contrary, web developer documentation is probably the most important. We're trying to compete with MSDN, and the MSDN DOM references are the model. MSDN as model applies more to completeness, organization (where good), and style, not necessarily to content. We won't document Windows APIs on DevMo, after all. As I just posted recently, I continue to think DevMo's emphasis should be on XUL app and extension developers, with other areas (core C++ code, C++ or other XPCOM component writing, web page development, etc.) coming in at lower priority as contributors deem appropriate. DOM docs are good for XUL development, for sure. But DevMo need not recapitulate the contents of existing, cross-browser web devlopment resource sites, and should not put that cart ahead of the horse. /be As a relatively new developer to Moz I can say there are two areas in which new documentation would be helpful to XUL developers: 1. Docs that explain how using the DOM with XUL differs from using the DOM with HTML. 2. Docs that explain the relationship between XPTookit, XUL and XPCOM. (as far as I can tell XUL, XPCOM, XPInstall etc are all part of the XPToolkit, but that is not stated anywhere I can find and is not obvious given the layout of docs on moz.org). ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
I had discussions with several people at DevDay about the need for a well managed component repository for XUL apps. I'm thinking along the lines of something like PEAR for PHP and CPAN for Perl, but containing reusable XBL widgets and XUL/XPCOM specific JavaScript classes. Is this something that DevMo should encompass? Fred ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Fred wrote: 1. Docs that explain how using the DOM with XUL differs from using the DOM with HTML. With HTML or with XHTML? That is, XUL-specific differences (there should be none, ideally; the few that exist are bugs that we're hoping to fix ASAP) or XML-specific differences? -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Fred wrote: As a relatively new developer to Moz I can say there are two areas in which new documentation would be helpful to XUL developers: 1. Docs that explain how using the DOM with XUL differs from using the DOM with HTML. Good point. Also in part a matter of bugs to fix, if I recall correctly. 2. Docs that explain the relationship between XPTookit, XUL and XPCOM. (as far as I can tell XUL, XPCOM, XPInstall etc are all part of the XPToolkit, but that is not stated anywhere I can find and is not obvious given the layout of docs on moz.org). We actually have two XUL toolkits, "XPToolkit" as in XPFE (http://www.mozilla.org/xpfe/ covers this as well as core XUL and XBL) and the "new toolkit" (http://lxr.mozilla.org/mozilla/source/toolkit/) used by Firefox, Thunderbird, NVu, and other apps. We should diagram the onion and document all the layers, including alternative layers. But if we have to choose, I say document the new toolkit -- it's the future (XPFE is in sustaining engineering mode). /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: Myk's doctor CGI ("edit this page" links on the main site) with content-editable would make a decent front end. A wiki front end might placate anyone not happy with doctor. Doctor is fine if you can make the changes there and then This is in fact true of every single web-based front end I can think of. For actual major changes, there is no reasonable alternative I'm aware of to being able to get the file into whatever text editor you like and edit it, then upload it back to the site. With CVS, this is trivial. Some CMSes support this to some extent. Whatever we do, I feel that we should keep in mind that authoring a document in a textarea is very painful. Especially if we're authoring in some random XML format (so even the limited crutch of Midas is not available). -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: Fred wrote: 1. Docs that explain how using the DOM with XUL differs from using the DOM with HTML. With HTML or with XHTML? That is, XUL-specific differences (there should be none, ideally; the few that exist are bugs that we're hoping to fix ASAP) or XML-specific differences? -Boris XML vs HTML, there are a lot of stupid little DOM tricks out there for HTML that just don't work with XUL/XML. Web developers familiar with the HTML and Core DOM could use some guidance in moving to the XML DOM. Fred ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: Gervase Markham wrote: I'd like to call it "MozDev", but that name seems to be taken. We could call it "d.m.o" after "b.m.o"... I'm sure others can think of better names. If we're going to go big on the copying, how about "MozDN"? ;-) Oracle Technology Network http://otn.oracle.com/ Borland Developer Network http://bdn.borland.com/ Open Source Development Network http://www.osdn.com/ Netscape DevEdge http://devedge.netscape.com/ IBM developerWorks http://www-136.ibm.com/developerworks/ Wireless Developer Network http://www.wirelessdevnet.com/ Sun Developer Network http://developers.sun.com Apple Developer Connection http://developer.apple.com/ I don't think we'd have any problem with DN name ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Fred wrote: XML vs HTML, there are a lot of stupid little DOM tricks out there for HTML that just don't work with XUL/XML. Web developers familiar with the HTML and Core DOM could use some guidance in moving to the XML DOM. OK, makes sense. Note that Core DOM _is_ the XML DOM, though ;) But yes, we should document things like using createElementNS and the like. -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: Good plan. Then we can receive a threat of legal action for trademark infringement as well as copyright infringement, There's no danger of copyright infringement unless we pinch their HTML code. And we have standards. And I very much doubt MS would approach us over trademarks, MikeRoweSoft.com notwithstanding. MozDN and MSDN are dissimilar enough, I think. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: Or a beverage store (http://www.bevmo.com/productlist.asp?area=home) -- what's wrong with that? The whole "Mo'" thing meaning "More" is really cheesily American to other English speakers - those that understand it at all... In the past, we've always used "Moz" as Mozilla's 'short name'. Why change? As I understand it, despot's admin support doesn't let us do a load of things we'd want to - like delegation ("Bob, you can edit directory X, but not Y; Fred, you can edit Y and X but not Q"). Or if it does in theory, it doesn't scale. It allows us to give access only to a list of people. That's good enough to start with. Let's not get too fancy yet. The problem is that, if we want to get fancier, we have to write all the code ourselves. Which means it'll probably never happen. CVS is also a particularly bad choice for a system where documents are going to be moving around a lot. Its limitations in that area are well-known. Right, but what's better? Are we really going to jump on the Subversion bandwagon and multiply risks we have to take on just to do DevMo, apart from the repository risks, by the risk of not-CVS and newer-than-CVS? "Mozilla must use the best open source solution to solve a well-understood problem." - Brendan Eich, original Mozilla Roadmap. Is CVS really the answer to that question for website content management? If it is, why is no-one else using it? - We have doctor (the "edit this page" link at the bottom of every page on http://www.mozilla.org/) for easy update -- but someone, as Asa said, should really extend doctor to use Mozilla's content-editable support. Myk? This sounds like a re-inventing of the wheel to me. Why? Doctor is here, it just needs new sidewalls. While Doctor eases the pain (and is a great technical achievement), the general view I've been hearing is that editing the website using it is still like kicking a dead whale down a beach. This is due to the inherent limitations of web editing interfaces (bzbarsky is right here) coupled to the CVS backend. Can we please use some content management software designed for managing web content? I don't give a stuff which one of the five thousand open source CMSes it is. But they all do the job they were designed to do better than CVS. You mean like Zope, which last time this was tried, didn't keep version histories in any delta-encoded way, just blobs of old files in a db? I _particularly_ didn't mention Zope on purpose - in fact, I said "I don't care which one it is", to prevent old Zope issues clouding the picture. It's two years later, an eternity in Internet time. I'm sure both Zope and it's many competitors have improved a lot since we last looked. How much more risk are we adding? Remember, for independent events, the multiplication principle applies. If we are launching ASAP, why wouldn't we use what we have now? Because that'll mean "what we have now" becomes "what we have forever". The www.mozilla.org website is a navigational ball of mud, and we've never got a serious body of contributors working on it. Compared to the sites of many other projects, it sucks. We need to analyse why that is, and avoid making the same mistakes again. I assert CVS is part of the problem - we can argue that, fine, but even if everyone else disagrees with me, we need to learn what our mistakes were to avoid repeating them. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: The www.mozilla.org website is a navigational ball of mud, and we've never got a serious body of contributors working on it. yes, and I'm afraid that can happen to DevMO too Compared to the sites of many other projects, it sucks. We need to analyse why that is, and avoid making the same mistakes again. I assert CVS is part of the problem CVS is a two-part problem: 1. Few people know that they can get a CVS account to edit m.o pages; those who do have already been around a long time. If you need help, you've got to find a qualified contributor, help them get a CVS account, and help them get through CVS. This means only a small percent of potential contributors get selected. 2. CVS has a rather steep learning curve *sign* Doctor isn't always applicable. You cannot apply patches through Doctor. You cannot upload UTF8 doc through Doctor because it convert characters to ugly 's. You cannot modify NOMENU and NOWRAP through Doctor. You cannot upload images using Doctor. If someone with a CVS account want to do anything useful, sooner or later s/he has to learn CVS. CVS is not the whole story. People need to learn to watch the webtree using Bonsai (and this isn't documented anywhere). mozilla.org is getting more complicated, and we need to document , templates, the various CSS classes, NOMENU and NOWRAP, etc. to help contributors build m.o to its full potential. - we can argue that, fine, but even if everyone else disagrees with me, we need to learn what our mistakes were to avoid repeating them. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
On 2004-03-04, Gervase Markham <[EMAIL PROTECTED]> wrote: [snip] > And I very much doubt MS would approach us over trademarks, > MikeRoweSoft.com notwithstanding. MozDN and MSDN are dissimilar enough, > I think. You don't seem 100% sure. I'm not sure you're wrong, but who knows... "Moz" and "MS" are quite similar really... I mean, would we be happy if someone brought out a new browser called MSzilla? :) -- Michael ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
As you mentioned it somewhere down the thread, what should the relation between devmo and xulplanet be? Do we want to cover XUL or should we link to xulplanet for that? The old fame vs. load question. As you indicated translations, should they happen on the same site, if ever? Should we try to be ready to get them in now? Axel ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
On 2004-03-04, Gervase Markham <[EMAIL PROTECTED]> wrote: > Brendan Eich wrote: [snip] >> >> It allows us to give access only to a list of people. That's good >> enough to start with. Let's not get too fancy yet. > > The problem is that, if we want to get fancier, we have to write all the > code ourselves. Which means it'll probably never happen. True, on the other hand, if it's decided to investigate and implement something else, the whole project will probably never happen. >> Right, but what's better? Are we really going to jump on the Subversion >> bandwagon and multiply risks we have to take on just to do DevMo, apart >> from the repository risks, by the risk of not-CVS and newer-than-CVS? > > "Mozilla must use the best open source solution to solve a > well-understood problem." - Brendan Eich, original Mozilla Roadmap. Rather taken out of context... he was talking about creating stuff, not actually using it. > I _particularly_ didn't mention Zope on purpose - in fact, I said "I > don't care which one it is", to prevent old Zope issues clouding the > picture. It's two years later, an eternity in Internet time. I'm sure > both Zope and it's many competitors have improved a lot since we last > looked. But again, if we decide to start looking, we'll be arguing about different systems (no doubt, clouded by much discussion of the Zope incident) for months. If there is actually someone with the time and competance given control and responsibility for pulling the whole thing together, and people writing the content, I would imagine the technical issues can probably be overcome... [snip] > The www.mozilla.org website is a navigational ball of mud, and we've > never got a serious body of contributors working on it. Compared to the > sites of many other projects, it sucks. We need to analyse why that is, > and avoid making the same mistakes again. I assert CVS is part of the > problem - we can argue that, fine, but even if everyone else disagrees > with me, we need to learn what our mistakes were to avoid repeating them. CVS is part of the problem, but I don't think it's the biggest part. Although I've only been around for a short part of the history of it, the problem seems to me to be that the website is managed by hundreds of different people, most of whom have long since gone away, and nobody has both the authority and the time to do anything about it. Each change has to be accompanied by attempts to track down people that don't communicate and/or don't exist, and usually a group debate on the merits of the changes are, who the audience is supposed to be, whose content is best, what the views of someone that isn't communicating might be, and the fact that the system doesn't work and wouldn't Zope have been good. We also seem to have a large number of people keen to contribute to meta discussion and technical tweaking, and a small number of people actually willing and able to write content. -- Michael ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover aber hob zu reden an und schrieb: >> If we're going to go big on the copying, how about "MozDN"? ;-) [DN in current use] > I don't think we'd have any problem with DN name Apart from it being ugly. ;-) Event though "DevMo" sounds like an aurally impared Simpsons character, it's far better than MozDN, IMHO... Karsten -- Freiheit stirbt| Fsayannes SF&F-Bibliothek: Mit Sicherheit| http://fsayanne.tprac.de/ ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: On 2004-03-04, Gervase Markham <[EMAIL PROTECTED]> wrote: The www.mozilla.org website is a navigational ball of mud, and we've never got a serious body of contributors working on it. Compared to the sites of many other projects, it sucks. We need to analyse why that is, and avoid making the same mistakes again. I assert CVS is part of the problem - we can argue that, fine, but even if everyone else disagrees with me, we need to learn what our mistakes were to avoid repeating them. CVS is part of the problem, but I don't think it's the biggest part. Although I've only been around for a short part of the history of it, the problem seems to me to be that the website is managed by hundreds of different people, most of whom have long since gone away, and nobody has both the authority and the time to do anything about it. Each change has to be accompanied by attempts to track down people that don't communicate and/or don't exist, and usually a group debate on the merits of the changes are, who the audience is supposed to be, whose content is best, what the views of someone that isn't communicating might be, and the fact that the system doesn't work and wouldn't Zope have been good. As an innocent bystander, I agree with Gerv on this; we'd be much better off with a proper CMS that is designed to deal with websites rather than trying to hack CVS into doing the same job. I haven't investigated largescale CMS systems, but perhaps they have features to deal with the editing problem; one could certianly imagine that such systems would provide something like the patch queue in bugzilla, so changes to a page would be queued for approval by the person responsible for maintaining the page. If the CMS handled details like that, trying to track people down in bugzilla/newsgroups/irc in order to make small edits of a document wouldn't be so necessary. It would also be possible to see who was neglecting their pages and assign maintainance of such pages to another person. With the current system, this is rather more complex (at the very least, bugzilla has to be involved, which adds another overhead). Obviously, designed from-the-ground-up CMS systems will have other advantages too, but I think that providing a transparent system for adding or modifying documents would be a big improvment for people looking to contribute documents. We also seem to have a large number of people keen to contribute to meta discussion and technical tweaking, and a small number of people actually willing and able to write content. Yeah, that sounds like me (well, I'm willing to write stuff, but not able...) ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: Brendan Eich wrote: Or a beverage store (http://www.bevmo.com/productlist.asp?area=home) -- what's wrong with that? The whole "Mo'" thing meaning "More" is really cheesily American to other English speakers - those that understand it at all... In the past, we've always used "Moz" as Mozilla's 'short name'. Why change? I haven't used Moz that way, and jwz was dead-set against it. Maybe we're just grumpy old men. But first, let's agree that the domain name should be developer.mozilla.org -- that's what inspired the DevMo name, not "Mo" as short for "More". As I understand it, despot's admin support doesn't let us do a load of things we'd want to - like delegation ("Bob, you can edit directory X, but not Y; Fred, you can edit Y and X but not Q"). Or if it does in theory, it doesn't scale. It allows us to give access only to a list of people. That's good enough to start with. Let's not get too fancy yet. The problem is that, if we want to get fancier, we have to write all the code ourselves. Which means it'll probably never happen. We already have to maintain despot. Unless you are going to pile future unknown requirements on it, I don't see how we'll fail for want of a better despot. Either we'll limp along, or we'll improve despot -- or later (that's the key -- not right now!) we will lift up the server content on really big jacks, slide out despot and even CVS, and drop the content back down on something better. Later. CVS is also a particularly bad choice for a system where documents are going to be moving around a lot. Its limitations in that area are well-known. Right, but what's better? Are we really going to jump on the Subversion bandwagon and multiply risks we have to take on just to do DevMo, apart from the repository risks, by the risk of not-CVS and newer-than-CVS? "Mozilla must use the best open source solution to solve a well-understood problem." - Brendan Eich, original Mozilla Roadmap. Is CVS really the answer to that question for website content management? If it is, why is no-one else using it? What are people using on sites of the same scale as ours? Tell me more, fast. And remember not to multiply risk gratuitously at the front of the schedule. I _particularly_ didn't mention Zope on purpose - in fact, I said "I don't care which one it is", to prevent old Zope issues clouding the picture. It's two years later, an eternity in Internet time. I'm sure both Zope and it's many competitors have improved a lot since we last looked. You had better care, and make a concrete proposal, otherwise CVS wins, because it's here now and we use it for the website. Get real! How much more risk are we adding? Remember, for independent events, the multiplication principle applies. If we are launching ASAP, why wouldn't we use what we have now? Because that'll mean "what we have now" becomes "what we have forever". Nonsense. We don't have the same web content we did in 1998. We don't have the same layout engine, either. Things change. Put some constructive energy into this, and be practical. Just complaining about CVS or asserting that no one else uses it is not enough. Note: I'm not saying CVS is "enough". We use other tools layered on it. It gives us just the bare bones versioning for files (as you note, not for directories) that we need to be able to diff and patch documents among branches, and the like. We don't want to lose that in the quest for fancier replacements. Hence my mention of Subversion -- but is it ready for prime time? The www.mozilla.org website is a navigational ball of mud, and we've never got a serious body of contributors working on it. What does that have anything to do with CVS? The people who didn't follow README-style and precedent would have done likewise using any other revision control system. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: Gervase Markham wrote: The www.mozilla.org website is a navigational ball of mud, and we've never got a serious body of contributors working on it. yes, and I'm afraid that can happen to DevMO too The solution is a strong, competent editor. I have at least one volunteer already. Anyone else up for it, or want to assist the editor-in-chief? /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Axel Hecht wrote: As you mentioned it somewhere down the thread, what should the relation between devmo and xulplanet be? Link always, try to get docs hosted well in any case. We are not a portal -- we don't mind if people follow a link off to another site, so long as it's a great site like xulplanet.org. I'm mainly concerned about server load at first. Later, the lack of localizations and coherence (indexing) will start to hurt. So ultimately, I'd like to see DevMo host the essential XUL docs, and even some non-essential ones. As you indicated translations, should they happen on the same site, if ever? Should we try to be ready to get them in now? That's why I proposed, in shameless imitation of msdn except for the name, a Worldwide item on the link toolbar. That would lead to an index page of links to various localizations. Should the localizations be hosted at developer.mozilla.org? I think so, for the same reason we want to "stand alone" if necessary for XUL docs. That does mean we need assistant editors who speak various languages and can help the editor-in-chief run a tight ship across many localizations. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: > CVS is part of the problem, but I don't think it's the biggest part. > Although I've only been around for a short part of the history of it, the > problem seems to me to be that the website is managed by hundreds of > different people, most of whom have long since gone away, and nobody has > both the authority and the time to do anything about it. It's because we don't have any structure for new contributor. If you write a doc, you either need to maintain it or track down someone else who can do this. So we have a situation where people who need help cannot find help, and people who want to help has nothing to help with. > Each change has > to be accompanied by attempts to track down people that don't communicate > and/or don't exist, and usually a group debate on the merits of the > changes are, who the audience is supposed to be, whose content is best, > what the views of someone that isn't communicating might be, and the fact > that the system doesn't work and wouldn't Zope have been good. That happens when we are dealing with doc written long ago and hasn't been updated since. What's cool about MSDN is that on top of every page is the publish date (and software version applicability), so MS has an excuse not to update old docs. Perhaps we should have a structure/rule to simply mark old docs as obsolete and replace them with new ones? > We also > seem to have a large number of people keen to contribute to meta > discussion and technical tweaking, and a small number of people actually > willing and able to write content. That's a thing in the past. I haven't seen much meta discussion, and I think most of us have learned from the bad experience :-) ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: CVS is part of the problem, but I don't think it's the biggest part. Although I've only been around for a short part of the history of it, the problem seems to me to be that the website is managed by hundreds of different people, most of whom have long since gone away, and nobody has both the authority and the time to do anything about it. Each change has to be accompanied by attempts to track down people that don't communicate and/or don't exist, and usually a group debate on the merits of the changes are, who the audience is supposed to be, whose content is best, what the views of someone that isn't communicating might be, and the fact that the system doesn't work and wouldn't Zope have been good. We also seem to have a large number of people keen to contribute to meta discussion and technical tweaking, and a small number of people actually willing and able to write content. Bulls-eye. When jwz was editor-in-chief and initial creator of www.mozilla.org in 1998, things didn't suck. People with less attention to detail then let the hierarchy erode, checked in files named by StudlyCaps instead of hyphenated-words, and otherwise made incoherent changes (incoherent in large and small ways). Too many cooks. And you're absolutely right that there are always at least ten times as many people willing to tweak than to do the initial heavy lifting. And probably 100 times as many people willing to spout off without carrying weight ;-). So again: I'm looking for volunteers to be editor-in-chief. I expect DevMo's editor-in-chief to rule with an iron fist, in a velvet glove. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: When jwz was editor-in-chief and initial creator of www.mozilla.org in 1998, things didn't suck. People with less attention to detail then let the hierarchy erode, checked in files named by StudlyCaps instead of hyphenated-words, and otherwise made incoherent changes (incoherent in large and small ways). Too many cooks. I'm not excluding myself here, btw. I've made stupid hierarchy decisions, and favored expediency over coherence, in my past website dealings. But I want to do better, especially with DevMo. Anyway, didn't want to sound like I was harshing on others and exempting myself. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: As you indicated translations, should they happen on the same site, if ever? Should we try to be ready to get them in now? That's why I proposed, in shameless imitation of msdn except for the name, a Worldwide item on the link toolbar. That would lead to an index page of links to various localizations. Should the localizations be hosted at developer.mozilla.org? I think so, for the same reason we want to "stand alone" if necessary for XUL docs. That does mean we need assistant editors who speak various languages and can help the editor-in-chief run a tight ship across many localizations. also, many l10n projects don't have their own independent site, or they cannot handle a large volume of traffic. Having some place to host translation would ease the pain. Question: do DevMO/l10n have to be exact translations (e.g. can l10n pages have different index pages, like on MS site)? ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: Question: do DevMO/l10n have to be exact translations (e.g. can l10n pages have different index pages, like on MS site)? I'm not sure what's best. Can you say more about why the MSDN localizations have different index pages and possibly other structure? /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: Axel Hecht wrote: <...> As you indicated translations, should they happen on the same site, if ever? Should we try to be ready to get them in now? That's why I proposed, in shameless imitation of msdn except for the name, a Worldwide item on the link toolbar. That would lead to an index page of links to various localizations. Should the localizations be hosted at developer.mozilla.org? I think so, for the same reason we want to "stand alone" if necessary for XUL docs. That does mean we need assistant editors who speak various languages and can help the editor-in-chief run a tight ship across many localizations. From our (kinda limited) experience with the www.mozilla-europe.org site, having concurrent localized versions of a website puts quite some management task on the iron fist. And forget about that velvet glove ;-). Anyway, we most definitly don't want to start with translations, I'd say. Localizers should be able to get a grip on what needs translation, and that requires a halfway-live site. But. If the site should be ready to get localized, internal links should be made up right from the start. This requires a settlement on the URL scheme as well as a policy about linking to other pages, shared images and localized images. We at mozilla-europe.org use a scheme that goes like www.mozilla-europe.org/lang/dir/ec/to/ries/file.html. We don't use absolute links at all, so that translations can reuse links more easily. So the question would be, do we wanna go for a top-level lang dir, do we wanna use Gerv's redirect magic [1], too? In the scenario of having both /dir and /en/dir pointing to the same resource, we need to care about links even more. Axel [1] http://www.gerv.net/hacking/language-selection/ ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: Clover wrote: Question: do DevMO/l10n have to be exact translations (e.g. can l10n pages have different index pages, like on MS site)? I'm not sure what's best. Can you say more about why the MSDN localizations have different index pages and possibly other structure? If you go to microsoft site or MSDN, and then to the Taiwan version, you won't find any file-to-file relationship. The Taiwan pages have very different layout. The English version and Taiwan version have similar file structure, but they have diffierent articles. For example, on MSDN Taiwan you can see articles written by Taiwanese (which aren't translated to English). I would suggest the following editing rules: - Every article must be reviewed for grammar, spelling, readability etc. - All articles have to be complete - Every article must have a publish date - Every article should indicate what version of software it is applicabel to - We accept non-trivial content updates - updated page must have a Update Date - details need to be reviewed for version applicability - Links can be added, removed, updated without changing the document date. - We will NOT accept grammar and spelling changes In general, we would ensure that all docs have print, professional quality. This would have the following advantage: - Translators can translate a page and be done with it. S/he doesn't have to watch the doc - We don't have to review and update every page whenever we roll out a new software version. The Date and Version fields would imply if a doc is still relevant. - We encourage people to write more - We stop wasting time on old docs. If they are obsolete, and updating the doc takes no trivial effort, we can just give up on the doc. - People sometimes file bug reports that a doc refers to a software that has a new version and the version/link needs to be updated. This is silly; we shouldn't try make sure everything is up-to-date to minute details. - Most doc writers don't have time to maintain their own docs. This relieve them from such obligation - All doc writers can go on a summar vacation and the site will still run smoothly. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
I've been reading the discussion with interest, and want to layout some ideas for structure/metadata/organization: We have roughly two different types of content that I'm aware of: reference material, and "articles". REFERENCE MATERIAL Reference material, e.g. the MSDN "DHTML Reference" at http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/dhtml_reference_entry.asp, includes DOM/HTML/XUL/SVG documentation, XPCOM interface documentation (both frozen and non-frozen), xpinstall API reference, etc. This material has the following characteristics: * It needs constant updating as mozilla adds support for new DOM/etc specifications. * It needs to be deeply and widely cross-referenced. * We want to keep historical information available (e.g. mozilla started supporting document.load() in release x.x, and XMLHttpRequest in release y.y. Doron and I discussed this, and I think we are approaching consensus. The references for the following material would be kept in flat files in a custom XML format: DOM (doron has a plan for these docs, I understand) > HTML > CSS > XML > XUL > MathML > XBL > SVG > XPInstall XPConnect XSLT The spidermonkey and NSPR APIs might be future candidates for this treatment, but they already have reference material and an update strategy, so let's not mess with them yet. This XML format would include a title, a freetext (xhtml) description, freetext remarks, basic example code, and a well-defined list of properties, methods, events, etc. It would also include standards information, if applicable. Cross-references would be in a semi-absolute format (for example ) that would be transformed into a fully-qualified URI reference during the publication stage. This XML format can then be transformed (using XSLT) into a displayable format for the website. I was interested in the translation questions that were raised. I think that for the time being, unless an foreign editor steps forward, this information will be English-only. However, when the time comes that we want to translate the information, I don't think we should fork the source file; instead, we will extend the XML format a bit, to allow for the freetext sections to occur in multiple languages. Because the format is well-defined, using XSLT to accomplish the transformations is easy and allows for future expansion with little effort. It is my opinion that these files should be kept in a CVS or subversion repository (and we have experience with CVS, so I agree with brendan: KISS, and we can always move to something else later). An automatic updater (cron job) will transform the files into the proper HTML format for the website, similarly to the way we build the mozilla.org website currently. As for the maintenance of this reference material: it is my opinion that mozilla hackers should be *required* to update this material as they make changes to the underlying APIs. Superreview should not be granted without corresponding API updates. The lead editor should have the power to "crack the whip" for non-compliant developers. The CVS repository should have anonymous-read access, so that any developer can easily create patches against it. CVS write access would be available to anyone with regular cvs.m.o access, and a single-review process should be established, with an editor and a short-list of peers. ARTICLES article: a many-paragraph text, with (optional) attached code samples, diagrams, and supporting files. An article may be a "howto", sample code, overview, or other document. Articles have very different editorial requirements than the reference material above: I see the immediate need for a CMS-like workflow solution, so that articles don't get bogged down: 1) anyone may submit an article for consideration. Articles may be submitted in any language (although if we don't have an editor for that language, we might be in trouble). Articles should be in html, and use a well-defined set of CSS classes from a standard stylesheet, so that there is graphical consistency. There should be a style+grammar guide for consistency. All code samples and figures/images should be included in the submission. The submitted must agree to whatever licensing scheme is chosen. 2) a group of "peer editors" may accept with edits, suggest resubmission with changes, or reject the article outright. Ideally, the article would have feedback within 4-7 days. Peers should run the doc through a basic editing checklist including making sure that code samples actually compile/work, etc. 3) Once an article is accepted, experienced mozilla coders (module owners, peers, superreviewers) would review the doc for accuracy. This shouldn't be a serious time-consumer; most docs should take 5-10 minutes to check. Again, feedback would occur within 4-7 days. These can also make edits directly, or ask the article author to make edits. 4) The "lead editor" publishes the document. Thi
Re: developer.mozilla.org thoughts
Benjamin D. Smedberg wrote: I've been reading the discussion with interest, and want to layout some ideas for structure/metadata/organization: We have roughly two different types of content that I'm aware of: reference material, and "articles". I think that's probably too simplistic, see me post "DevMo Guideline Proposal" REFERENCE MATERIAL Reference material, e.g. the MSDN "DHTML Reference" at http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/dhtml_reference_entry.asp, includes DOM/HTML/XUL/SVG documentation, XPCOM interface documentation (both frozen and non-frozen), xpinstall API reference, etc. This material has the following characteristics: * It needs constant updating as mozilla adds support for new DOM/etc specifications. * It needs to be deeply and widely cross-referenced. * We want to keep historical information available (e.g. mozilla started supporting document.load() in release x.x, and XMLHttpRequest in release y.y. I agree that the developers should keep the documents up to date, but I think the document should only be published for each public release of the software and older reference docs should remain online. In other words, the maintenance of the document should not necessarily be part of the CMS. ARTICLES article: a many-paragraph text, with (optional) attached code samples, diagrams, and supporting files. An article may be a "howto", sample code, overview, or other document. Again, I think that there are different types of documents based on purpose, content, need for review, etc. 1) anyone may submit an article for consideration. Articles may be submitted in any language (although if we don't have an editor for that language, we might be in trouble). Articles should be in html, and use a well-defined set of CSS classes from a standard stylesheet, so that there is graphical consistency. There should be a style+grammar guide for consistency. All code samples and figures/images should be included in the submission. The submitted must agree to whatever licensing scheme is chosen. 2) a group of "peer editors" may accept with edits, suggest resubmission with changes, or reject the article outright. Ideally, the article would have feedback within 4-7 days. Peers should run the doc through a basic editing checklist including making sure that code samples actually compile/work, etc. 3) Once an article is accepted, experienced mozilla coders (module owners, peers, superreviewers) would review the doc for accuracy. This shouldn't be a serious time-consumer; most docs should take 5-10 minutes to check. Again, feedback would occur within 4-7 days. These can also make edits directly, or ask the article author to make edits. Using the document categories I suggested in my post, steps 2 and 3 should not be necessary for "Articles", "Tutorials" or "White Papers" because they are "contributed unofficial documentation". Nevertheless, the editor may wish to be able to add comments to these types of documents. 4) The "lead editor" publishes the document. This includes assigning the document a place in the website hierarchy and linking it from other places as necessary. The lead editor is also responsible for "see also" links 5) Users of the document may comment on it, just like xulplanet's comment feature. Tutorials and Articles yes, Tech Notes and White Papers no. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: "Moz" and "MS" are quite similar really... I mean, would we be happy if someone brought out a new browser called MSzilla? :) We probably wouldn't object. There are lots of "zilla" names already. But Toho (owners of the Godzilla mark) might. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Proposal: we have our own look, but with similar bars along the top: - highest has some few right-justified items to get to www.mozilla.org and a sitemap; - next has a gradient and a left-justified "DevMo" logo, or something as simple yet attractive and even more distinctive; - lowest/most-used toolbar has: DevMo | Topics | Library | Downloads | Samples | Subscriptions | Worldwide Sounds fine, except categories would do well to be driven by readers. Library is where I think we should start building first and fastest. Hmm. Reference material isn't a big reader drawcard, and takes a long time to create. We could chuck up what we already have and then focus on better titbits. We will hope to get to the point of having so many articles, and such a stream of fresh ones, that we can or must do likewise, but for now, it seems better to me for us to have docs organized in a fairly flat category tree that organizes and includes at least: > DOM (doron has a plan for these docs, I understand) DOM Inspector > ... Eek. Eek. Readers First. These are all subcategories for readers who want reference material. We definitely want tutorials organized by hot "How do I do X?" questions and scenarios. Guides and other longer docs that cover larger APIs and sets of APIs are needed. Written for beginners? For experts? For Uni Students? For teachers? For who? Architecture and user-interface laundry-list: - Need a graphical design strawman or mock-up that we can all nitpick into shape and agree on, soon. Yay. That's fun. - How do we want to generate or otherwise maintain docs with consistent style elements, toolbar headers, etc.? The content part is words (and code) for most one-off pieces. You just fill a template with words and code in one spot. Anything else is server-side includes. Maybe you have to split the article across a few pages by hand. There's always special cases, like the keyboard map page. But mostly you just cut'n'paste the content in. Maybe you have a Perl script that takes the plain text and hacks it a bit before you paste. - Do we want a wiki front end? Shaver has argued that we do, based on his recent experience. For one class of readers. It's a community forum / community service. It's not for everyone. - What should we use for the repository? CVS is easy for us to set up, and a known quantity with admin support (http://despot.mozilla.org/). I voted elsewhere for something like a CMS that can give a document a number rather than a path (paths contain a hardcoded hierarchy). - We have doctor (the "edit this page" link at the bottom of every page on http://www.mozilla.org/) for easy update -- but someone, as Asa said, should really extend doctor to use Mozilla's content-editable support. Myk? Only needed for docs with long review cycles; mostly reference. Needed there, though. Note that OpenOffice/Word allows two copies of a draft with different comments to be merged into one. So it doesn't have to be done server-side. - Should we let programmers use doc-comments to write primary API document source, and extract it via a javadoc style tool that grovels over the source tree, compiling XML or HTML from the extracted comments and their context? I think so. Just ask Neil Deakin for his xulplanet gear, then. It would be better to give the reader a fishing rod than a fish: explain how to read XPIDL. It would be great to encourage extra documentation in .idls, and reflect the lot to the Web. - Should we implement an idea of Ben Goodger's, doc-comment tags of some kind to bracket "best practice" or otherwise canonical examples? Again, the idea is to let programmers keep primary doc source in the code, where it is less likely to rot. Any documentation generated by developers is nice to have, but in my view, implementation notes are the best use of core developer time on docs. There's another tier of people who can take that info and produce examples, etc. There needs to be a medium where those implementation notes can be announced, eg to mozillazine. - Lxr queries linking API interface and method names to their uses. - Benjamin Smedberg has good experience and ideas on how the back end and an initial HTML front end should work, what the meta-data should be accompanying the documentation data, etc. Benjamin, please comment when you have the time. Nothing beats a lovingly crafted hand woven basket ;-) These things would help content providers write better articles for sure, though. - N. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Fred wrote: Benjamin D. Smedberg wrote: I've been reading the discussion with interest, and want to layout some ideas for structure/metadata/organization: We have roughly two different types of content that I'm aware of: reference material, and "articles". I think that's probably too simplistic, see me post "DevMo Guideline Proposal" REFERENCE MATERIAL Reference material, e.g. the MSDN "DHTML Reference" at http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/dhtml_reference_entry.asp, includes DOM/HTML/XUL/SVG documentation, XPCOM interface documentation (both frozen and non-frozen), xpinstall API reference, etc. This material has the following characteristics: * It needs constant updating as mozilla adds support for new DOM/etc specifications. * It needs to be deeply and widely cross-referenced. * We want to keep historical information available (e.g. mozilla started supporting document.load() in release x.x, and XMLHttpRequest in release y.y. I agree that the developers should keep the documents up to date, but I think the document should only be published for each public release of the software and older reference docs should remain online. In other words, the maintenance of the document should not necessarily be part of the CMS. Why only release new documents with new actual releases? Lots of development (both internal and external) goes on between releases, and the docs should, if possible, reflect the current state of play. Extensiion developers, for example, often try to keep up with changes in nightly builds so that, when the next major release comes along, the extension is already working. It would be fantastic if there was some magic way to get a version of a doc as it applied to some particular release; if the docs are stored in a made-up XML format, that should be quite possible by introducing some attribute which indicates which release a particular piece of text applies to. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: Brendan Eich wrote: Clover wrote: Question: do DevMO/l10n have to be exact translations (e.g. can l10n pages have different index pages, like on MS site)? I'm not sure what's best. Can you say more about why the MSDN localizations have different index pages and possibly other structure? If you go to microsoft site or MSDN, and then to the Taiwan version, you won't find any file-to-file relationship. The Taiwan pages have very different layout. The English version and Taiwan version have similar file structure, but they have diffierent articles. For example, on MSDN Taiwan you can see articles written by Taiwanese (which aren't translated to English). I would suggest the following editing rules: way too many. - Every article must be reviewed for grammar, spelling, readability etc. - All articles have to be complete They will most likely never be. - Every article must have a publish date - Every article should indicate what version of software it is applicabel to That doesn't get us around documenting other versions, though. - We accept non-trivial content updates - updated page must have a Update Date This stuff should be part of the CMS. Don't try to put up rules for stuff that software should handle fine. - details need to be reviewed for version applicability - Links can be added, removed, updated without changing the document date. - We will NOT accept grammar and spelling changes Why (for the last two)? Grammar and spelling fixes may be annoying, but what good does it do to have bad english? Note that significant parts of these documents will be written by people with a non-english mother language. Keep it real. In general, we would ensure that all docs have print, professional quality. This would have the following advantage: - Translators can translate a page and be done with it. S/he doesn't have to watch the doc Translators shouldn't have to watch a doc, they should get notified. But again, don't put up rules that software should take care of. Oh, and don't put up rules for vapourware. AFAICT, we're not excluding translated versions of the documents so far, but we're not planning on having them soon. - We don't have to review and update every page whenever we roll out a new software version. The Date and Version fields would imply if a doc is still relevant. Versioning of docs is a tough question and should probably be decided by drivers. I see three or four targets: - trunk - latest stable - 1.4 (which is latest API/embedding-stable) - 1.0 (did we deprecate this one? It'd be hell to document that. But 1.4 won't be that much easier.) - We encourage people to write more - We stop wasting time on old docs. If they are obsolete, and updating the doc takes no trivial effort, we can just give up on the doc. This should be decided on a case by case basis by the iron fist. No rules for stuff like this. - People sometimes file bug reports that a doc refers to a software that has a new version and the version/link needs to be updated. This is silly; we shouldn't try make sure everything is up-to-date to minute details. - Most doc writers don't have time to maintain their own docs. This relieve them from such obligation - All doc writers can go on a summar vacation and the site will still run smoothly. Axel ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Benjamin D. Smedberg wrote: I've been reading the discussion with interest, and want to layout some ideas for structure/metadata/organization: We have roughly two different types of content that I'm aware of: reference material, and "articles". REFERENCE MATERIAL Reference material, e.g. the MSDN "DHTML Reference" at http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/dhtml_reference_entry.asp, includes DOM/HTML/XUL/SVG documentation, XPCOM interface documentation (both frozen and non-frozen), xpinstall API reference, etc. This material has the following characteristics: * It needs constant updating as mozilla adds support for new DOM/etc specifications. * It needs to be deeply and widely cross-referenced. * We want to keep historical information available (e.g. mozilla started supporting document.load() in release x.x, and XMLHttpRequest in release y.y. Doron and I discussed this, and I think we are approaching consensus. The references for the following material would be kept in flat files in a custom XML format: DOM (doron has a plan for these docs, I understand) > HTML > CSS > XML > XUL > MathML > XBL > SVG > XPInstall XPConnect XSLT The spidermonkey and NSPR APIs might be future candidates for this treatment, but they already have reference material and an update strategy, so let's not mess with them yet. This XML format would include a title, a freetext (xhtml) description, freetext remarks, basic example code, and a well-defined list of properties, methods, events, etc. It would also include standards information, if applicable. Cross-references would be in a semi-absolute format (for example ) that would be transformed into a fully-qualified URI reference during the publication stage. This XML format can then be transformed (using XSLT) into a displayable format for the website. I was interested in the translation questions that were raised. I think that for the time being, unless an foreign editor steps forward, this information will be English-only. However, when the time comes that we want to translate the information, I don't think we should fork the source file; instead, we will extend the XML format a bit, to allow for the freetext sections to occur in multiple languages. Because the format is well-defined, using XSLT to accomplish the transformations is easy and allows for future expansion with little effort. Try to not do giga-huge files with all kind of content inside. It makes versioning hard, and I'd prefer to have localizers mess with their own copy instead of potentially horking the original english version. IMHO, its better to have a file per language. It is my opinion that these files should be kept in a CVS or subversion repository (and we have experience with CVS, so I agree with brendan: KISS, and we can always move to something else later). An automatic updater (cron job) will transform the files into the proper HTML format for the website, similarly to the way we build the mozilla.org website currently. One of the things that I dislike about the mozilla.org website is the lag between check-in and publishing. I favour doing stuff in cvs checkin scripts, though even that is a bit tricky at times. (esp for cross directory check ins.) As for the maintenance of this reference material: it is my opinion that mozilla hackers should be *required* to update this material as they make changes to the underlying APIs. Superreview should not be granted without corresponding API updates. The lead editor should have the power to "crack the whip" for non-compliant developers. The CVS repository should have anonymous-read access, so that any developer can easily create patches against it. CVS write access would be available to anyone with regular cvs.m.o access, and a single-review process should be established, with an editor and a short-list of peers. ARTICLES article: a many-paragraph text, with (optional) attached code samples, diagrams, and supporting files. An article may be a "howto", sample code, overview, or other document. Articles have very different editorial requirements than the reference material above: I see the immediate need for a CMS-like workflow solution, so that articles don't get bogged down: 1) anyone may submit an article for consideration. Articles may be submitted in any language (although if we don't have an editor for that language, we might be in trouble). Articles should be in html, and use a well-defined set of CSS classes from a standard stylesheet, so that there is graphical consistency. There should be a style+grammar guide for consistency. All code samples and figures/images should be included in the submission. The submitted must agree to whatever licensing scheme is chosen. 2) a group of "peer editors" may accept with edits, suggest resubmission with changes, or reject the article outright. Ideally, the article would have feedback within 4-7 da
Re: developer.mozilla.org thoughts
Benjamin D. Smedberg wrote: As for the maintenance of this reference material: it is my opinion that mozilla hackers should be *required* to update this material as they make changes to the underlying APIs. Superreview should not be granted without corresponding API updates. The lead editor should have the power to "crack the whip" for non-compliant developers. Wasn't there a blip of a thought on using the javadoc comments, which the developers _should_ be updating or writing as needed, for this? I would much prefer that, personally, since it keeps the comments with the code and prevents documentation skew (the website saying one thing while the IDL says another). If the javadoc comments are not detailed enough (as they usually are not), we need to decide whether to make them more detailed or whether to require documenting on the website additional to the creation of javadoc comments (eg usage examples, etc). -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: Benjamin D. Smedberg wrote: As for the maintenance of this reference material: it is my opinion that mozilla hackers should be *required* to update this material as Wasn't there a blip of a thought on using the javadoc comments, which the developers _should_ be updating or writing as needed, for this? I There was. But unfortunately, there is no obvious way to map our interfaces to actual DOM objects. Javadoc doesn't work for properties/methods implemented in XBL. Javadoc only covers methods/properties, it doesn't deal with DOM attributes. Finally, we need to keep historical information about when various properties were added. I wouldn't mind extracting what I can from javadoc, but it's far from sufficient. --BDS ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Benjamin D. Smedberg wrote: There was. But unfortunately, there is no obvious way to map our interfaces to actual DOM objects. Sure. For DOM, things are a little different (and we don't javadoc our DOM interfaces because that would simply repeat what the spec says). I guess I was talking more about embedding APIs. The versioning problem still exists there, though But that can be solved by simply creating the "latest" version based on javadoc (say daily) and snapshotting it at release time so you can always look up what the API looked up in a particular release. -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: Benjamin D. Smedberg wrote: There was. But unfortunately, there is no obvious way to map our interfaces to actual DOM objects. Sure. For DOM, things are a little different (and we don't javadoc our DOM interfaces because that would simply repeat what the spec says). I guess I was talking more about embedding APIs. The versioning problem still exists there, though But that can be solved by simply creating the "latest" version based on javadoc (say daily) and snapshotting it at release time so you can always look up what the API looked up in a particular release. Right, this was what I was thinking of too. Mozilla's embedding APIs, broadly construed (not just the stuff under http://lxr.mozilla.org/mozilla/source/embedding/) are defined by IDL. The doc-comments in those files should be as complete, correct, and well-written as we can make them. We could scan for magic comments in XBL and XUL files too -- why not? Proposals? /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: I guess I was talking more about embedding APIs. The versioning problem still exists there, though But that can be solved by simply creating the "latest" version based on javadoc (say daily) and snapshotting it at release time so you can always look up what the API looked up in a particular release. Well... that suggestion gives you interface documentation, indeed. It does NOT give you documentation of contracts, like: 1. who implements this interface, 2. what other interfaces does this implement (that you can rely on), 3. how you should get a component implementing this interface (for example, nsIURI and nsIMIMEInfo should not be created by contractid). ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Christian Biesinger wrote: Boris Zbarsky wrote: Well... that suggestion gives you interface documentation, indeed. It does NOT give you documentation of contracts, like: 1. who implements this interface, 2. what other interfaces does this implement (that you can rely on), 3. how you should get a component implementing this interface (for example, nsIURI and nsIMIMEInfo should not be created by contractid). True. We need contractid documentation in general. #3 could be documented in the IDL itself, though, imo. But yes, we need a way tolink from the interface documentation to the contractid docs... preferably semi-automatically. Perhaps some sort of file that contains such relationships (either in the sourcetree or on the site). -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
"Benjamin D. Smedberg" wrote: > > Articles should be in html, and use a well-defined set of CSS classes > from a standard stylesheet, so that there is graphical consistency. > There should be a style+grammar guide for consistency. We've got a set of classes already; see the mozilla.org style sheet. I need to write an HTML page documenting them, though, because the docbook reference is slightly out of date. Style Guide is at http://mozilla.org/README-style.html For grammar I recommend The Elements of Style. :) > 4) The "lead editor" publishes the document. This includes assigning the > document a place in the website hierarchy I really like the idea of getting the location reviewed... > 5) Users of the document may comment on it, just like xulplanet's > comment feature. Whether or not we go for comments, the document maintainer needs to be *very clear*. If I see an error in the doc, I want to be able to notify that person without having to search CVS logs. In terms of requirements, what I most want to see is a) Clear ownership of *every* document, so one knows who to contact. b) Adding files, especially at the root, locked down so as to require location review. > It may seem that this is over-complicating the matter. If the rules and process are clear, then a little bit of complication is not a problem. If the rules and process are unclear (like they are now), even a minimal set of requirements becomes an obstacle because you have to spend so much time figuring out you're suppose to do. Further thoughts: The primary structure, as reflected in the URI, should imo be *flat* with regards to topic. e.g. /xpcom, /xpfe, /gecko, /dom, /web etc. Sections can link to each other -- for example, /gecko and /web would link to /dom. This is the most forwards-compatible structure, and for URIs that is a major consideration. Several different tocs can then link into this structure, organizing it by alphabet, by artificial hierarchy, or even by format. [1] *The format of the document should not determine its place in the primary structure.* The subject matter should. [1] I wouldn't recommend this method for mozilla.org proper, because that part of the site has more inherent structure than the collection we're trying to amass here. ~fantasai ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: But yes, we need a way tolink from the interface documentation to the contractid docs... preferably semi-automatically. Perhaps some sort of file that contains such relationships (either in the sourcetree or on the site). The contract id doc may contain enough info for that... might require some kind of special formatting. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: > > > All that open source motherhood and apple pie aside, it's vitally > > important that we have an editor-in-chief who will set prose and web > > content style rules, rally writers and other editors to urgent tasks, > > police the prototype site for bugs, and lead in driving the buglist to > > zarro. Volunteers? > > Fantasai's been the voice crying in the wilderness on these issues for > years. I nominate her :-) Eek. Two nominations already! I can review, I can edit, I can do QA. I'm quite willing to help out with those. But... > When jwz was editor-in-chief and initial creator of www.mozilla.org in > 1998, things didn't suck. People with less attention to detail then let > the hierarchy erode, checked in files named by StudlyCaps instead of > hyphenated-words, and otherwise made incoherent changes (incoherent in > large and small ways). Too many cooks. That, I think I can handle. Document organization and style rules, yes. > So again: I'm looking for volunteers to be editor-in-chief. I expect > DevMo's editor-in-chief to rule with an iron fist, in a velvet glove. I don't know about the "ruling with an iron fist" part. I can make a manuscript bleed red ink, in good English-teacher/ code-reviewer fasion, but the ruling part seems to involve telling people what to do and when. And in my experience, I'm really very bad with schedules. So if someone wants to guide the management bit and align my pen with the right velocity vector, I'll can take a copyeditor-in-chief slot or whatever. (bsmedberg seems to have a better grip on processes, imo.) ~fantasai ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: > > Yeah. Strong editors needed, the Wiki is just the front end, and maybe > the patch-tool if Doctor isn't right. I don't like WikiStyle links. They have several problems: a) They can unintentionally create links to non-existant resources. It's especially an issue with code documentation, 'coz we use the StudlyCaps naming convention throughout Mozilla. b) There is *no* inherent URI structure. c) Accessibility. And I don't just mean screen readers, but search engines as well. If we want a structured text parser, reStructuredText[1] is one option. IIRC, it doesn't accept HTML code as input, which may be a problem, but it's become popular for Python docs, and it does have a sophisticated set of constructs. [1] http://docutils.sourceforge.net/ ~fantasai ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael Lefevre wrote: It allows us to give access only to a list of people. That's good enough to start with. Let's not get too fancy yet. The problem is that, if we want to get fancier, we have to write all the code ourselves. Which means it'll probably never happen. True, on the other hand, if it's decided to investigate and implement something else, the whole project will probably never happen. Why does that have to be true? The current explosion of interest and demand for instant activity sounds to me very much like the development team who starts coding as early as possible, instead of designing and planning, because then they seem to be making progress. The key metric is how quickly it gets finished, not how quickly it gets started. If we spend two weeks investigating and picking the most suitable back-end technology, the worst that could happen is that we end up choosing CVS and so have something usable two weeks later. The best is that we choose something which turns out to be a lot more suitable, and reap gains for the lifetime of the project. "Mozilla must use the best open source solution to solve a well-understood problem." - Brendan Eich, original Mozilla Roadmap. Rather taken out of context... he was talking about creating stuff, not actually using it. He's talking about using GTK, if I remember correctly. I _particularly_ didn't mention Zope on purpose - in fact, I said "I don't care which one it is", to prevent old Zope issues clouding the picture. It's two years later, an eternity in Internet time. I'm sure both Zope and it's many competitors have improved a lot since we last looked. But again, if we decide to start looking, we'll be arguing about different systems (no doubt, clouded by much discussion of the Zope incident) for months. Again, why does that have to be true? Brendan says he supports the iron hand in the velvet glove. So let's look around, make recommendations and have our iron-handed supremo make a decision at a particular deadline. CVS is part of the problem, but I don't think it's the biggest part. Even if that's true, that doesn't mean we can't solve that part. If there's a big problem and a small problem, the fact that we have to attack the big one doesn't mean we should do nothing about the smaller one. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Brendan Eich wrote: But first, let's agree that the domain name should be developer.mozilla.org -- Sure. The problem is that, if we want to get fancier, we have to write all the code ourselves. Which means it'll probably never happen. We already have to maintain despot. My (quite possibly incorrect) understanding of despot is that it hasn't really changed for years, and there's not many people around who know the code, which is of the standard that Bugzilla's used to be. Not perhaps the best base for a new fine-grained user management system. Unless you are going to pile future unknown requirements on it, I don't see how we'll fail for want of a better despot. Either we'll limp along, or we'll improve despot -- or later (that's the key -- not right now!) we will lift up the server content on really big jacks, slide out despot and even CVS, and drop the content back down on something better. Later. Why make that work for ourselves then, rather than starting on the right foot now? "Mozilla must use the best open source solution to solve a well-understood problem." - Brendan Eich, original Mozilla Roadmap. Is CVS really the answer to that question for website content management? If it is, why is no-one else using it? What are people using on sites of the same scale as ours? Tell me more, fast. And remember not to multiply risk gratuitously at the front of the schedule. OK. See new root post. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: I would suggest the following editing rules: Every other documentation effort we've made had started with (and usually finished with) decisions on a big set of editing rules. Let's try starting with none and seeing what happens. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Axel Hecht wrote: Please, not. I hate that and I never saw a useful comment in my life. I'm just not old enough for viagra. Honestly, comment systems are spam and maintainance problems and we don't wanna check a few hundred pages for those. Comments bitrot even worse than articles, and you can't be sure that comments are meant to be under the same license that the document is. Plain pain. We can deal with the license and comment spam issues in the obvious ways. I feel that this feature is really valuable - it gives updaters ideas of what bits are unclear, and what updates need doing. I've certainly valued it on the MySQL manual. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
On 2004-03-08, Gervase Markham <[EMAIL PROTECTED]> wrote: > Michael Lefevre wrote: > It allows us to give access only to a list of people. That's good enough to start with. Let's not get too fancy yet. >>> >>>The problem is that, if we want to get fancier, we have to write all the >>>code ourselves. Which means it'll probably never happen. >> >> True, on the other hand, if it's decided to investigate and implement >> something else, the whole project will probably never happen. > > Why does that have to be true? It doesn't have to be true. I'm just guessing it'd probably happen. > The key metric is how quickly it gets finished, not how quickly it gets > started. True (although I'm not sure what "finished" would mean in this context. However, how quickly it gets started obviously has an impact on that "key metric" as well. [snip] >> But again, if we decide to start looking, we'll be arguing about different >> systems (no doubt, clouded by much discussion of the Zope incident) for >> months. > > Again, why does that have to be true? It doesn't have to be true. If the investigating and decision can happen within a set deadline so we don't hold things up indefinitely, that would be good. Call me a pessimist, but I'm predicting that that won't happen even if it is tried, so I don't see much point in trying it. But I'm not running anything here; I'm not even sure I can contribute much to this project, so you don't have to listen to me :) -- Michael ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: We can deal with the license and comment spam issues in the obvious ways. Does that mean that the document maintaner will be able to remove user comments as necessary? -Boris ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: Gervase Markham wrote: We can deal with the license and comment spam issues in the obvious ways. Does that mean that the document maintaner will be able to remove user comments as necessary? Sounds reasonable to me. The comment form would require a login of some sort, and would say something like: "You grant permission for your comments to be used in future revisions of this documentation under the X license. You understand that your comments may be deleted at any time, whether they are incorporated or not." This is not a free-speech-rules discussion board, it's a (hopefully) technically accurate documentation set :-) Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Boris Zbarsky wrote: Christian Biesinger wrote: Boris Zbarsky wrote: Well... that suggestion gives you interface documentation, indeed. It does NOT give you documentation of contracts, like: 1. who implements this interface, 2. what other interfaces does this implement (that you can rely on), 3. how you should get a component implementing this interface (for example, nsIURI and nsIMIMEInfo should not be created by contractid). True. We need contractid documentation in general. #3 could be documented in the IDL itself, though, imo. But yes, we need a way tolink from the interface documentation to the contractid docs... preferably semi-automatically. Perhaps some sort of file that contains such relationships (either in the sourcetree or on the site). The xulplanet XPCOM docs are the best I've seen. We should ask Neil how it's done, and if he'd be willing to help with that part of the project. Don't want to reinvent the wheel. --BDS ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: My (quite possibly incorrect) understanding of despot is that it hasn't really changed for years, and there's not many people around who know the code, which is of the standard that Bugzilla's used to be. Not perhaps the best base for a new fine-grained user management system. FWIW, although archaic, Despot code is (perhaps as a result) fairly easy to grok. -myk ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
I'm coming into this late in the discussion, so I apologize. In any case, I wrote an email to Fabian Guisset, informing him of the work I've been doing at http://aom.nachbaur.com, to which he pointed me to this timely thread. If anyone wants the nitty-gritty of what I said, and/or the laundry list of features the sites sports, then let me know and I'll follow up with more details. Suffice to say, I've been tired of the lack of documentation for the DOM/JavaScript side of Mozilla development, and true to OSS form (e.g. "If you can do it, but don't, then you don't have any right to complain") I set out to remedy the situation. I'm an AxKit fanatic, and am one of the developers on the project (though, IMHO, a lowly one). The site is rendered with AxKit, so site style is easy to maintain, the content is in semantic XML (accessible if you click the "Source Code" boxy icon on the top navbar) and is intended to document all JavaScript-accessible objects in Mozilla. After a bit of poking around to orient myself, I'm documenting ECMA-262. Next will be the W3C DOM, and the Mozilla extensions to it. I have a lot of possible plans for where the project can go, but in the mean-time I'm simply concerned with getting the job done. (For a few of the objects in the site that showcase it's functionality, look at the String, Document, and MenuList objects) I follow the KISS philosophy on this project. I'm not worrying with CMSs, fancy site navigation (though I'm partial to the one I use right now) or anything else that can wait until later. I'm just setting out to get the thing documented. Since the site is built with XSLT, if I ever need to change the content to a more logical layout, or add any functionality, I can just write a stylesheet to convert all the content on the site. Anyway, I feel that I'm beginning to rant/ramble, so anyway, I just wanted to point you all there while I catch up with this newsgroup thread. If anyone wants to contribute, GREAT! So far my plan is to be benevolent dictator on this project, so while I have web-cvs access to the project available at http://cvs.nachbaur.com/cgi-bin/viewcvs.cgi/MozillaAOMReference/, there's no public commit access available yet. If anyone wants to grab their own copy of the site, contribute documentation or anything, and then send it my way for integration into the site, wonderful! The heart of any technology is it's developers, and if they don't have any documentation (or they have to endure the sort of thing I'm having to go through to document it) then you soon will have one of the best pieces of technology on the bottom of the acceptance list. The only reason I've stuck with Mozilla for so long (no flames please) is because a) its really cool and fits with my view of what the web should be, b) it fits really well with AxKit, c) I want to write client-side apps without having to devolve into writing in C, or d) I'm clinically insane and should be stopped. Cheers! Questions, comments, threats or bribes? ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Michael A Nachbaur wrote: Suffice to say, I've been tired of the lack of documentation for the DOM/JavaScript side of Mozilla development, and true to OSS form (e.g. "If you can do it, but don't, then you don't have any right to complain") I set out to remedy the situation. Netscape DevEdge maintains many web developer docs. mozilla.org has some, but they are mostly (if not all) from former Netscape employees. mozilla.org doesn't have enough people interested in writing Web developer docs. Have you looked at WiKi's? We people at the Taiwanese Mozilla user community have only recently started serious documentation/translation effort and we are making great progress. We are using a discussion forum hosted by the localization project and two (hijacked) WiKi's. We haven't got any rule. Just efforts. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
At the Moz Dev Day there seemed to be considerable interest in creating XUL-Based apps. More easy-to-find, easy-to-understand documentation regarding the DOM/JavaScript side should be made available. Either that or the creation should be made easier. That is why, IMHO, perl is so popular. Doing this would make Moz a more popular platform for Remote Apps. Clover wrote: Michael A Nachbaur wrote: Suffice to say, I've been tired of the lack of documentation for the DOM/JavaScript side of Mozilla development, and true to OSS form (e.g. "If you can do it, but don't, then you don't have any right to complain") I set out to remedy the situation. Netscape DevEdge maintains many web developer docs. mozilla.org has some, but they are mostly (if not all) from former Netscape employees. mozilla.org doesn't have enough people interested in writing Web developer docs. Have you looked at WiKi's? We people at the Taiwanese Mozilla user community have only recently started serious documentation/translation effort and we are making great progress. We are using a discussion forum hosted by the localization project and two (hijacked) WiKi's. We haven't got any rule. Just efforts. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Clover wrote: > Michael A Nachbaur wrote: > >> Suffice to say, I've been tired of the lack of documentation for the >> DOM/JavaScript side of Mozilla development, and true to OSS form (e.g. >> "If you can do it, but don't, then you don't have any right to complain") >> I set out to remedy the situation. > > Netscape DevEdge maintains many web developer docs. mozilla.org has > some, but they are mostly (if not all) from former Netscape employees. > mozilla.org doesn't have enough people interested in writing Web > developer docs. I have found plenty of documentation on XUL, and some that documents JavaScript access to the DOM in Mozilla, but there is much more undocumented than otherwise. Additionally, the documentation out there for JavaScript is mainly for the HTML DOM, not for the W3C DOM. I've already found several instances in my documentation effort where I am / seem to be the first to document those features of the W3C DOM. *shrug* ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
c tanner wrote: > At the Moz Dev Day there seemed to be considerable interest in creating > XUL-Based apps. More easy-to-find, easy-to-understand documentation > regarding the DOM/JavaScript side should be made available. Either that > or the creation should be made easier. That is why, IMHO, perl is so > popular. Doing this would make Moz a more popular platform for Remote > Apps. I agree. That is the main reason why I'm interested in Mozilla+XUL. I'm a web developer by trade, writing complex intranet applications for vertical markets (currently in the broadband ISP arena). The limitations of DHTML are staggering, and the alternative to going with Mozilla is to drop the flexible web development paridigm and go back to a Perl/Tk or Perl/wxWindows interface. I feel the documentation currently available for XUL is excellent. What I feel is lacking is the DOM/JavaScript docs. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
At the Moz Dev Day there seemed to be considerable interest in creating XUL-Based apps. More easy-to-find, easy-to-understand documentation regarding the DOM/JavaScript side should be made available. Either that or the creation should be made easier. That is why, IMHO, perl is so popular. Doing this would make Moz a more popular platform for Remote Apps. It's more than that, too. Mozilla is somewhat isolated from other programming technologies at the moment. d.m.o needs to build bridges from what people know to Mozilla. Now that we're seeing libraries like PHP/PEAR's XUL modules, there's opportunity for PHP peple to participate in Mozilla in a way that makes sense for what they already know. We can help with that. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
I agree with the focusing on XUL apps and extensions. There is a lot of potential growth in this area, and it is a place that Mozilla can have a good niche. Brendan Eich wrote: As I just posted recently, I continue to think DevMo's emphasis should be on XUL app and extension developers, with other areas (core C++ code, C++ or other XPCOM component writing, web page development, etc.) coming in at lower priority as contributors deem appropriate. DOM docs are good for XUL development, for sure. But DevMo need not recapitulate the contents of existing, cross-browser web devlopment resource sites, and should not put that cart ahead of the horse. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Gervase Markham wrote: Why make that work for ourselves then, rather than starting on the right foot now? Because we don't know what the right foot now is, and we can stumble far without having to decide. Worse Is Better. There's a ton of risk in reading CMS hype, hearing some fans raving, and jumping on the bandwagon -- only to find we bought a lemon after paying up front, or running into a brick wall too soon. Whatever we use has to be hackable. Oops, myk has anticipated my invocation of Richard Gabriel, and also come down on the side of hackability. I'll defer to his post following up your new thread root: news://news.mozilla.org:119/[EMAIL PROTECTED] /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Whatever we use has to be hackable. The benefit of even a trivial CMS is that we can hack at the content level, not at the infrastructure level. My thought is that a CMS should be used in a no-brainer way, not in a fancy way. You don't need to be a DB guru to use MySQL, and the same is true of a simple CMS. Just install it and run it; don't get sucked into complicated uses. The benefit you get with an RDBMS is that you can stop thinking about code and start modelling data. The same is true of a CMS, you can stop thinking about implementation, and start thinking about content. If you want a "fast and wrong" start, then let's be fast and wrong in the right ballpark: content. That requires no code or infrastructure, just a static and trivial website with a weekly review of logs to see what readers are attracted to. Styling unnecessary; navigation minimal. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Nigel McFarlane wrote: Whatever we use has to be hackable. The benefit of even a trivial CMS is that we can hack at the content level, not at the infrastructure level. My thought is that a CMS should be used in a no-brainer way, not in a fancy way. You don't need to be a DB guru to use MySQL, and the same is true of a simple CMS. Just install it and run it; don't get sucked into complicated uses. Sorry, Murphy was an optimist. I mean hackable at the infrastructure level, because things go wrong there and you have to fend for yourself. Otherwise we could buy at MS and trust in a support contract (and wait by the phone). No opaque database formats. Text files are better; Unix philosophy wins. If you want a "fast and wrong" start, Worse is better is not fast and wrong. They're totally different things. Have you read http://www.jwz.org/doc/worse-is-better.html ? then let's be fast and wrong in the right ballpark: content. That requires no code or infrastructure, just a static and trivial website with a weekly review of logs to see what readers are attracted to. Styling unnecessary; navigation minimal. Navigation, or rather search and multiple indexes, is necessary. Styling should be attractive as you say, but that takes work. Default flat-document text style is not enough. /be ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
No opaque database formats. I'm not recommending opacity, I'm recommending bang-for-effort. All RDBMSes support import/export utilities, just as object formats can be decompiled. (but this isn't about DBs so let's drop that). For the record, I'm against an opaque CMS and for plain text files (for storage). I'm in favour of a CMS from the point of view of tracking content by id's rather than by URLs or paths. I even don't care if those id's appear in URLs or paths, just as long as there's a radically flat collection of content items that can be grouped/linked as we see fit. Today I want article X to be a beginner's article. Tomorrow I want it to be an XBL article. The day after it needs to be both. Eventually it's an embarassment and needs to disappear into archives. Then it's suddenly a "Top Ten of all time". That requires some form of flexible aggregration technology that benefits from some kind of permanent object tracking. I don't want to have to re-sort the hierarchy, or to track down "forgotten" pieces. I want to be able to manage my inventory of content. Have you read http://www.jwz.org/doc/worse-is-better.html ? I'm familiar with those problem solving strategies. We're not building a VLSI chip here, though. There's big blocks to play with too: Apache is the obvious example. Navigation, or rather search and multiple indexes, is necessary. Styling should be attractive as you say, but that takes work. Default flat-document text style is not enough. Sure, necessary I agree, but not first. Follow the logic of "worst thing": There should be a week of d.m.o being just this one page: Give me references! Give me tutorials! Give me articles! Give me opinion! Give me anything new! At least the next-least-worst iteration will provide something closer to what the readers want. Nothing trumps what the readers want, not navigation, not styles, and not infrastructure. Without the readers, there's nothing. And the readers primarily want content. We'd bust our carefully debated navigation and styles to pieces if we discovered that doing so would triple the hits. Might as well start right there and say "what brings hits", rather than debating structure/infrastructure in an info-vaccuum. I'm for putting this page, or something real close, straight up, while we sort out a trivially simple CMS *strategy*. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts
Here's my shopping list of technology-independant wants for a CMS. 1. Tracking of content pieces by unique id. Basic inventory management. 2. No implicit structure in storage of content pieces. Basic design freedom to slap navigation, hierarchy, aggregation and miniportals on top of content for a special event or for the next millenia. 3. Separation of public interface from editorial interface. d.m.o is an output of editorial, not entangled with it. Add content via the back-door. 4. Simple file formats for submissions. Force non-layout, non-style contributers to focus on their words and examples. 5. Enough file formats to be practical. Encourage contributors to contribute. 6. 80% of versioning pushed out into contributor land. Don't micro-manage versions of content that isn't fit for readers to see. Some special cases. 7. Support reader feedback. Capture comments by readers on what they've read. 8. No-brainer processes. It should be trivial to use. 9. Web log analysis tools. What content are readers reading? - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - About Readers
Yay! Something I know about. I've read a lot of the discussion on DevMo here, and there are many great thoughts on technology and structure. Following best practice is a great idea; if MSDN's structure is that best practice, then let's follow it. Yay. If you look at any publication, the paper and index, or the equivalent bits, are the least of the problem. It's defining the audience, their needs, and their wants that is the majority of the problem. When we look at MSDN, we don't get to see that picture; we just see 90 minutes of movie in the can. This conversation should be a lengthy "them" conversation, not a "we" conversation. You live or die by reaching "them". Suppose it turns out that 80% of readers are into Orange. Well, then 80% of the portal's front page should be about Orange and Mozilla. It's as simple as that. You don't want to spend 6 months of time and energy only to discover that. So I say: Yay! there's lots of nice technology to use. Let's use it *after* we've got audience focus. I would like to see bugs describing a situation that a potential reader finds him/herself in. I would see bugs describing reader groups and their issues. I would like to see a person for each audience, A person who says: "I care about these specific readers and their issues, and I'll use whatever technology it takes to find and get content to them on a regular basis". That's a sub-editor/assistant editor role. Publishing is a really fragile business, highly prone to failure. In the US, 5000 publishers go out of business every year. The technology needed to print or upload content is trivial compared with the problem of successfully understanding readers. What collaborative tools should we use to capture who the readers are and what they want? A meta bug for "reader profiles" would be a good start. A way of accepting URLs from people that helps us keep up-to-date with our audiences and their issues would be great too. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
I believe readers should come first, but there's no reason to halt on technology investigations. Those enthusiastic about pure technologies have time to trial them and build up something while we find readers. Whatever it is, the tech should be free of implicit structure, so that when DevMo's priorities change in a year, content can be moved around with minimum hassle. We should be able to rip down any part of the HTML navigation if we want to. We should be able to restyle and relayout from the ground up if we want to. Changing market conditions, strategic changes in reader perceptions, these are very important things to flexibly support. Otherwise you lose readers. I think that means we have to look beyond adirectory hierarchy. I vote for a CMS, and I think we could benefit greatly from a relationship with the Zope people, who already have Mozilla advocates and technologists. They want an XUL-based management interface to Zope. There are multiple reasons why us-using-them and them-using-us would make good promotional sense. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - Cross Browser.
Someone said: Should we do Cross Browser stuff or not? If it's a hot issue that impacts on the success of Mozilla and draws readers, then why not? - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
Nigel McFarlane wrote: > > Those enthusiastic about pure technologies have time to trial them > and build up something while we find readers. Whatever it is, the tech > should be free of implicit structure, so that when DevMo's priorities > change in a year, content can be moved around with minimum hassle. No moving around content every year. Will drive anyone using the site up the wall. If I've found useful stuff in some corner of the site, I don't want to have to re-find it every six months or so, and I don't want the search engines wiping off their score sheets, either. ~fantasai ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
fantasai <[EMAIL PROTECTED]> wrote in message news:<[EMAIL PROTECTED]>... > No moving around content every year. Will drive anyone using the > site up the wall. If I've found useful stuff in some corner of the > site, I don't want to have to re-find it every six months or so, > and I don't want the search engines wiping off their score sheets, > either. > > ~fantasai here's a great article (imo) i came across one day. the title is "Cool URIs don't change" and it's by Tim Berners-Lee http://www.w3.org/Provider/Style/URI the main points of the article are: urls should never change. you can move the files anywhere you want, but the urls should be consistent. and the urls should be human readable and human guessable. a topic for another post: see http://www.php.net/urlhowto.php ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
A piece should have a fixed URL, just like the example you cite. It's the question of how URLs are aggregated that interests me. If links are hierarchical URLs, like d.m.o/a/b/c/d/e/article5.html then the aggregated pages are hardcoded in the hierarchy. I'd rather see that avoided. I prefer: important page: http://d.m.o/subjects.cgi?miniport=0023 aggregates links: http://d.m.o/articles.cgi?ref=1245 http://d.m.o/articles.cgi?ref=1532 http://d.m.o/articles.cgi?ref=0032 If miniport 0023 goes out of date, just replace it with 0024, which has the same title, but which is linked to in place of 0023. 0023 then goes into the archive. regards, Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
Nigel McFarlane wrote: important page: http://d.m.o/subjects.cgi?miniport=0023 This rather fails the "guessable" test, doesn't it? Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
[EMAIL PROTECTED]@PLEASEyahoo.com wrote: here's a great article (imo) i came across one day. the title is "Cool URIs don't change" and it's by Tim Berners-Lee http://www.w3.org/Provider/Style/URI If I begin with a FAQ of 10 questions, then it grows to 50, and then to 100... so I split the FAQ into separate files. At the end of the process, all questions in misc.html are moved to the appropriate file. Now, does it make sense for me to keep the misc.html URI? It would look to me the original URI has lost its meaning, e.g. other people can link to it all they want and visitors following the URIs won't find the information the visitors expect. (This doesn't apply to DevMO. I just want to point out my objection to TB's doc) the main points of the article are: urls should never change. you can move the files anywhere you want, but the urls should be consistent. and the urls should be human readable and human guessable. a topic for another post: see http://www.php.net/urlhowto.php ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
Clover wrote: If I begin with a FAQ of 10 questions, then it grows to 50, and then to 100... so I split the FAQ into separate files. At the end of the process, all questions in misc.html are moved to the appropriate file. Now, does it make sense for me to keep the misc.html URI? You should never have a URI called "misc.html" in the first place. ;-) But if you did, and the content goes away, then the URI should redirect to the index, or the most appropriate content. Or just contain an archived version of the original with directions to the new. Gerv ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
> This rather fails the "guessable" test, doesn't it? Doesn't everyone guess these days by typing keywords into Google or into search boxes? I don't think it's practical to support URL guessing when the number of URLs maintained is large. Which of these is the "right" guess anyway: http://example.com/bikes/parts/wheels.html http://example.com/parts/bikes/wheels.html http://example.com/parts/wheels/bikes.html To me, guessing only works when the site is something you're already familiar with. That's a tiny portion of the readership? I only guess portal URLs - that's still possible for d.m.o. Yesterday I was looking for Bill Dortch's cookie libraries. I remembered it was www.hidaho.com, but when I got there: d'oh! it's gone. So much for guesses. I reckon using doc ID's takes a lot of heat out of the d.m.o design. URL paths just aren't the big picture. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
Just read the RFC about URLs and be done with it, please. Axel ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Technology
Gerv wrote: > Clover wrote: > > If I begin with a FAQ of 10 questions, then it grows to 50, and then to > > 100... so I split the FAQ into separate files. At the end of the > > process, all questions in misc.html are moved to the appropriate file. > > Now, does it make sense for me to keep the misc.html URI? > > You should never have a URI called "misc.html" in the first place. ;-) Quite right. You should have a URI like /foo/bar/faq.html and enable MultiViews so you can always refer to it as just /foo/bar/faq Now, if your FAQ grows, you can split it up into /foo/bar/faq/install.html /foo/bar/faq/options.html /foo/bar/faq/plugins.html etc. and then you make /foo/bar/faq/index.html the table of contents. In good style, you refer to all of the above without extensions, and drop "index.html" from your URLs entirely. Thus, nothing breaks (the server will send back /foo/bar/faq/index.html any time someone asks for /foo/bar/faq) and everything is forwards-compatible. Note that I didn't use numbers for the subsections. This is because a) Names are more descriptive. b) I can reorder things without breaking links. See http://mozilla.org/README-style.html for other notes on URIs. ~fantasai ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - Editing, Translation, Versions
In my experience, getting anything published is incredibly labour intensive. If smart, successful publishers still do drafts by hand, then probably we will too? What I know: Except for very long-lived and frequently reviewed documents, there's just not enough versioning in publishing to justify complex source code control. It's just a matter of hand-crafted drafts and final copy. Translation is the same: hand manipulation. When you're working on your beautiful article (which we want), most of the processing happens outside the system, in email exchanges. Only when there's some element of finality do you submit copy. If you look at how newspapers and magazines work, they have big production systems (some of them), but every line of content still goes through a series of hands. If we have some beautiful reference material, then that is a different matter; we'd like to keep that versioned up to date for sure. So I propose email as the main method of managing editing, versions and translations, with some exceptions for living documents like references and wikis. The KISS principle. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation
Re: developer.mozilla.org thoughts - On Rights and Credits
On the subject of Rights and Credits: These things aren't locked in stone; they change a lot, and sometimes must be individually negotiated. The main "rules" I'm aware of are: Protecting Content: It's nearly impossible to protect non-fiction written content. A complete waste of time and energy. The most you might protect is the structural outline, or key paragraphs. It's common for the Table-of-Contents/Site-Navigation-Hierarchy to be considered worthwhile IP. You can see from Brendan's remarks how little respect is paid even to that; ripping off style and layout is very common. Too close a rip-off and we might awaken the Microsoft Legal Giant, though, on a TOC basis. Yikes. This rule extends to print. I know of a best seller cook book. The book has been good for 20 years. When a copycat author took the content and changed the wording of each paragraph slightly but no more, the publisher didn't even pursue the copycat publisher in law. Not worth it. The good side of this is that it's easy to generate content without having to worry much about plagiarism ;-) Owning Rights: Owning rights comes down to readership. If you have no readership yet (our case), and/or you pay nothing, then you can ask for no rights in return. Generous people might give you rights. You can always ask. As a starting point, DevMo (or the reader-friendly name) just needs to protect itself from hostile contributors failing to give "permission-to-use" statements, the same problem as the Gerv has been addressing in the tree. If people get to keep their rights, they're more motivated to supply content. At the start, we need content. Later on we can tighten up on rights. There are no lost opportunities; content can alway be re-written. When we have 10,000 readers, then we can ask contributors to surrender some rights in return for the prestige of being on DevMo. We can start playing rights fun and games at that point, if we want. Rights shmights ;-). And what about the OPL, anyway? Credits: Likewise, the smaller you are, the more credit you have to give, unless contributors don't care. We have not yet determined if academics or others interested in references and extensive bylines are target readers. If they are, then credits should be extensive. Otherwise, a byline is more than enough, I think. Some readers will be totally confused by a document packed with references. I think there's certainly a case for some of the Mozilla opinion leaders to provide highly referenced commentary and essays. I can imagine a group of readers who like that sort of thing. - Nigel. ___ mozilla-documentation mailing list [EMAIL PROTECTED] http://mail.mozilla.org/listinfo/mozilla-documentation