Regarding Wikis
Deb Richardson
Over the past year you have made it clear that you are not a fan of
the MDC's open-edit wiki policies. You and I have discussed this
before, and I have told you several times that this policy is not
going to change. If you do not agree with this policy, you don't
have to contribute to our project. That's ok.
I would like to take this opportunity, however, to point out that in
the past year over 1700 pages of documentation have been contributed,
over 24000 additions and updates have been made, over 5000 people
have registered for accounts, and over 10,600,000 pages of
documentation have been served. This is on the English wiki alone,
and doesn't count the incredible work being done by translators
working on the 10 (soon to be 11) localizations.
All of this is directly the result of using a wiki system. Older
projects tried a different approach with tight editorial standards,
strict coding guidelines, patch submissions with required reviews,
and the use of (various forms of) HTML and XML for markup. Those
projects failed for a variety of reasons, but mostly because it was
simply too difficult for volunteers to contribute.
When I started the MDC, I decided to use a wiki specifically to make
it as easy as possible for volunteers to contribute. Very few people
enjoy writing technical documentation. Fewer still have the
knowledge and experience to write good documentation about the
Mozilla project and Web technologies. Fewer still (I would say none)
are interested in repetitively rewriting and revising their
documentation to meet strict editorial, coding, and markup guidelines.
Restricting write access or enforcing strict writing/coding standards
would make it much more difficult and much less fun to contribute to
our project. Most of the volunteers we have would go away, and fewer
people would step up to help out. The MDC needs -more- help, not less.
No, the MDC documentation is not perfect. No, the MDC documentation
is not complete. Yes, the MDC documentation is full of stylistic
inconsistencies in both prose and code. Yes, the MDC documentation
contains errors and omissions.
What you're forgetting, however, is that all of these things were
true in Mozilla documentation before we had the wiki, and they would
all continue to be true if we stopped using the wiki today. The
wiki, however, makes it faster, easier, and more fun to make
additions, improvements, and corrections than ever before. Yes,
people can introduce new errors or problems, but over the past year
the wiki has clearly been hugely beneficial to both the quality and
quantity of our documentation.
While it would be nice to have clearly written style guides for
writing and coding -- and the paid or volunteer staff to correct
documentation to meet those guidelines -- we have neither right now.
I do want to write such guides eventually, but even when I do they
will be friendly suggestions, not draconian standards to be enforced
with an iron fist.
Now, as a year ago, we have simply to do the best with what we've
got. Yes, there are improvements to be made, but those improvements
can be made incrementally over time. Our documentation will -never-
be perfect, but right now I think we're doing a pretty good job at
making it better.
Thanks.
~ deb
Zbigniew Braniecki
> Gerard,
>
> Over the past year you have made it clear that you are not a fan of
> the MDC's open-edit wiki policies. You and I have discussed this
> before, and I have told you several times that this policy is not
> going to change. If you do not agree with this policy, you don't
> have to contribute to our project. That's ok.
Great! I just want to say that I'm 100% with you at this point, deb!
Gerard, you said that you don't understand why anyone can edit
anything anywhere for any reason. I see that you don't understand.
But, well, it's the wiki way of work... And there are proves that it
works. And if you don't understand why, then you need to read more
about Wiki maybe?
> While it would be nice to have clearly written style guides for
> writing and coding -- and the paid or volunteer staff to correct
> documentation to meet those guidelines -- we have neither right now.
> I do want to write such guides eventually, but even when I do they
> will be friendly suggestions, not draconian standards to be enforced
> with an iron fist.
We need guidelines, a set of advices, even a "rules" that could/should
(not must) be followed. That's all.
> Now, as a year ago, we have simply to do the best with what we've
> got. Yes, there are improvements to be made, but those improvements
> can be made incrementally over time. Our documentation will -never-
> be perfect, but right now I think we're doing a pretty good job at
> making it better.
MDC is a project, not a product. Project will never be "finished".
It's a process, it has no end, it's always on the path from nothing to
perfect...
Deb, thanks for keeping it open! :)
Greetings
Zbigniew Braniecki
Andreas Wuest
> On 3/10/06, Deb Richardson <d...@dria.org> wrote:
> > While it would be nice to have clearly written style guides for
> > writing and coding -- and the paid or volunteer staff to correct
> > documentation to meet those guidelines -- we have neither right now.
> > I do want to write such guides eventually, but even when I do they
> > will be friendly suggestions, not draconian standards to be enforced
> > with an iron fist.
>
> We need guidelines, a set of advices, even a "rules" that could/should
> (not must) be followed. That's all.
Although I find it mandatory to have the wiki open for everyone to
edit, I definitely think that we need (binding) policies. Not only to
make better use of the time committers invest (i.e. they know from the
beginning how to do it right, instead of being corrected by more
senior editors), and to optimise the time the more authoritative
editors spend by overseeing the modifications made.
I am talking about wiki markup style, about example coding style, but
also about how to file an article under which category, and about
findability.
Let me give an example:
http://developer.mozilla.org/en/docs/Special:Search?search=mork&go=Go.
There are 5 pages about Mork by the same author. 4 of them have
similar if not verbatim content. They all had their own categories:
Mork:What, Mork:History, Mork:Structure, etc. And, they were not
linked to from anywhere, nor were the categories.
I came by one of the articles by chance through some Usenet post. I
tried to clean up a bit, but still had no idea from where to link to
them. I then created an own Category:Mork, filed all Mork articles
under that, and made it a subcategory of Category:Toolkit API, notably
the only subcategory of it.
For those who don't know, Mork is the database backend used amongst
others by the address book. Now, I posed myself the following
question: If I were interested in how the address book stores its
data, how had I reached this article? I did not know that the
technology underlying it was called Mork, so a straight search was not
going to help me. The articles themselves where linked from nowhere,
neither the corresponding categories. To make a long story short, I am
quite sure I had never reached the article. And this worries me.
Therefore I'd find it very helpful to have a policy which states
(amongst other things):
* Link to your articles from somewhere, if possible, from a topic
page. If there is no topic page, but there are lots of articles about
similar issues, provide one (e.g. there is a nice page about Storage,
which is going to supersede Mork, but you can't link from Storage to
Mork, because Storage is not a topic page about database backends, but
about the technology named Storage, which is a particular instance of
a database backend).
* If you create new categories, arrange them like all other
categories (namely with breadcrumbs, link to Category:All Categories,
etc.), and make them a subcategory of some other category, because
otherwise, they are just dangling somewhere in space.
It is such policies which would prevent valuable articles from not
being found, and save other editors some time so they not have to go
around fixing categories and worry where to place such articles.
> MDC is a project, not a product. Project will never be "finished".
> It's a process, it has no end, it's always on the path from nothing to
> perfect...
I agree, but there's nothing to prevent us from raising the quality
bar as high as possible while we're en-route.
--
Kind regards,
Andi
Tristan Nitot
> (...)in the past year over 1700 pages of documentation have been
> 5000 people have registered for accounts, and over 10,600,000 pages of
>
> All of this is directly the result of using a wiki system. Older
> projects tried a different approach with tight editorial standards,
> strict coding guidelines, patch submissions with required reviews, and
> the use of (various forms of) HTML and XML for markup. Those projects
> failed for a variety of reasons, but mostly because it was simply too
> difficult for volunteers to contribute.
I think the site was quite a success back then, I cannot emphasize
enough how much I prefer Devmo, for the ability it offers to correct a
simple mistake or bring improvement.
It happens that 4 years ago, I have founded http://openweb.eu.org/ (a
reference about standard in French language) on a centralized model
(like Devedge) but using volunteers to write articles, and if I knew
about Wikis back then, I would have used a wiki instead of a home-made
CMS, for the reasons explained by Deb.
> but over the past year the wiki has clearly been hugely beneficial to
> both the quality and quantity of our documentation.
And that's an understatement : -D
--Tristan
--
Mozilla Europe - http://www.mozilla-europe.org/
Site in CA, CS, DE, EL, EN, ES, FI, FR, HU, IT, NL, NO, PL, SK And SQ
Mozilla Europe is an international Mozilla Foundation affiliate
Nickolay Ponomarev
> Although I find it mandatory to have the wiki open for everyone to
> edit, I definitely think that we need (binding) policies. Not only to
> make better use of the time committers invest (i.e. they know from the
> beginning how to do it right, instead of being corrected by more
> senior editors), and to optimise the time the more authoritative
> editors spend by overseeing the modifications made.
>
http://kb.mozillazine.org/Rules
> For those who don't know, Mork is the database backend used amongst
> others by the address book. Now, I posed myself the following
> question: If I were interested in how the address book stores its
> data, how had I reached this article? I did not know that the
> technology underlying it was called Mork, so a straight search was not
> going to help me. The articles themselves where linked from nowhere,
> neither the corresponding categories. To make a long story short, I am
> quite sure I had never reached the article. And this worries me.
>
Given the amount of documentation we have, one would have to ask around and find
out that technology used named 'mork'. You're right in principle, though.
> * If you create new categories, arrange them like all other
> categories (namely with breadcrumbs, link to Category:All Categories,
> etc.), and make them a subcategory of some other category, because
> otherwise, they are just dangling somewhere in space.
Even if you put a category in Category:All Categories, it's still 'dangling',
because you can't expect our users to use the list of all categories. Actually I
already mentioned that I dislike the All Categories idea, because it makes the
Uncategorized Categories MediaWiki tool more or less useless.
Nickolay
Benjamin Smedberg
> Let me give an example:
> http://developer.mozilla.org/en/docs/Special:Search?search=mork&go=Go.
> There are 5 pages about Mork by the same author. 4 of them have
> similar if not verbatim content. They all had their own categories:
> Mork:What, Mork:History, Mork:Structure, etc. And, they were not
> linked to from anywhere, nor were the categories.
>
> I came by one of the articles by chance through some Usenet post. I
> tried to clean up a bit, but still had no idea from where to link to
> them. I then created an own Category:Mork, filed all Mork articles
> under that, and made it a subcategory of Category:Toolkit API, notably
> the only subcategory of it.
FWIW, this is not the "correct" solution in this particular case, and we
should move these pages somewhere else: I designed the "Toolkit API" page to
be a list of the frozen/official APIs exposed by "the toolkit", and mork is
definitely not part of that list.
--BDS
Christian Biesinger
> FWIW, this is not the "correct" solution in this particular case, and we
> should move these pages somewhere else: I designed the "Toolkit API"
> page to be a list of the frozen/official APIs exposed by "the toolkit",
> and mork is definitely not part of that list.
Aren't the Mork articles in question about the file format and its
history anyway, rather than about an API?
Andreas Wuest
As I wrote, it was kind of a stopgap. If somebody could please point
me to a better category, I'd be very thankful! I really don't know
where to file it correctly.
--
Kind regards,
Andi