Squeakapedia?
Locked
 
|
Hi all,
Problem: Documentation of squeak and varients is a bear to find in an organized fashion. This has been true for quite a while. It is true now. It will be true for a while into the future. The current tools for developing and organizing documentation are poor. In particular our swiki is old and creaky when compared to readily available free platforms, namely MediaWiki and Wikipedia. The idea of developing and storing squeak user documentation in a mediawiki environment seems attractive to me. I have been editing on that platform for a year now. I can point to several advantages: First a large number of people are familiar with it already. Second a large number of people have developed it and made it comfortable. The edges have been rounded off. In addition a large number of people continue to develop it. It has the driving force of necessity behind it. Thirdly it contains separate spaces for Main articles, Users, and discussion forums. Each user and article has a companion discussion space for meta comments and interuser messages. Templates and transclusion provide a way to write once, read anywhere. Categories are available for organizing and finding content once its been entered. Etc. Basically, I find the idea of putting documentation and guidance there attractive. I can think of two ways to gain a media wiki space for squeak. The low road would be to use an already existing mediawiki farm like wikia to establish a squeak wiki. This would be low cost and low maintenance. The disadvantage would be a loss of direct control and putting up with commercial content that wikia contracts. The high road would be to implement a mediawiki or wiki farm on a server we controlled. This would allow control over content and the prevention of intrusive and inappropriate advertising. In return it would take someones (possibly plural) time and effort to implement, maintain, and upgrade the service as needed. By either route there would be an open way to add content and collect and organize information documenting squeak. The possibility of getting a wider community contribution. Currently we are stuck with only masters being able to make significant contributions. Consider this an open letter to the SOB to think about this. And an open plea for people who could help make it happen to step forward. I could and would be willing to help by adding content if such a wiki existed. Yours in curiosity and service, --Jerome Peace |
|
|
I've used lots of wikis over the years, starting with the original
c2.com wiki. While each had its unique features that made it interesting, basically they were all good. Wikis are cool and, when there is a community behind them, can be very powerful. The squeak wiki has fallen out of favor. It used to be extremely useful and was used a lot, it isn't used as much now. I don't think that its problems have much to do with the platform it is running on. While Mediawiki is certainly a very nice wiki, I think the problems of the Squeak wiki would be unchanged if it were a Mediawiki. So, what is wrong with the Squeak wiki? Why isn't it used as much? In my opinion, the problem is that, from a documentation point of view, there is no such thing as Squeak, rather, there are many versions of Squeak. Although there are some things they all have in common, they differ in some ways. If you make a separate wiki for each version, you fragment your community and have no way of dealing with duplicate pages. If you make a single wiki for them all, like the Squeak wiki did, you end up with lots of information that is still true for older versions but is no longer true for the latest. And since a lot of people are still running the older versions, you don't want to get rid of that information. The new way for making documentation, which is to treat it as source and to version it like source, solves these problems. It probably introduces some problems of its own, but I think it is probably the best alternative for creating good, long-lasting documentation for Squeak. -Ralph |
|
|
I, too, an fascinated by this question: _Why_ has the wiki "fallen
out of favor?" I am skeptical that it is because there are multiple versions of Squeak and the inherent out-of-dateness that creates. This is something that all forms of documentation face, even internal ones that are versioned with the code. Just look at how often code comments are found to be out of of date. The value of documentation is all about what we *decide* to put into it. So why, oh why, have we "decided" to not update the wiki? IMO, we, as a community, are stuck in this feedback loop; where something that isn't "new and sexy", does not deserve our time or attention. The lack of attention causes bit-rot, further deteriorating the image of the "old thing". But the irony is, one of the "new sexy things" (depending on one's perceptions, of course) is just an electronic version of something much older than the wiki. The Pharo community are making on-line "books", much more old-fashioned than a wiki. The Squeak wiki, to me, seems much more dynamic, hyper-linked, and "finer-grained". It also *designed*, originally, for this medium known as The World Wide Web.... :) This is not a criticism of Pharo or the electronic-book format; I like books and their more linear nature bodes well for tutorials. I just think another great resource, the wiki, sits right under right our nose, and the only real "deficiency" it suffers as a tool for documentation is that it doesn't have sexy colors or buttons, thus leading to provoking our psychotic feedback loop.. - Chris On Tue, Jun 15, 2010 at 5:13 AM, Ralph Johnson <[hidden email]> wrote: > I've used lots of wikis over the years, starting with the original > c2.com wiki. While each had its unique features that made it > interesting, basically they were all good. Wikis are cool and, when > there is a community behind them, can be very powerful. > > The squeak wiki has fallen out of favor. It used to be extremely > useful and was used a lot, it isn't used as much now. I don't think > that its problems have much to do with the platform it is running on. > While Mediawiki is certainly a very nice wiki, I think the problems of > the Squeak wiki would be unchanged if it were a Mediawiki. > > So, what is wrong with the Squeak wiki? Why isn't it used as much? > > In my opinion, the problem is that, from a documentation point of > view, there is no such thing as Squeak, rather, there are many > versions of Squeak. Although there are some things they all have in > common, they differ in some ways. If you make a separate wiki for > each version, you fragment your community and have no way of dealing > with duplicate pages. If you make a single wiki for them all, like > the Squeak wiki did, you end up with lots of information that is still > true for older versions but is no longer true for the latest. And > since a lot of people are still running the older versions, you don't > want to get rid of that information. > > The new way for making documentation, which is to treat it as source > and to version it like source, solves these problems. It probably > introduces some problems of its own, but I think it is probably the > best alternative for creating good, long-lasting documentation for > Squeak. > > -Ralph > > |
|
|
In reply to this post by Ralph Johnson
+1
----- Original Message ---- From: Ralph Johnson <[hidden email]> To: The general-purpose Squeak developers list <[hidden email]> Sent: Tue, June 15, 2010 3:13:28 AM Subject: Re: [squeak-dev] Squeakapedia? I've used lots of wikis over the years, starting with the original c2.com wiki. While each had its unique features that made it interesting, basically they were all good. Wikis are cool and, when there is a community behind them, can be very powerful. The squeak wiki has fallen out of favor. It used to be extremely useful and was used a lot, it isn't used as much now. I don't think that its problems have much to do with the platform it is running on. While Mediawiki is certainly a very nice wiki, I think the problems of the Squeak wiki would be unchanged if it were a Mediawiki. So, what is wrong with the Squeak wiki? Why isn't it used as much? In my opinion, the problem is that, from a documentation point of view, there is no such thing as Squeak, rather, there are many versions of Squeak. Although there are some things they all have in common, they differ in some ways. If you make a separate wiki for each version, you fragment your community and have no way of dealing with duplicate pages. If you make a single wiki for them all, like the Squeak wiki did, you end up with lots of information that is still true for older versions but is no longer true for the latest. And since a lot of people are still running the older versions, you don't want to get rid of that information. The new way for making documentation, which is to treat it as source and to version it like source, solves these problems. It probably introduces some problems of its own, but I think it is probably the best alternative for creating good, long-lasting documentation for Squeak. -Ralph |
|
|
In reply to this post by Chris Muller-3
Hi, For me the reasons for not using the Squeak swiki are mostly structure, versioning, ownership and the swikis relevance.The swiki is quite a mess and a hard to navigate so it's hard to find stuff.
When I look at stuff, I hardly never know what version of Squeak this is describing and if it's still relevant. If I then find out its relevant but need a change I'm unsure if I can change without interfering with other peoples work and references.
Then I wonder if its worth the effort to change stuff because the swiki is not relevant anymore... ugh... Karl
On Tue, Jun 15, 2010 at 10:06 PM, Chris Muller <[hidden email]> wrote: I, too, an fascinated by this question: _Why_ has the wiki "fallen |
|
|
In reply to this post by Ralph Johnson
+1
On Tue, Jun 15, 2010 at 4:13 AM, Ralph Johnson <[hidden email]> wrote: I've used lots of wikis over the years, starting with the original |
|
|
In reply to this post by Karl Ramberg
But I still find the irony to be that nearly all of the complaints
about the swiki seem to originate from the human-side of the equation. You are not the only one to refer to it "as a mess" but I hope you agree this is not a swiki technical problem. We humans were provided with a flexible, dynamic, hyperlinkable document structure. We are able to make a complex class-hierarchy and running code system called our "Smalltalk image" but this hyper-linked _documentation_, apparently is too much for us, as a community.. It would be relatively easy to straighten out... I just went to http://wiki.squeak.org/squeak/1 and... really doesn't look that "messy" to me, but then I'm sure I'm at a lower-standard than you.. :) When I don't want to navigate, I just use the "Search" button, it works.. > If I then find out its relevant but need a change I'm unsure if I can change > without interfering with other peoples work and references. Well, you should not be unsure, because the swiki was designed from the very beginning to be a "community maintained documentation". Anyone who creates a page may password protect it, thereby establishing their "ownership" if they wished. Even if they forgot to password protect it, every page also has version history, so if there was "inteference" it could be trivially rolled back. > Then I wonder if its worth the effort to change stuff because the swiki is > not relevant anymore... > For me the reasons for not using the Squeak swiki are mostly structure, > versioning, ownership and the swikis relevance. > The swiki is quite a mess and a hard to navigate so it's hard to find stuff. > When I look at stuff, I hardly never know what version of Squeak this > is describing and if it's still relevant. > ugh... > Karl I think you have succinctly articulated the negative feedback loop the swiki finds itself in, whether deserved or not.. :-/ > > > On Tue, Jun 15, 2010 at 10:06 PM, Chris Muller <[hidden email]> wrote: >> >> I, too, an fascinated by this question: _Why_ has the wiki "fallen >> out of favor?" >> >> I am skeptical that it is because there are multiple versions of >> Squeak and the inherent out-of-dateness that creates. This is >> something that all forms of documentation face, even internal ones >> that are versioned with the code. Just look at how often code >> comments are found to be out of of date. >> >> The value of documentation is all about what we *decide* to put into it. >> >> So why, oh why, have we "decided" to not update the wiki? >> >> IMO, we, as a community, are stuck in this feedback loop; where >> something that isn't "new and sexy", does not deserve our time or >> attention. The lack of attention causes bit-rot, further >> deteriorating the image of the "old thing". >> >> But the irony is, one of the "new sexy things" (depending on one's >> perceptions, of course) is just an electronic version of something >> much older than the wiki. The Pharo community are making on-line >> "books", much more old-fashioned than a wiki. The Squeak wiki, to me, >> seems much more dynamic, hyper-linked, and "finer-grained". It also >> *designed*, originally, for this medium known as The World Wide >> Web.... :) >> >> This is not a criticism of Pharo or the electronic-book format; I like >> books and their more linear nature bodes well for tutorials. I just >> think another great resource, the wiki, sits right under right our >> nose, and the only real "deficiency" it suffers as a tool for >> documentation is that it doesn't have sexy colors or buttons, thus >> leading to provoking our psychotic feedback loop.. >> >> - Chris >> >> >> >> On Tue, Jun 15, 2010 at 5:13 AM, Ralph Johnson <[hidden email]> >> wrote: >> > I've used lots of wikis over the years, starting with the original >> > c2.com wiki. While each had its unique features that made it >> > interesting, basically they were all good. Wikis are cool and, when >> > there is a community behind them, can be very powerful. >> > >> > The squeak wiki has fallen out of favor. It used to be extremely >> > useful and was used a lot, it isn't used as much now. I don't think >> > that its problems have much to do with the platform it is running on. >> > While Mediawiki is certainly a very nice wiki, I think the problems of >> > the Squeak wiki would be unchanged if it were a Mediawiki. >> > >> > So, what is wrong with the Squeak wiki? Why isn't it used as much? >> > >> > In my opinion, the problem is that, from a documentation point of >> > view, there is no such thing as Squeak, rather, there are many >> > versions of Squeak. Although there are some things they all have in >> > common, they differ in some ways. If you make a separate wiki for >> > each version, you fragment your community and have no way of dealing >> > with duplicate pages. If you make a single wiki for them all, like >> > the Squeak wiki did, you end up with lots of information that is still >> > true for older versions but is no longer true for the latest. And >> > since a lot of people are still running the older versions, you don't >> > want to get rid of that information. >> > >> > The new way for making documentation, which is to treat it as source >> > and to version it like source, solves these problems. It probably >> > introduces some problems of its own, but I think it is probably the >> > best alternative for creating good, long-lasting documentation for >> > Squeak. >> > >> > -Ralph >> > >> > >> > > > > > |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |