Personal tools

HaskellWiki talk:Guidelines

From HaskellWiki

(Difference between revisions)
Jump to: navigation, search
(Does anyone have any comments to make about the proposal....)
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
=Headlines=
+
==Headlines==
   
 
[[User:BrettGiles|Brett]], this is not to offend you. It just expresses my conviction. -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]]
 
[[User:BrettGiles|Brett]], this is not to offend you. It just expresses my conviction. -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]]
Line 11: Line 11:
 
::::I prefer starting with ==, like Wikipedia. —[[User:Ashley Y|Ashley Y]] 00:52, 2 March 2006 (UTC)
 
::::I prefer starting with ==, like Wikipedia. —[[User:Ashley Y|Ashley Y]] 00:52, 2 March 2006 (UTC)
   
----
+
::::MediaWiki is broken in not creating an '''h2''' element for a headline with single equal signs. So we should work around this brokeness by making our top-level headlines <tt>==</tt> headlines. -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]] 21:22, 8 March 2006 (UTC)
==Page nameing==
+
I see that we are doing renaming of pages pretty much whenever someone doesn't follow the unofficial guideline. Is it time to move that to an official guideline? Do we need a large consensus to do so or just persuade the sysops? [[User:BrettGiles|BrettGiles]] 19:24, 1 March 2006 (UTC)
+
:::::I've added a respective section to [[HaskellWiki:Guidelines]]. -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]] 21:40, 8 March 2006 (UTC)
  +
  +
==Page nameing and renaming==
  +
Apparently the last rename I did so offended the author that they quit the wiki. I used to follow the guideline I just added on the main page, but had never got a response before. However, considering the size of the wiki and the number of new users (especially those that seem to not know there are guidelines :), perhaps it is time to re-institute the practice. --[[User:BrettGiles|BrettGiles]] 18:04, 24 July 2007 (UTC)
  +
  +
==Official guidelines?==
  +
  +
What makes a guidline an "official" guidline? What's the process? &mdash;[[User:Ashley Y|Ashley Y]] 00:53, 2 March 2006 (UTC)
  +
  +
:I suspect that a large number of the users / contributors to this site have an academic background. My experience with academia is that some kind of consensus based decision is the most successful at getting the decision adopted. In a community like this wiki, I’m not sure how to get that. We could send out notices on the various mailing lists, we could post notes on the front page and probably other ways as well. Like any consensus decision making it would take a long time. On the other hand, those that support the site could just be autocratic, set the rule and if there is too much flak, change it.
  +
:As to what actually makes an "official" guidline, I think it is up to the '''sysops''' whether we even have such a thing. The word tends to mean that '''sysops''' are required to monitor and fix the site when these are not followed. So, we might not even want to go to official, stay at unofficial and just let the community grow the guidlines (and do the monitoring) as they see fit. Sometimes, a certain level of anarchy works fine.[[User:BrettGiles|BrettGiles]] 16:06, 2 March 2006 (UTC)
  +
::I think that the traditional consensus decision making process is too slow. In addition, not everyone is interested in every guideline question, so it is not sensible to bother everyone with each of these questions. Therefore, it seems to me that it is better to follow your “autocracy approach”. And I also doubt that it is sensible to let some sysops decide about what guidelines are official. At least, this would be a bit contrary to the wiki approach, in my opinion. So I propose that users are allowed to set up guidelines they think of as sensible—possibly after some short discussion—and to declare them as official. If others don't like the guidelines, the guidelines can still be discussed (again) and changed. -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]] 21:22, 8 March 2006 (UTC)
  +
:::So this is how all that started: with an abuse of power. Is this real? I mean, it really started this way? Do you understand that autocracy is against the very wiki philosophy and is an abuse against every other wiki users? Users are not allowed to set rules and start enforcing them '''against''' other users. This is going to create tension and, in the long run, to destroy a wiki. --AndreaRossato Thu 26 2007 07:37 CEST
  +
  +
OK. Everything on the project page should have a consensus. Everything else should be discussed here. I have adjusted the project page accordingly. &mdash;[[User:Ashley Y|Ashley Y]] 06:34, 3 March 2006 (UTC)
  +
:What is the “project page”? -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]] 21:22, 8 March 2006 (UTC)
  +
::Ah, I understand. It's [[HaskellWiki:Guidelines]]. -- [[User:Wolfgang Jeltsch|Wolfgang Jeltsch]] 21:40, 8 March 2006 (UTC)
  +
  +
