subject:"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

2004-03-03 Thread c tanner

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

2004-03-03 Thread Pascal Chevrel

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

2004-03-03 Thread Michael Lefevre

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

2004-03-03 Thread Axel Hecht

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

2004-03-03 Thread Gervase Markham

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

2004-03-03 Thread Gervase Markham

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

2004-03-03 Thread Michael Lefevre

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

2004-03-03 Thread Dan Gall

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

2004-03-03 Thread Simon Paquet

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

2004-03-03 Thread Clover

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

2004-03-03 Thread Boris Zbarsky

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

2004-03-03 Thread Boris Zbarsky

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

2004-03-03 Thread Clover

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

2004-03-03 Thread Boris Zbarsky

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

2004-03-04 Thread Gervase Markham

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

2004-03-04 Thread Gervase Markham

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 &#x'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

2004-03-04 Thread Michael Lefevre

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

2004-03-04 Thread Axel Hecht

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

2004-03-04 Thread Michael Lefevre

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

2004-03-04 Thread Karsten Düsterloh

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

2004-03-04 Thread James Graham

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

2004-03-04 Thread Axel Hecht

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

2004-03-04 Thread Benjamin D. Smedberg

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.

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.

4) The "lead editor" publishes the document. Thi

Re: developer.mozilla.org thoughts

2004-03-04 Thread Fred

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

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.

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

2004-03-05 Thread Gervase Markham

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

2004-03-05 Thread James Graham

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

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

2004-03-05 Thread Axel Hecht

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

2004-03-05 Thread Axel Hecht

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

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 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.

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:

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

2004-03-05 Thread Boris Zbarsky

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

2004-03-05 Thread Benjamin D. Smedberg

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

2004-03-05 Thread Boris Zbarsky

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

2004-03-05 Thread Brendan Eich

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

2004-03-06 Thread Christian Biesinger

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

2004-03-06 Thread Boris Zbarsky

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

2004-03-06 Thread fantasai

"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

2004-03-06 Thread Christian Biesinger

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

2004-03-07 Thread fantasai

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

2004-03-07 Thread fantasai

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

2004-03-08 Thread Michael Lefevre

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

2004-03-08 Thread Boris Zbarsky

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

2004-03-08 Thread Benjamin D. Smedberg

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

2004-03-08 Thread Myk Melez

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

2004-03-09 Thread Michael A Nachbaur

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

2004-03-09 Thread Clover

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

2004-03-09 Thread c tanner

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

2004-03-09 Thread Michael A Nachbaur

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

2004-03-09 Thread Michael A Nachbaur

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

2004-03-09 Thread Nigel McFarlane


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

2004-03-09 Thread c tanner

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

2004-03-09 Thread Brendan Eich

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

2004-03-10 Thread Nigel McFarlane


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

2004-03-10 Thread Brendan Eich

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

2004-03-10 Thread Nigel McFarlane


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

2004-03-10 Thread Nigel McFarlane

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

2004-03-06 Thread fantasai

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

2004-03-08 Thread [EMAIL PROTECTED]@PLEASEyahoo.com

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

2004-03-08 Thread Nigel McFarlane

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

2004-03-09 Thread Gervase Markham

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

2004-03-09 Thread Clover

[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

2004-03-09 Thread Gervase Markham

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

2004-03-09 Thread Nigel McFarlane

> 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

2004-03-10 Thread Axel Hecht

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

2004-03-10 Thread fantasai

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