Hackage wiki page per project discussion

Purpose of this page ?

collect thoughts about whether we should provide a wiki page (and maybe even more advanced features such as bug trackers) for all projects hosted on hackage

I'll post a link to this page to haskell-cafe so everyone should participate

Why a Wiki

We do have about 2000 packages on hackage. Hackage was made life easier. While packaging some packages for nix (using Hack-Nix) I had to write some patches.

If you have a patch what to do? Duncan Coutts proposed contacting the maintainer. If you don't receive replies within a time frame write to the haskell-cafe mailinglist. If you can't find him become the new maintainer.

While contacting the maintainer works very well within 3 days in most cases there are situations where maintainers can't reply because they are on holiday or got very busy.. In these cases I'd like to put my patch somewhere so that others can find them.

What could a wiki page be used for?

a) patches (which are removed when maintainers integrate them upstream)

b) Howtos and pitfalls (written by users or maintainers)

c) references to similar projects pointing out differences.

d) a smart lazy changelog. If a user hits a change he can add this to the

 wiki so that others can find out faster which version constraints to
 add to their .cabal file.

 This looks like this:
 2.20: renamed foo to bar.

 2.48: type change of iwillneverChange :: Int  to  Maybe Int

e) a list of changes which will go into the next release of a package.

  This may help you figuring out whether you should download the darcs repository.

f) many other ideas I can't think about yet.

...

implementation details:

design could look like this:

The link would point to the haskell wiki having the url suffix /project-name.

When a wiki page can replace a .cabal file update

• naturally it takes some time until most recent cabal updates are used by mainstream.. Eg there is a way to add repository locations now.. But have a look at happy.cabal and smile :) Btw: I adopted this usage of the source-repository field for one project.

• minor dependency changes

• tell users about experimental branches

• it's easier to provide important information such as:

 "This package is superseded by XY because: ..."

• • We already have a mechanism to deprecate packages or to mark them as superseded. --DuncanCoutts 00:25, 12 December 2009 (UTC)

Marc Weber: Can you explain how this works or point me to the documentation?

The main point about this wiki idea is that you can attach arbitrary information and you don't have to wait for anyone to do so. Get things done. Provide patches. Link them on the wiki. Come back later and discuss your proposals with the maintainer. Keep summaries of discussions on subjects accessible by everyone. ...

Of course I know that the maintainers are the people doing the real work. But look at it from a different view: Having such a forum for all projects by default also means that a maintainer can let others do some of the work knowing that they don't have to reply within some days.

The wiki can host all information which may be useful but which wasn't foreseen by hackage or cabal devs. We must keep agile and move forward only.

Concerns

My (DuncanCoutts) concern is about the consent from package authors. Hackage is a social bargain. We ask package authors to distribute their work through hackage because it provides benefits to the community. If we impose too much on package authors then they may decide it's just not worth it.

In particular, if we automatically create a wiki page for every package then we are imposing additional obligations on package authors. As a package author I might be concerned that this wiki page duplicates an existing home page or bug tracking system. If there's a wiki page about my project then I am effectively obligated to check it from time to time, since users will inevitably report bugs etc there. It is that extra obligation that package authors may resent.

There is no problem with such a feature being opt-in, but whether it is something we require and impose on package authors needs much more of a social consensus before we go ahead.

Reply Marc Weber: Everybody knows that it is wiki content and will take care.

About effort: Note that package authors can watch their wiki pages easily. Authors and maintainers already do the hard work. Watching a wiki page is not mach work compared to writing a library. But they may find wiki contents of foreign projects that useful that they provide some contents their selves

The above concerns amount to saying that there is (or may be) no value added for the user but nevertheless makes extra work for the maintainer. My (Daniel Wagner) concern is that there may actually be value removed for the user. A bad, incomplete, or non-existent wiki page can be worse than no page at all, because new users may view the wiki page as the canonical resource. This is especially so because many of the smaller projects have minimal or non-existent homepages (often just the root of a darcs repository) and minimal or non-existent documentation; this puts users in the habit of searching elsewhere for information about using the package. Maintainers that do end up putting effort into their project's pages and documentation will suffer as a result, especially if the projects are too small to garner many wiki-editing users. In this case, an unhelpful wiki page may scare away potential users, despite the existence of other useful resources.

concern "The wiki will be outdated"

True. Every user must know that wikis naturally are out of date :) But the question is: Can one wiki page (containing an example) generate more value than some outdated pages cause damage to you?

It's hard to say because haskellwiki wiki pages can be found when searching from the start page as well.

Maybe we can ask users to add the package version so that users will see themselves that content is outdated?