== Headlines ==
  +
  +
Each page has a title which is automatically shown near the top of the page (currently centered and in red). So it doesn't make sense to put a single level 1 headline at the top of the page. (At the moment, you will see this on a few pages of this wiki. I suppose this is a legacy which comes from copying content from the old website to this wiki.)
  +
  +
For top-level structuring, level 1 headlines (the ones denoted by single equals signs in the source) should be used. It is semantically incorrect to use level 2 headlines for this purpose. I note that level 1 headlines are currently rather large and in a font that might not be preferable. However, the solution to this is not to refrain from using level 1 headlines but to change the stylesheet appropriately. ''&mdash;says [[User:Wolfgang Jeltsch]]''
  +
  +
:Note that is is currently being discussed. Level 1 (single equals) create an <tt>&lt;h1&gt;</tt> heading, which is the same level as the page title. We may (or may not:) switch to the standard of starting at level 2 (double equals) ''&mdash;says [[User:BrettGiles]]''
  +
  +
:I prefer starting with level 2 as per Wikipedia. I consider the page title to be implicitly level 1 (whether it gets rendered as h1 or not). &mdash;[[User:Ashley Y|Ashley Y]] 06:34, 3 March 2006 (UTC)
  +
  +
  +
== Wiki Bug ==
  +
Try giving a Haskell example with the greater than or the less than sign in it. It clashes with the HTML rendering! -- says [[User:Uchchwhash|Pirated Dreams]] 04:22, 17 March 2006 (UTC)
  +
  +
==What's Wrong With This Guidelines==
  +
I don't know how these guidelines became the official policy of this
  +
wiki, and I cannot find out how some of us decided to become the
  +
housekeepers, or the [http://c2.com/cgi/wiki?WikiGnome WikiGnome]s, of
  +
it.
  +
  +
Still I've been involved in wiki development and I have some ideas on
  +
how a wiki should work. I tried to discuss it in the
  +
[http://www.haskell.org/pipermail/haskell-cafe/2007-July/029483.html haskell-café mailing list].
  +
  +
Probably I should do that here too.
  +
  +
[http://c2.com/cgi/wiki?HowToReactToGoodStyleTransgressions How to react to good style transgression?]
  +
Are these guidelines to be enforced? Aren't enforced guidelines a
  +
contradiction in terms? Sure they are...
  +
  +
I don't think that cosmetic edits done just to enforce these
  +
guidelines are going to help this wiki on the long run. They piss
  +
newcomers off. And you are pissing off right the newcomers you would
  +
like to keep, the ones who are willing to contribute.
  +
  +
You could start by reading the new material, and doing some edit to
  +
the content: if you collaborate the wiki way, probably your
  +
suggestions on style issues would be followed.
  +
  +
Anyway, these are guidelines, or they pretend they are, and so you
  +
must always think about the fact the new paths can be taken.
  +
  +
Instead what you have been doing, in the last year, is setting some
  +
rules here and reshaping the wiki in the name of those rules.
  +
  +
===And what is right with these guidelines===
  +
So, when the "new" wiki started, there was quite a bit of discussion here and on the haskell list about what was an appropriate style for the wiki pages, considering that the site is meant to be a resource for new and exsisting Haskell users and as such, were desired to be reasonably consistent in style. These guidelines were the result. A variety of people edit pages to bring them into the stylistic guidelines, but if anyone is not happy with the current set, this seems like a good place to discuss changing them.
  +
  +
Andrea's link to the "WikiGnome" has some very good pointers about stylistic changes being applied to the edits of ''newcomers'', and an even better one about dropping the argument. So this is my last edit about the subject :) --[[User:BrettGiles|BrettGiles]] 21:58, 25 July 2007 (UTC)
  +
:: Style consistency is not a primary goal of a wiki. A primary goal for the wiki is always having new people contribute to its grow. If you think that stylistic guidelines enforcing must be achieved regardless of the consequences than you should drop wiki technologies and use a blogging system or other kind of content management system. Instead, if you want to use a wiki, you should try to stick to the wiki philosophy as close as you can. --AndreaRossato Thu 26 2007 07:27 CEST
  +
::I'd like to point out that I perfectly understand that your effort has the aim of improving this wiki, and I don't think that style consistency is something to be avoided. What I'm trying to do, is to help finding a better way of achieving style consistency without increasing the level of entrance for new users. I hope you - Brett - will understand I have nothing against you. But I would like you to take into account the perspective of a newcomer too. I hope you are going to keep on discussing these issues with me. That would be helpful for the both of us. Thanks for your kind attention. --AndreaRossato Jul 26 2007 10:05 CEST.
  +
  +
And that leads me to the second real big issue: page renaming.
  +
  +
==Why Page Renaming Is BAD==
  +
  +
Wiki page titles are [http://en.wikipedia.org/wiki/URI URI], and URI
  +
should be persistent over time.
  +
  +
When you rename a page you are breaking URI persistence. A redirect is
  +
only a work around. A bad work around.
  +
  +
You did a lot of page renaming lately. By doing so you broke a lot of
  +
URIs.
  +
  +
You are also breaking the structure of this wiki, by creating a false
  +
hierarchy of pages. In a wiki all pages are top level. Hierarchy and
  +
wikis belong to different worlds.
  +
  +
I do believe that this guidelines are used in a vary bad way. I would
  +
like you to stop. Or at least to seriously reconsider your way of
  +
enforcing them.
  +
  +
AndreaRossato -- Wed Jul 25 2007 19:57 CEST
  +
  +
==Amendments Proposal==
  +
I think we could use this episode to grow, as a community. I suggest some amendments to these guidelines:
  +
# enforcement: we could add something about guidelines enforcement, referring to the link I [http://c2.com/cgi/wiki?HowToReactToGoodStyleTransgressions posted before]: the user's Talk page should be used instead, and cosmetic edits should be ruled out as a bad practice, incompatible with the wiki philosopy;
  +
# page renaming: we should adopt a very strict policy for page renaming. URI persistence should be the primary goal, so page names can be changed only within a very short period of time after page creation, only for compelling reasons and only with the consent of other users, after discussing it in the talk page;
  +
# wiki structure: I'm not going to make any proposal but I would like you to think about the fact that wiki pages should be all top level, with no (false) hierarchy. This means that using slashes in page name should be considered bad practice.
  +
I hope I will find people willing to discuss these proposals.
  +
Thanks for your kind attention. --AndreaRossato Jul 26 07:59 CEST
  +
:Hi Andrea - I would suggest a few things regarding this:
  +
:*Let's move the proposal to the top of the page so that it is the first thing people see. We may even want to group the rest (or some of the rest) as old history.
  +
:*It might be a good idea to advertise this on the haskell mailing list and the haskell-cafe lists. Some people who are interested might not check the latest changes. Previous discussions seemed effective to me because there were multiple points of view.
  +
::--[[User:BrettGiles|BrettGiles]] 01:24, 27 July 2007 (UTC)
  +
:::So, a month has gone by with no changes / additions / updates to this page. I wonder if anyone supports or disagrees with the proposal by Andrea? --[[User:BrettGiles|BrettGiles]] 20:10, 24 August 2007 (UTC)

Latest revision as of 20:10, 24 August 2007

Contents

[edit] 1 Headlines

Brett, this is not to offend you. It just expresses my conviction. -- Wolfgang Jeltsch

Not to worry Wolfgang - I never take offence :) - My thoughts on the usage of level 2 only were primarily due to the size balance, but also I note this is a guideline for the original mediawiki site. Does anyone know why that is? BrettGiles 22:11, 25 February 2006 (UTC)
No idea, but it seems loose to me. -- Wolfgang Jeltsch 22:40, 25 February 2006 (UTC)
I did some research on metawiki and this is the reason they start at level 2. "So that when a user without CSS, or a text-mode browser, or a screen reader visits, they'll be presented with a page that at least has a logical document flow." From what I can tell, by default, the page title is rendered as a h1 element. So are single = headings. Double == are h2 and so on. So from that point of view it does make sense to start at two equals. I think the real issue is that the software is slightly broken in not generating an h2 for a single equals sign. So, what do you think? BrettGiles 22:36, 26 February 2006 (UTC)
I prefer starting with ==, like Wikipedia. —Ashley Y 00:52, 2 March 2006 (UTC)
MediaWiki is broken in not creating an h2 element for a headline with single equal signs. So we should work around this brokeness by making our top-level headlines == headlines. -- Wolfgang Jeltsch 21:22, 8 March 2006 (UTC)
I've added a respective section to HaskellWiki:Guidelines. -- Wolfgang Jeltsch 21:40, 8 March 2006 (UTC)

[edit] 2 Page nameing and renaming

Apparently the last rename I did so offended the author that they quit the wiki. I used to follow the guideline I just added on the main page, but had never got a response before. However, considering the size of the wiki and the number of new users (especially those that seem to not know there are guidelines :), perhaps it is time to re-institute the practice. --BrettGiles 18:04, 24 July 2007 (UTC)

[edit] 3 Official guidelines?

What makes a guidline an "official" guidline? What's the process? —Ashley Y 00:53, 2 March 2006 (UTC)

I suspect that a large number of the users / contributors to this site have an academic background. My experience with academia is that some kind of consensus based decision is the most successful at getting the decision adopted. In a community like this wiki, I’m not sure how to get that. We could send out notices on the various mailing lists, we could post notes on the front page and probably other ways as well. Like any consensus decision making it would take a long time. On the other hand, those that support the site could just be autocratic, set the rule and if there is too much flak, change it.
As to what actually makes an "official" guidline, I think it is up to the sysops whether we even have such a thing. The word tends to mean that sysops are required to monitor and fix the site when these are not followed. So, we might not even want to go to official, stay at unofficial and just let the community grow the guidlines (and do the monitoring) as they see fit. Sometimes, a certain level of anarchy works fine.BrettGiles 16:06, 2 March 2006 (UTC)
I think that the traditional consensus decision making process is too slow. In addition, not everyone is interested in every guideline question, so it is not sensible to bother everyone with each of these questions. Therefore, it seems to me that it is better to follow your “autocracy approach”. And I also doubt that it is sensible to let some sysops decide about what guidelines are official. At least, this would be a bit contrary to the wiki approach, in my opinion. So I propose that users are allowed to set up guidelines they think of as sensible—possibly after some short discussion—and to declare them as official. If others don't like the guidelines, the guidelines can still be discussed (again) and changed. -- Wolfgang Jeltsch 21:22, 8 March 2006 (UTC)
So this is how all that started: with an abuse of power. Is this real? I mean, it really started this way? Do you understand that autocracy is against the very wiki philosophy and is an abuse against every other wiki users? Users are not allowed to set rules and start enforcing them against other users. This is going to create tension and, in the long run, to destroy a wiki. --AndreaRossato Thu 26 2007 07:37 CEST

OK. Everything on the project page should have a consensus. Everything else should be discussed here. I have adjusted the project page accordingly. —Ashley Y 06:34, 3 March 2006 (UTC)

What is the “project page”? -- Wolfgang Jeltsch 21:22, 8 March 2006 (UTC)
Ah, I understand. It's HaskellWiki:Guidelines. -- Wolfgang Jeltsch 21:40, 8 March 2006 (UTC)

[edit] 4 Headlines

Each page has a title which is automatically shown near the top of the page (currently centered and in red). So it doesn't make sense to put a single level 1 headline at the top of the page. (At the moment, you will see this on a few pages of this wiki. I suppose this is a legacy which comes from copying content from the old website to this wiki.)

For top-level structuring, level 1 headlines (the ones denoted by single equals signs in the source) should be used. It is semantically incorrect to use level 2 headlines for this purpose. I note that level 1 headlines are currently rather large and in a font that might not be preferable. However, the solution to this is not to refrain from using level 1 headlines but to change the stylesheet appropriately. —says User:Wolfgang Jeltsch

Note that is is currently being discussed. Level 1 (single equals) create an <h1> heading, which is the same level as the page title. We may (or may not:) switch to the standard of starting at level 2 (double equals) —says User:BrettGiles
I prefer starting with level 2 as per Wikipedia. I consider the page title to be implicitly level 1 (whether it gets rendered as h1 or not). —Ashley Y 06:34, 3 March 2006 (UTC)


[edit] 5 Wiki Bug

Try giving a Haskell example with the greater than or the less than sign in it. It clashes with the HTML rendering! -- says Pirated Dreams 04:22, 17 March 2006 (UTC)

[edit] 6 What's Wrong With This Guidelines

I don't know how these guidelines became the official policy of this wiki, and I cannot find out how some of us decided to become the housekeepers, or the WikiGnomes, of it.

Still I've been involved in wiki development and I have some ideas on how a wiki should work. I tried to discuss it in the haskell-café mailing list.

Probably I should do that here too.

How to react to good style transgression? Are these guidelines to be enforced? Aren't enforced guidelines a contradiction in terms? Sure they are...

I don't think that cosmetic edits done just to enforce these guidelines are going to help this wiki on the long run. They piss newcomers off. And you are pissing off right the newcomers you would like to keep, the ones who are willing to contribute.

You could start by reading the new material, and doing some edit to the content: if you collaborate the wiki way, probably your suggestions on style issues would be followed.

Anyway, these are guidelines, or they pretend they are, and so you must always think about the fact the new paths can be taken.

Instead what you have been doing, in the last year, is setting some rules here and reshaping the wiki in the name of those rules.

[edit] 6.1 And what is right with these guidelines

So, when the "new" wiki started, there was quite a bit of discussion here and on the haskell list about what was an appropriate style for the wiki pages, considering that the site is meant to be a resource for new and exsisting Haskell users and as such, were desired to be reasonably consistent in style. These guidelines were the result. A variety of people edit pages to bring them into the stylistic guidelines, but if anyone is not happy with the current set, this seems like a good place to discuss changing them.

Andrea's link to the "WikiGnome" has some very good pointers about stylistic changes being applied to the edits of newcomers, and an even better one about dropping the argument. So this is my last edit about the subject :) --BrettGiles 21:58, 25 July 2007 (UTC)

Style consistency is not a primary goal of a wiki. A primary goal for the wiki is always having new people contribute to its grow. If you think that stylistic guidelines enforcing must be achieved regardless of the consequences than you should drop wiki technologies and use a blogging system or other kind of content management system. Instead, if you want to use a wiki, you should try to stick to the wiki philosophy as close as you can. --AndreaRossato Thu 26 2007 07:27 CEST
I'd like to point out that I perfectly understand that your effort has the aim of improving this wiki, and I don't think that style consistency is something to be avoided. What I'm trying to do, is to help finding a better way of achieving style consistency without increasing the level of entrance for new users. I hope you - Brett - will understand I have nothing against you. But I would like you to take into account the perspective of a newcomer too. I hope you are going to keep on discussing these issues with me. That would be helpful for the both of us. Thanks for your kind attention. --AndreaRossato Jul 26 2007 10:05 CEST.

And that leads me to the second real big issue: page renaming.

[edit] 7 Why Page Renaming Is BAD

Wiki page titles are URI, and URI should be persistent over time.

When you rename a page you are breaking URI persistence. A redirect is only a work around. A bad work around.

You did a lot of page renaming lately. By doing so you broke a lot of URIs.

You are also breaking the structure of this wiki, by creating a false hierarchy of pages. In a wiki all pages are top level. Hierarchy and wikis belong to different worlds.

I do believe that this guidelines are used in a vary bad way. I would like you to stop. Or at least to seriously reconsider your way of enforcing them.

AndreaRossato -- Wed Jul 25 2007 19:57 CEST

[edit] 8 Amendments Proposal

I think we could use this episode to grow, as a community. I suggest some amendments to these guidelines:

  1. enforcement: we could add something about guidelines enforcement, referring to the link I posted before: the user's Talk page should be used instead, and cosmetic edits should be ruled out as a bad practice, incompatible with the wiki philosopy;
  2. page renaming: we should adopt a very strict policy for page renaming. URI persistence should be the primary goal, so page names can be changed only within a very short period of time after page creation, only for compelling reasons and only with the consent of other users, after discussing it in the talk page;
  3. wiki structure: I'm not going to make any proposal but I would like you to think about the fact that wiki pages should be all top level, with no (false) hierarchy. This means that using slashes in page name should be considered bad practice.

I hope I will find people willing to discuss these proposals. Thanks for your kind attention. --AndreaRossato Jul 26 07:59 CEST

Hi Andrea - I would suggest a few things regarding this:
  • Let's move the proposal to the top of the page so that it is the first thing people see. We may even want to group the rest (or some of the rest) as old history.
  • It might be a good idea to advertise this on the haskell mailing list and the haskell-cafe lists. Some people who are interested might not check the latest changes. Previous discussions seemed effective to me because there were multiple points of view.
--BrettGiles 01:24, 27 July 2007 (UTC)
So, a month has gone by with no changes / additions / updates to this page. I wonder if anyone supports or disagrees with the proposal by Andrea? --BrettGiles 20:10, 24 August 2007 (UTC)