Once in the wiki, of course, it would then be much easier to update, (re)organize, and maintain. As necessary, "official" docs, such as "Drivers" and "Super-Reviewers", could be locked so only people with admin access on the wiki could change them. (With admin access given to whomever needs it to do those updates.)
If there are other related relevant-but-aging docs on Mozilla.org that should be migrated (if this proposal is accepted), I'd be happy to do those as well.
Please let me know if you think this is a good idea. I'm happy to make this a priority task for myself if it would be helpful.
~ deb
(Technically this is about mozilla.org development, so replies might best go to m.d.mozilla-org.)
> This is in response to some of the ideas I've seen while skimming > through the (very large) "Summary..." thread on m.d.general.
> I propose migrating the documentation about getting started with > Mozilla development from mozilla.org into the MDC wiki's "Developing > Mozilla" area:
> Once in the wiki, of course, it would then be much easier to update, > (re)organize, and maintain. As necessary, "official" docs, such as > "Drivers" and "Super-Reviewers", could be locked so only people with > admin access on the wiki could change them. (With admin access given > to whomever needs it to do those updates.)
> If there are other related relevant-but-aging docs on Mozilla.org that > should be migrated (if this proposal is accepted), I'd be happy to do > those as well.
> Please let me know if you think this is a good idea. I'm happy to > make this a priority task for myself if it would be helpful.
> ~ deb
> (Technically this is about mozilla.org development, so replies might > best go to m.d.mozilla-org.)
Great. I called it the need for Open Documentation development in one of the Mozilla support newsgroups.
I am sure you will get a lot of help with this initiative, hopefully also from experienced software documentation profs, being retired looking for a hobby. I'm subscribed here. I'll spread the word if the lights are green.
Deb Richardson wrote: > I propose migrating the documentation about getting started with Mozilla > development from mozilla.org into the MDC wiki's "Developing Mozilla" area:
This sounds like a great idea. If you need (or would like) help from the Mozilla Foundation side please let me know.
> As necessary, "official" docs, such as > "Drivers" and "Super-Reviewers", could be locked so only people with > admin access on the wiki could change them. (With admin access given to > whomever needs it to do those updates.)
I agree that this is desirable.
> If there are other related relevant-but-aging docs on Mozilla.org that > should be migrated (if this proposal is accepted), I'd be happy to do > those as well.
There are also some policy-related documents that it might make sense to include in this migration, again with appropriate access control. These might nclude the policies relating to CVS committers, licensing policy (including how to use the license boilerplate files), policy on handling security vulnerability reports, and others.
Frank Hecker wrote: > There are also some policy-related documents that it might make sense to > include in this migration, again with appropriate access control. These > might nclude the policies relating to CVS committers, licensing policy > (including how to use the license boilerplate files), policy on handling > security vulnerability reports, and others.
I've gone through the Hacking Guide and a bunch of the documents to which it links, and have came up with the following list:
It's fairly extensive, and not necessarily final. I would like some feedback about what perhaps shouldn't be on that list, what might be added, and which documents should (or shouldn't) be "locked" after migration. Anyone is welcome to edit the list, using the "Edit" link in the right hand column.
If that list seems OK (or at least mostly OK), let me know and I will get started on the migration work as soon as possible.
One problem mozilla.org has is that there are often a lot of pages that have similar material. If we create a new official location we should immediately go forward and archive all the old pages somewhere, and mark them with big flashing red "OBSOLETE".
I'm interested in the usability of the pages users see when they want to get involved. In addition to looking at what we already have, I think we should also look at some other successful open source projects with god web sites and try and map out our content and theirs.
Once someone has decided to contribute to a Mozilla project development, a page with a set of link to pertinent areas:
- projects: different (active!) projects - testing info: nightly builds, - discussion lists: how to participate in development discussions - contacts: who to ask - getting and building the source - contributing code: process from bug to maintenance - bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)
A few important links to other material on mozilla.org
- mozilla's mission - project organization/leadership - different groups, and how exception handling works.
The key is to keep these pages trim, have them contain only the material folk need to get at when they're getting started.
The mozilla.org page should over time diminish the size of the Firefox/Thunderbird box at the top (maintaining the link off to mozilla.com).
The mozilla.org page could look like this:
mozilla.org search [ ] ( Go ) / Products \ Support \ Store \ Developers \ About \
Projects: Mozilla's mission is to preserve choice and - Firefox innovation on the Internet. You can help us build the - Thunderbird future of the Internet by _getting_involved_. - Gecko - Seamonkey Existing contributors ... - Camino - Bugzilla Announcements: MozillaZine News: ... * kjldfjsdf * sdfkl;skd;lflk;df ;sdlkf;slkf sdflkdf;lsdffd
Community Blogs : Site Map : Security Updates : Contact Us : Foundation
On Friday 2006-03-17 15:46 -0800, Ben Goodger wrote:
> have similar material. If we create a new official location we should > immediately go forward and archive all the old pages somewhere, and mark > them with big flashing red "OBSOLETE".
No need to archive or signpost; just add an HTTP redirect! I think many of the people migrating docs to devmo have been good about this; I've had to clean up after some and add redirects, though.
> Once someone has decided to contribute to a Mozilla project development, > a page with a set of link to pertinent areas:
> - projects: different (active!) projects > - testing info: nightly builds, > - discussion lists: how to participate in development discussions > - contacts: who to ask > - getting and building the source > - contributing code: process from bug to maintenance > - bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)
> A few important links to other material on mozilla.org
> - mozilla's mission > - project organization/leadership - different groups, and how exception > handling works.
I thought http://www.mozilla.org/hacking/ was about the clearest list we had of the important documents, although in a subset of the categories you list. It's had a few additions recently that may not belong at toplevel, though.
> The key is to keep these pages trim, have them contain only the material > folk need to get at when they're getting started.
If they can be more useful to existing contributors and still be useful to newcomers, that would be better. It would also have the advantage that the current contributors (who know what's correct and what's out of date) would look at the pages intended for newcomers, which would mean they would be more likely to be kept up to date. But I definitely agree that it should be easier for people to find information when getting started.
> Projects: Mozilla's mission is to preserve choice and > - Firefox innovation on the Internet. You can help us build the > - Thunderbird future of the Internet by _getting_involved_. > - Gecko > - Seamonkey Existing contributors ... > - Camino > - Bugzilla Announcements: MozillaZine News: > ... * kjldfjsdf * sdfkl;skd;lflk;df > ;sdlkf;slkf sdflkdf;lsdffd
> Community Blogs : Site Map : Security Updates : Contact Us : Foundation
It might even be good to have short descriptions in the "Projects" list there:
Firefox Web Browser Thunderbird Email Client Gecko Web page handling, core of other apps etc.
-David
-- L. David Baron <URL: http://dbaron.org/ > Technical Lead, Layout & CSS, Mozilla Corporation
By "migration" I mean "move the content into the MDC (devmo) wiki as a set of pages in the "Developing Mozilla" category, and redirecting the original URLs to the new locations.
Once in the wiki, it will be much easier to update, reorganize, or add to those pages. Ideally they would be put together as a "Getting Started" page for the "Developing Mozilla" section of the MDC.
> One problem mozilla.org has is that there are often a lot of pages that > have similar material. If we create a new official location we should > immediately go forward and archive all the old pages somewhere, and mark > them with big flashing red "OBSOLETE".
As dbaron points out, we can just redirect the pages. BSmedberg has already done this with a fair chunk of the Building Mozilla documentation, as you can see here:
> I'm interested in the usability of the pages users see when they want to > get involved. In addition to looking at what we already have, I think we > should also look at some other successful open source projects with god > web sites and try and map out our content and theirs.
> Once someone has decided to contribute to a Mozilla project development, > a page with a set of link to pertinent areas:
Agreed. That's pretty much I envision for the "Getting Started" page.
> The key is to keep these pages trim, have them contain only the material > folk need to get at when they're getting started.
Absolutely. I think Step One would be to get the existing information into the MDC wiki so it can be more easily updated. Once in the wiki, it will be much easier to work on reorganizing the content into a focused "Getting Started" area for new contributors.
L. David Baron wrote: > No need to archive or signpost; just add an HTTP redirect! I think many > of the people migrating docs to devmo have been good about this; I've > had to clean up after some and add redirects, though.
OK. Do we care about cvs revision histories?
> I thought http://www.mozilla.org/hacking/ was about the clearest list we > had of the important documents, although in a subset of the categories > you list. It's had a few additions recently that may not belong at > toplevel, though.
I was thinking the list I presented above might be a good surrogate for the hacking page. The order of docs on the hacking page is a bit haphazard, and the content not necessarily presented in the best way.
For example:
Life Cycle of a Patch (the top link):
The description on the Hacking page says "An overview of how to get the source, develop patches, get them reviewed, super-reviewed and checked in the tree."
Speed readers will skip the first paragraph that links to docs on building from source (oops!), and a long document on hacking Mozilla. They'll skip down to a section that includes links mostly on things to consider before submitting patches for review/reviewing others' patches: portability, l10n, etc.
I don't know if this is the ideal flow. I think the trick is to think like a new contributor and their needs during the various stages of their involvement: idea -> design -> coding -> review -> checkin -> maintenance.
During the idea/design phase, mailing lists are very useful. During the coding phase, docs about mozilla architecture/conventions/portability etc useful. During the review phase, docs about process, conventions, etc useful. During the checkin phase, links to tinderboxen, regression policies, etc. During the maintenance phase, handling bugs, etc.
I think most of the docs under hacking/ need to be refactored. Very many contain large tracts of text that are redundant with other docs. More bite sized pieces that are better organized would be more useful to people. A lot of people want to help, but they may not have the patience to read through many essays.
Let me come up with something more concrete and post it in this thread.
>> The key is to keep these pages trim, have them contain only the material >> folk need to get at when they're getting started.
> If they can be more useful to existing contributors and still be useful > to newcomers, that would be better.
Absolutely.
> Firefox > Web Browser > Thunderbird > Email Client > Gecko > Web page handling, core of other apps > etc.
Yes. This might be a way to kick-start some interest in some of the more dormant projects too!
Ben Goodger wrote: > L. David Baron wrote: >> No need to archive or signpost; just add an HTTP redirect! I think many >> of the people migrating docs to devmo have been good about this; I've >> had to clean up after some and add redirects, though.
Look at the list of activities and areas I gave in my other post in this thread:
- projects: different (active!) projects - testing info: nightly builds, - discussion lists: how to participate in development discussions - contacts: who to ask - getting and building the source - contributing code: process from bug to maintenance - bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)
As people become involved what are the things they're most likely to be interested in? Getting involved with a particular project probably.
- Project List - Discussion lists - the first port of call. Few people are going to jump right in and start coding I bet, they probably want to see what's going on first. - Testing info - many folk get involved through testing, since installing nightlies is an accessible entry point.
Next, once you're more adventurous: - build from source - contribute code (* this is a page in and of itself *)
Lesser importance right away, but useful if you need it: - Links to tools (tbox, etc) - Contacts: who do I ask? Help I found a security bug! Something is wrong! etc.
For existing contributors what do they want? - To know what's going on globally and in other parts of the world - Links to documentation and best practices - Links to tools ??
(* Contributing Code *)
What sort of code do people contribute? - bug fixes for filed bugs (improving overall quality) - new features/self-found bugs (scratching itch)
The process for handling the two is often very different. There's usually little resistance to those producing bugfix patches. But a new feature? Well, that requires discussion, design, and a lot more work. How does that process work? Who decides if the feature should be accepted? What goes where? etc. There's not really any material on that stuff right now.
> What sort of code do people contribute? > - bug fixes for filed bugs (improving overall quality) > - new features/self-found bugs (scratching itch)
> The process for handling the two is often very different. There's > usually little resistance to those producing bugfix patches. But a new > feature? Well, that requires discussion, design, and a lot more work. > How does that process work? Who decides if the feature should be > accepted? What goes where? etc. There's not really any material on that > stuff right now.
This is also different per-project. Which raises the question, how do these docs scale across projects?
What I like about this page is that it's clearly designed to be read by engineers: nicely organized into bite sized chunks, smallish paragraphs, bulletized items, etc. You get the feeling you're acquiring lots of useful knowledge rapidly when you read it.
(Mozilla's large enough that each block might be its own separate page (although a printable PDF guide for bedtime reading is a nice idea!))
Ben Goodger wrote: > What I like about this page is that it's clearly designed to be read by > engineers: nicely organized into bite sized chunks, smallish paragraphs, > bulletized items, etc. You get the feeling you're acquiring lots of > useful knowledge rapidly when you read it.
Using your ideas as a guide, and looking through our existing docs, I've cobbled together a quick initial structure:
* Community, roles and responsibilities ** Includes lists of Drivers, Super-reviewers, Module owners, Security team, etc. * Projects ** Includes a list of all active projects, with related discussion lists, wiki.mo links, and contacts * Testing & Bug reporting ** Testing ** Filing bugs ** Handling security bugs * Source code ** Getting the source ** Building from source * Coding ** Fixing bugs ** Developing new features ** Contributing code ** Code review process ** Commit access ** Tools (bonsai, tinderbox, lxr) ** Theory and documentation ** Tree layout ** Coding style ** Coding conventions ** Secure coding guidelines ** Performance and leaks * Maintenance * Localization
Please fill in whatever you thinks missing or restructure it however you think it would best work. We'll likely have to fill in some blanks since our current docs don't cover everything we'll want in the guide.
> mozilla.org search [ ] ( Go ) > / Products \ Support \ Store \ Developers \ About \
Should the support section be moved to mozilla.com? -- Chris Ilias mozilla.test.multimedia moderator Mozilla links <http://ilias.ca> (Please do not email me tech support questions)
Deb Richardson wrote: > * Community, roles and responsibilities > ** Includes lists of Drivers, Super-reviewers, Module owners, Security > team, etc. > * Projects > ** Includes a list of all active projects, with related discussion > lists, wiki.mo links, and contacts > * Testing & Bug reporting > ** Testing > ** Filing bugs > ** Handling security bugs > * Source code > ** Getting the source > ** Building from source > * Coding > ** Fixing bugs > ** Developing new features > ** Contributing code > ** Code review process > ** Commit access > ** Tools (bonsai, tinderbox, lxr) > ** Theory and documentation > ** Tree layout > ** Coding style > ** Coding conventions > ** Secure coding guidelines > ** Performance and leaks > * Maintenance > * Localization
I'm wondering why you put "Tools (...)" and every subitem after that *after* the process of developing a bug. I would say some/most/all of these resources are very useful, if not indispensable, when starting work on the code. How are you supposed to write a patch if you don't know where what code belongs, how it should be styled, etc. (and maybe something about how XPCOM/XPConnect work/are used (does that go in Theory and documentation? I assume so...)).
When I came to one of the Mozilla projects about one and a half year ago, the first thing I was taught to use was Bugzilla (where do I file my bug?), next up was LXR (where is the code that I need to fix?), then CVS and how to use it to create a patch. Security and leaks weren't of much concern in that case, considering the nature of the fix, but if they would have been, surely they would have to be considered before trying to make the actual patch and getting it checked in?
Chris Ilias wrote: >> mozilla.org search [ ] ( Go ) >> / Products \ Support \ Store \ Developers \ About \
> Should the support section be moved to mozilla.com?
The Mozilla Corporation does not support Camino, SeaMonkey, tier-2 platforms, probably not XULRunner yet, etc. -- there is most definitely a need for a mozilla.org support section.
Look at the list of activities and areas I gave in my other post in this thread:
- projects: different (active!) projects - testing info: nightly builds, - discussion lists: how to participate in development discussions - contacts: who to ask - getting and building the source - contributing code: process from bug to maintenance - bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)
As people become involved what are the things they're most likely to be interested in? Getting involved with a particular project probably.
- Project List - Discussion lists - the first port of call. Few people are going to jump right in and start coding I bet, they probably want to see what's going on first. - Testing info - many folk get involved through testing, since installing nightlies is an accessible entry point.
Next, once you're more adventurous: - build from source - contribute code (* this is a page in and of itself *)
Lesser importance right away, but useful if you need it: - Links to tools (tbox, etc) - Contacts: who do I ask? Help I found a security bug! Something is wrong! etc.
For existing contributors what do they want? - To know what's going on globally and in other parts of the world - Links to documentation and best practices - Links to tools ??
(* Contributing Code *)
What sort of code do people contribute? - bug fixes for filed bugs (improving overall quality) - new features/self-found bugs (scratching itch)
The process for handling the two is often very different. There's usually little resistance to those producing bugfix patches. But a new feature? Well, that requires discussion, design, and a lot more work. How does that process work? Who decides if the feature should be accepted? What goes where? etc. There's not really any material on that stuff right now.
> What sort of code do people contribute? > - bug fixes for filed bugs (improving overall quality) > - new features/self-found bugs (scratching itch)
> The process for handling the two is often very different. There's > usually little resistance to those producing bugfix patches. But a new > feature? Well, that requires discussion, design, and a lot more work. > How does that process work? Who decides if the feature should be > accepted? What goes where? etc. There's not really any material on that > stuff right now.
This is also different per-project. Which raises the question, how do these docs scale across projects?
L. David Baron wrote: > No need to archive or signpost; just add an HTTP redirect! I think many > of the people migrating docs to devmo have been good about this; I've > had to clean up after some and add redirects, though.
OK. Do we care about cvs revision histories?
> I thought http://www.mozilla.org/hacking/ was about the clearest list we > had of the important documents, although in a subset of the categories > you list. It's had a few additions recently that may not belong at > toplevel, though.
I was thinking the list I presented above might be a good surrogate for the hacking page. The order of docs on the hacking page is a bit haphazard, and the content not necessarily presented in the best way.
For example:
Life Cycle of a Patch (the top link):
The description on the Hacking page says "An overview of how to get the source, develop patches, get them reviewed, super-reviewed and checked in the tree."
Speed readers will skip the first paragraph that links to docs on building from source (oops!), and a long document on hacking Mozilla. They'll skip down to a section that includes links mostly on things to consider before submitting patches for review/reviewing others' patches: portability, l10n, etc.
I don't know if this is the ideal flow. I think the trick is to think like a new contributor and their needs during the various stages of their involvement: idea -> design -> coding -> review -> checkin -> maintenance.
During the idea/design phase, mailing lists are very useful. During the coding phase, docs about mozilla architecture/conventions/portability etc useful. During the review phase, docs about process, conventions, etc useful. During the checkin phase, links to tinderboxen, regression policies, etc. During the maintenance phase, handling bugs, etc.
I think most of the docs under hacking/ need to be refactored. Very many contain large tracts of text that are redundant with other docs. More bite sized pieces that are better organized would be more useful to people. A lot of people want to help, but they may not have the patience to read through many essays.
Let me come up with something more concrete and post it in this thread.
>> The key is to keep these pages trim, have them contain only the material >> folk need to get at when they're getting started.
> If they can be more useful to existing contributors and still be useful > to newcomers, that would be better.
Absolutely.
> Firefox > Web Browser > Thunderbird > Email Client > Gecko > Web page handling, core of other apps > etc.
Yes. This might be a way to kick-start some interest in some of the more dormant projects too!
What I like about this page is that it's clearly designed to be read by engineers: nicely organized into bite sized chunks, smallish paragraphs, bulletized items, etc. You get the feeling you're acquiring lots of useful knowledge rapidly when you read it.
(Mozilla's large enough that each block might be its own separate page (although a printable PDF guide for bedtime reading is a nice idea!))
Everyone is welcome to poke around there, comment on the "Talk" page (via the "Discussion" link in the right-hand column), or even edit the page itself. I am not a Mozilla Developer, so I am relying on other people's experience and expertise to guide the development of this document structure.
On 3/21/06, Deb Richardson <d...@mozilla.com> wrote:
> Please, any feedback would be appreciated.
All in all, the list and order of topics to be covered seems to be sane. I have a few comments though.
It's still a bit unclear who is the target audience of the Getting Started guide. Is it supposed to be a guide for people new to Mozilla project, as it name suggests, or just a handbook for mozilla developers, as I could think looking at its TOC? I think we should be careful not to mix the two, otherwise the end result may happen to be suboptimal to both groups of contributors.
(Things like "handling security bugs", "Commit access", "Performance and leaks" and list of drivers at the top doesn't seem to be appropriate for the Getting Started guide. Topics such as QA and Localization are not generally useful for developers, although I agree that the Getting Started guide should advise a new contributor to get involved in QA first)
Also it's not clear how the whole Getting Started guide will look. Is it going to be a list of links like hacking page [1] now? IMO that's not optimal, as a contributor has to read through multiple long pages to learn the basics. For example, one shouldn't have to read the seven pages of code review FAQ [2] just to request a review. (He'll have time to read it while waiting for review anyway ;)
I would expect the Getting started guide to be a (relatively) concise summary of the information we have, which is useful for new contributors, with links to detailed explanations. Something like [3], but not as detailed on technical topics, not as scary for chrome developers, and with more pointers to existing information, such as reviewers list.
Nickolay Ponomarev wrote: > On 3/21/06, Deb Richardson <d...@mozilla.com> wrote: >> Please, any feedback would be appreciated. > All in all, the list and order of topics to be covered seems to be > sane. I have a few comments though.
> It's still a bit unclear who is the target audience of the Getting > Started guide. Is it supposed to be a guide for people new to Mozilla > project, as it name suggests, or just a handbook for mozilla > developers, as I could think looking at its TOC? I think we should be > careful not to mix the two, otherwise the end result may happen to be > suboptimal to both groups of contributors.
> (Things like "handling security bugs", "Commit access", "Performance > and leaks" and list of drivers at the top doesn't seem to be > appropriate for the Getting Started guide. Topics such as QA and > Localization are not generally useful for developers, although I agree > that the Getting Started guide should advise a new contributor to get > involved in QA first)
> Also it's not clear how the whole Getting Started guide will look. Is > it going to be a list of links like hacking page [1] now? IMO that's > not optimal, as a contributor has to read through multiple long pages > to learn the basics. For example, one shouldn't have to read the seven > pages of code review FAQ [2] just to request a review. (He'll have > time to read it while waiting for review anyway ;)
> I would expect the Getting started guide to be a (relatively) concise > summary of the information we have, which is useful for new > contributors, with links to detailed explanations. Something like [3], > but not as detailed on technical topics, not as scary for chrome > developers, and with more pointers to existing information, such as > reviewers list.
I'd be hoping to see that this document would evolve into something like the js guide, from a structural point of view, and from the point of view of target audience. I'm not that afraid that things get out of scope if we don't define the target audience stricter. When it comes down to the "js reference" part of this, we may want to link to pages that are not on the wiki, or at least somewhat protected, for example for the cvs committer form.
As the Apache folks say, +1 for migrating these and making them accessible and editable. Same for reorganizing them. The current order came about to help people find the content that had been there previously, and so is definitely in need of fixing.
On the docs that should be locked, the few Deb has noted with "lock" are documents we've considered official and so should be locked. The other official policy docs that should be locked are below. Many need updating very badly. It would be helpful if there can be a way for people to make suggestions (or provide an edited version that is clearly marked as a proposed revision but not the official policy, if there is wiki-fu that allows that).
Deb Richardson wrote: > Frank Hecker wrote: >> There are also some policy-related documents that it might make sense >> to include in this migration, again with appropriate access control. >> These might nclude the policies relating to CVS committers, licensing >> policy (including how to use the license boilerplate files), policy on >> handling security vulnerability reports, and others.
> I've gone through the Hacking Guide and a bunch of the documents to > which it links, and have came up with the following list:
> It's fairly extensive, and not necessarily final. I would like some > feedback about what perhaps shouldn't be on that list, what might be > added, and which documents should (or shouldn't) be "locked" after > migration. Anyone is welcome to edit the list, using the "Edit" link in > the right hand column.
> If that list seems OK (or at least mostly OK), let me know and I will > get started on the migration work as soon as possible.
|