Don't think about other people. Think about yourself: Do you mind reading some outdated wiki pages? Do you appreciate the valuable contents which will be exist as well? If you don't mind reading some outdated pages and if you'd like to see more examples about how to use packages you basically support this idea! Let's not forget that haskell.org is a wiki itself. And naturally parts are outdated as well. You still don't want to miss it, do you?

wiki alternatives

If content isn't put on a wiki what do people do instead?

• They may do nothing (bad)
• They may write a blog (bad because others don't find it or because content gets out of date). Which way is more likely providing you with valuable information: A blog found by google or an attached wiki page people can keep up to date?
• They may write to the mailinglist. Things are archived forever. On the wiki they are as well but not only a small amount of visitors ever looks at the history of a page..

my project already has a wiki ..

Fine. In this case the haskellwiki wiki page will only have one link telling the user about your page.

progress and feedback

I've send a short mail to about 100 maintainers to get to know what they think about this idea.

Consider adding your name only for spam reasons (but send your emal address to marco-oweber@gmx.de so that I can associate them with packages on hackage to got to know who didn't reply)

I support this idea:

• marco-oweber@gmx.de (Marc Weber)
• clawsie@fastmail.fm (Brad Clawsie)
• newanon@yandex.ru (Oleg Ivanov)

I support but want opt-out:

• f.nfgnava@tznvy.pbz/rot13 (Sergey Astanin) I think default project wiki is a good thing for users, especially given that many projects don't have links neither to the web page nor to the bug tracker, some are unmaintained public domain, and some don't have even e-mail of the maintainer. However, I think that this wiki policy should be applied only to such “orphaned” projects without evident maintainer/infrastructure. When there is a valid link to project page, bug tracker or stand alone wiki, it's better to direct users there.

I support but I want opt-in:

• daniel@wagner-home.com (Daniel Wagner) I believe opt-in is the Right Thing, so would vote here even if I didn't have the misgivings I mention above
• daniel.schoepe@googlemail.com (Daniel Schoepe) In general I think it's a very good idea, but imposing it on every package author might discourage some, especially people new to Hackage.
• the idea makes me nervous, but I can live with opt-in (Eric Kow)
• vandijk.roel@gmail.com (Roel van Dijk) I wouldn't mind it as long as it is completely optional. But it is already supported just by setting your homepage to a haskell.org wiki page. And you can always ask a maintainer if he/she can create a wiki for a project or if it's ok if you create a wiki for their project.

I don't like the idea even if there was a warning such as "This content is contributed by maintainers and users and may be out of date.":

If you vote here, make sure you've read "wiki alternatives". You can clean up the wiki page. You can't clean up foreign blogs.

• EvanMartin (exactly what Duncan wrote -- I don't have time to vet a third-party page and keep it up to date; I have seen obsolete wikis for too many projects in my time. If I want to use a wiki I could just set it as the home page for my project. Consider adding a "wiki" link to the package description format.)

I don't care:

I won't tell you:

Anton-Latuka's direct response Anton-Latukha (talk) 10:27, 7 February 2021 (UTC)

I would start with that I am a Wiki-minded guy. Formerly quite active on ArchWiki, learned a lot about MediaWiki engine and went that far that hanged-out and discussed things with ArchWiki admins a bit at one point.

I wanted to help the ArchWiki design, but it went nowhere. Just as also my trying to help to migrate the HaskellWiki into a containerized world, and after that - the Nix world.

With my father, we won a 1-st prize in WikiMedia Ukrainian scientific photography contest a couple of years ago. It is to say, I know a little bit here and there to be able to say something.

• Overall, the idea is sound.
• The main goal - is to direct and tie the community enough to the Wiki, that community becomes to stick. People stubbornly keep trying to abandon the Wiki. While Haskellers are knowledge-minded people, the vast majority of even Haskellers know zero about the cornerstones of the Wiki's, while the Wikis are a main community knowledge storage human civilization currently has. But there is nothing better than a community that has a great wiki.

• We need to look to, and draw from best Wikis. To look the level of knowledge and effectivity and quality of life in an Arch Linux community, or a Gentoo community, the core secrets of which is that the knowledge hubs of them are their first-class Wikis. They do the thing properly and others (we) need to draw from their exp heavily. Plain stealing of organization from those Wikis is the way: Salvador's Dali: "Those who do not want to imitate anything, produce nothing." Or "Immature artists borrow; mature artists steal" as even Igor Stravinsky said. In this case - stealing as much infrastructure and established exp those Wikis directly applies. I'd approached them and asked to steal from them, for example ArchWiki:Help:Cheatsheet and everything it implies to have on the Wiki.

• The ArchWiki had a period of a quantum-leap, that I wanted to reintroduce to the understanding of to ArchWiki admins. To have a policy that "it is Ok to create a link to the not existing keyword", since those are marked red anyway, but also helps to blow up the content creation and interlinking inside the Wiki, which is a great thing sometimes. It is just the difference between static linking and dynamic linking. Dynamic linking. The ArchWiki had that period, it was trendy to shoot article links from the heap to indicate that "such article is needed", then other contributors come around click the theme they love and populate the article, or alias it to the proper place in the Wiki. That was the moment ArchWiki was the most actively developing place in Wikis I've seen. You may remember that also.

• But you want to push it (applying Wiki to the community) - too bit far, and the truth seems to be in the middle. It needs just the right push, if you push to hard on maintainers - they are stingy. The ignorance prejudice of not knowing is strong even in Haskellers. People need to be properly directed, taught to use the Wiki for what it is for. For example - with smart encouragement of interlinks policy.

• Using the Wiki as a bug tracker system is not a sound idea. People would oppose that actively. But what formulation is sound and effective - is to use it as a backup or a sum knowledge storage which it is. A topic & topic problem-solution gatherer - is. For example, ArchWiki has large sections on ArchWiki:systemd or ArchWiki:KDE.

• The Wiki content is in no way or form bears the maintainer responsibility - people are imagining that, Wiki goes with HaskellWiki:Copyrights, just as any Wiki does, and any Wiki license the first words are "THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND". The knowledge gathered on the Wiki belongs to the Wiki & to the public, and not to the opinion of a package maintainer. Wiki is a knowledge and, very importantly, an adequate critique engine for the community. For another example - the package maintainer is not responsible for what people write on StackOverflow.

• What is a good idea - is to get a list of the most well-known Haskellers that are on StackOverflow, they have a lot of great content there. And StackOverflow content. And ask them politely to be able to gather their responses in the Wiki. StackOverflow public#licensing, all StackOverflow threads are Wikipedia:Creative Commons license, Wikipedia:Stack Overflow. We, as a Wiki is fully compatible with the license under which authors provide the StackOverflow the content, since authors grant is as a CC BY-SA, we can copy it. Especially from the [Official StackOverflow licensing document]:

 From time to time, Stack Overflow may make available compilations of all the Subscriber Content on the public Network (the “Creative Commons Data Dump”). The Creative Commons Data Dump is licensed under the CC BY-SA license...

• "The bounding" is free for us - since it legally means the full rights of any Wiki use, since MediaWiki wikis are bijectionally fully compatible with CC BY-SA licenses particularly. And in any legal president, Wiki may have - the StackOverflow as a company - not interested to have any legal precedent with the Haskell community. Because, `Y'know` how that would be perceived by the developer's community. If Microsoft buying GitHub has such backlash, imagine the backlash of StackOverflow ever somehow legally challenging both the Wiki and Haskell communities at the same time - it is full destruction of StackOverflow's public reputation, and it is built on a public.

• As it is shown the StackOverflow content is CC BY-SA, so it is free to be used as Wiki content.

Those are some of my ideas

• I personally think it is very sound to create per-package page, but not pretend it is somehow a kinda-official bug tracker, because it is not, it is community info on the package. Well, if only for brevity to use it as a public hype controversy stunt to leverage the hype, so that society filters-out the themes themselves and form the Wiki themes themself. AKA I am interested in recursion schemes currently, so I would be interested to see that theme and package discussion around it blowing up and forming a recursion schemes.

So from that point of view - it is a good idea to do to revitalize the Wiki. But also ```afaik``` Wiki needs to increase the infrastructure access team and do some MeadiaWiki engine work and expand maintainer team overall. For example, I would be happy to have an InterWiki list expansion and provisioning of the WikiMonkey bot in user accounts, or at least to allow Wiki Monkey bot to be leveraged by users ArchWiki:Bots, and the best way to work on that is to have HaskellWiki deployment reproducible and have a backup of the Wiki, so maintainers and contributors can experiment on extending the Wiki.

users view (beginners)

Daniel Wagner told me that the thinks beginners will suffer the most. So I'll start a thread on beginners@haskell.org and ask them :-)

I'm a beginner, I don't mind reading outdated content. When I see a code snippet I'm going to copy paste it int ghci. If it doesn't work may be challenged and may fix it. Of course I'll contribute by solution and put it on the wiki. I think that such a scratch pad is a nice idea in general.

• put your name here

I'm a beginner and I fear reading about outdated content. This means that you fear the damage reading outdated content is bigger than the gains you have by reading up to date contents.

• put your name here

mailinglist threads

• haskell-cafe

• beginners@haskell.org

Notes

You can watch this page