User:Duplode/Why Wikibooks

This essay originates from a reply of mine amidst a conversation in /r/haskell about software documentation that turned towards wikis and learning materials. I have edited the reply so that it makes sense outside of the original context.

Because developers love to code and hate to document, and only developers know their system well enough to produce good documentation. [...] But these are the same people who would write tutorials/howtos/examples/tips/hacks/SO-answers, rather than anything resembling official documentation.

Exactly. A tutorial should be a commentary on a reference text, and not the reference itself.

But that is the problem! Almost all tutorials, SO-answers, video tutorials on YouTube, blogposts are written by one person only. Even programming books are written by 1-2 people, most of the time. Why is that? I don't know yet.

Except for the SO-answers, I see two factors at play. The first one, I believe, is essential and ineliminable, while the second one is accidental and more tractable.

Firstly, such forms encourage, and even demand, that the content gets infused with a strong dose of personal vision and flair. That is because are too many subjective decisions that must be made when writing even a brief tutorial, let alone a whole book: choices about pedagogy, writing style, text organisation, visual presentation, and so forth. A personal vision, however, can be a difficult thing to share. Additionally, conflicting personal visions can cause trouble, no just because of ego clashes, but also because if mishandled they can turn the overall result into an incoherent mess (design by committee, "too many cooks spoil the broth"). That being so, author numbers tend to be small.

Secondly, the tools and workflows used to produce the materials do not encourage collaboration. YouTube is merely a publishing platform rather than an authoring one, and most blogging platforms are geared towards the single-author use case (GitHub Pages being the exception that confirms the rule).

The arguments above do not really work for Stack Overflow, given that it is a wiki and that SO culture strongly encourages objectivity. SO-answers, however, tend to be short; short enough that, if there is worth in pursuing a different strategy than that used by an existing answer, writing a new one can be easier than editing the existing one or arguing with its author. There is also another factor that tilts the balance towards writing new answers: gamification, i.e. teh repz.

I personally consider Wikibooks a failure; seriously, it's tiny compared to Wikipedia's success. One can blame terrible MediaWiki engine or lack of marketing [...]

And here is where things get even more interesting.

I agree that Wikibooks has not being a resounding success; it is quite far from that indeed. As you suggest, some of the reasons are contingent, including the lack of love and attention from Wikimedia and the inadequacy of the software for book writing (MediaWiki syntax is clumsy, achieving precise layout and formatting is an uphill struggle, the navigation tools are unsophisticated, the official PDF creator is broken, and the less said about Visual Editor the better).

And yet, even with all the discouraging factors, I am not giving up on Wikibooks. Why? Because writing open-source books through online collaboration is a beautiful idea, and it opens possibilities that aren't available with comparable media. To explain why I think so, I will dissect the characterisation I just made.

Books: A book gives you enough room to aim for things that are unreachable in ultra-objective SO-answers or goal-directed tutorials. Crucially, a book makes it possible to apply at length well-defined pedagogic strategies, and to present many disparate subjects (or even a whole language ecosystem) within a common conceptual framework. Books also have narratives, with twists and turns, that can not only help keeping the readers interested but also play a pedagogic role. If the ultimate goal goes beyond teaching specific techniques towards forming better programmers, the only facilitator better than a good book is a good mentor. All of that implies a book can be more than a collection of independent tutorials: I do believe continuity matters.

Collaboration: Writing with other people helps reining in your excesses, identifying your mistakes, and makes the writing experience less lonely. Writing with other people that you have not vetted beforehand exposes you to alternative viewpoints and constructive criticism. Not less importantly, helping to write the book you are learning from can be an incredibly rich experience, and also puts the point of view of the learner on the table (related to that, it should be pointed out that, in spite of its flaws, the MediaWiki software has historically done a good job in terms of keeping the barrier to entry reasonably low).

Online: Online collaboration eases a lot the pressure of getting it right the first time. There will always be someone to spot your typos (and I commit a lot of them!), and even more serious mistakes are very cheap to fix. As one of the Wikipedia mottoes goes, there is no deadline. There is also no deadline because it is much easier to keep a collaborative online book in sync with the evolution of the subject matter, as more people are empowered to do the updates and the latency in publishing the changes is much smaller. Finally, online publishing makes wide dissemination of the book easy.

Open-source: Open-source licensing means the book will not have its usefulness to learners, teachers and other authors restricted in arbitrary ways. It also makes it much less likely that the book will become unavailable due to unfortunate contingencies or the whims of some publisher.

A beautiful idea, indeed. By reading between the lines, however, you can sense there is some trouble in paradise. From the argument about the small number of authors it follows that there is an ineliminable tension between book (a coherent whole, strongly infused by personal vision) and collaboration (between multiple parties with potentially conflicting visions and motivations). Successful collaborative book writing requires a great deal of sensibility for dealing with this tension. Maintainers can be neither dictatorial (which alienates outsiders, who bring useful input) nor too lax editorially (which leads to the degeneration of the book into a disjointed hodgepodge of text fragments). Contributors can be neither too shy (which causes useful contributions not to be made) nor too assertive (which leads to ego clashes, drama and sub-optimal results). And, as you implied elsewhere, everyone involvement needs a to do a little self-effacement, given the need for tolerance, the necessary freedom in editing someone else's text at will and the relative anonymity of contributions to a wiki.

Even with such complications I believe the idea is worth trying, and that success is not impossible. Under the right circumstances, with a neither too great nor too small core group of co-authors who are able to agree on a shared vision, and with enough readers and eventual contributors to keep things moving, a collaborative book can flourish.

Something motivates people to write very long, detailed tutorials or solutions for no money or fame, but doesn't motivate them to do that on Wikibooks, and definitely discourages them from contributing to existing books. There are so many half-written, obsoleted, abandoned books there that I know nobody would ever finish. I would definitely not contribute to almost all of them, without doubt.

There are many reasons for the less than ideal state of affairs at Wikibooks. Some of them are the material contingencies I mentioned above. Books can be abandoned as Internet communities wax and wane, and books with a single main contributor are specially vulnerable to changes of direction in her personal life. There likely is a reverse network effect (or "broken windows" effect) at play, which I think is what you are trying to get at when you talk about the "many half-written, obsoleted, abandoned books". As suggested in this thread, the ethereal nature of wiki contributions and the relative lack of immediate individual recognition might also play a part, though I have doubts about it. Still, I don't think there is anything that makes Wikibooks' aims fundamentally inviable. That is partly because I know at least one success story: The Haskell Wikibook.

You might reasonably find it strange that I'm calling the Haskell Wikibook a success story, given how little we hear about it these days. But it was not always so. I don't know if you were part of the Haskell community back in 2006; I, for one, only joined much later. Back then, however, in the days before /r/haskell and Stack Overflow and RWH and LYAH, the Wikibook was a major learning resource, referenced all around the community. It was, and still is, one of the biggest wikibooks, with an ambitious table of contents that was largely backed by actual chapters. There were some rough edges to the book, certainly, but there were also chapters as good as anyting you might find elsewhere, if not better.

The Wikibook also used to fit the social patterns I tentatively identified here. There was a moderately small group of core contributors working with a shared perspective and balancing each other out - people such as Paul Johnson, Eric Kow and, a bit later, Heinrich Apfelmus. Some of those contributors were also in the process of learning Haskell themselves, while others were more experienced Haskellers. There was enough interest from the community to keep the ball rolling. And so effective collaborative writing did indeed happen for quite a few years.

So, in spite of all difficulties, success is possible in terms of useful results. I would like to broaden the focus for a moment to consider how community size and success are related. I claimed that collaborative book writing is best done with a relatively small group of core contributors. I believe that also applies to Wikibooks as a whole, so when saying that Wikibooks is a relative failure next to Wikipedia one needs to be careful not to use the size of the communities an immediate indicator of success. Though Wikibooks may be rather small, I am quite sure there would be serious trouble were it to grow as large as Wikipedia. The fact that each book implements a singular vision means that Wikibooks is actually made of many small interconnected communities built around the individual books, and that books need some degree of editorial independence to flourish. Unbounded growth of the project would likely lead to more centralisation, more bureaucracy, stricter rules and increased external interference over the work of co-authors. There would also be more toes being stepped on, and more wikidrama. In summary, many of the social problems contributors often identify in Wikipedia would be reproduced -- except that, while the extra strictness and at least some of the bureaucracy can be seen as a necessary evil in Wikipedia, in Wikibooks they would cause unqualified harm. Also, while Wikibooks is a little too quiet right now, I was active back in 2010, when there was more chatter in the common spaces, and from that experience I can tell that Wikibooks is a more receptive and less harsh environment than Wikipedia -- and that is unqualifiedly a good thing!

I'm not sure why, but my internal voice just says “nope”.

Well, frankly I would be very happy if your voice would start saying "yeah" instead :) Lately I have been helping maintain and tying to improve the Haskell Wikibook. From last year on Aaron Wolf (/u/wolftune) has been contributing regularly as well. Progress has been slow and at times inconstant, and there is a LOT of work to be done. But I believe that we have solid foundations in the beginner chapters, and that we are finally getting the book in touch with present-day Haskell. In spite of all the other great resources around us, I firmly believe the Wikibook has a role to play, with its quite distinctive pedagogic choices and its proven resistance to the effects of time. So I invite you for a visit. Have a look around, see if you like what you see and, if you feel like doing it, feel free to tweak something or to leave some criticism in the talk pages. You can be sure any changes won't vanish into wiki nothingness, as there will be at least one human (me!) watching the changes.