[OOTB-hive] Wiki updates (was: CE looking bad?)

[Richard Esplin]

Martin and I had a long discussion about the wiki on IRC. Since the topic came 
up on this list, I'll summarize here the information I shared there.

__A Brief HIstory of the Wiki__

* We have struggled with the wiki for at least the last four years. Jeff and I 
repeatedly tried to get people motivated to help clean in up. We discussed the 
problems during office hours off, Jeff blogged about it 
(http://ecmarchitect.com/archives/2011/12/22/1503), and I listed it as a hack-
a-thon project. Jeff founded a Google Group for wiki-gardners, but only got two 
volunteers (thanks Piergiorgio and Diego!).

* The wiki doesn't get much attention from anyone except for me. There is 
approximately one small edit a week, and few large edits a year.

* The relationship between the Alfresco Wiki and the official documentation has 
been unclear. The wiki ranks highly in Google, yet most of it is out 
of date. As our official documentation has improved, the wiki diminishes in 
relevance. Out of date documentation on the wiki is currently a major source 
of complaints from people that are just starting with Alfresco. This has led 
to people requesting that the wiki be decommissioned.

* Yet there are some valuable nuggets that still haven't made it to the official 
documentation, and it serves as a reference for previous versions of Alfresco.  
I wanted to preserve that information.

* I think its most important purpose is for collaboration with our open source 
community. It is where we document how our project works, and allow the 
community to participate in our governance process.

* Historically, the Alfresco engineering team used the wiki for preliminary 
documentation of ongoing projects. This is initially convenient, but quickly 
becomes a maintenance problem. Instead, these types of one-way communication 
should be blog posts which are clearly tied to a specific point in time. Over 
time this content should migrate to the official documentation.

* I documented my plan to clean up the wiki 
(https://wiki.alfresco.com/wiki/Wiki_Cleanup), and discussed my plan with 
people during the hack-a-thon last fall. I suggested Order of the Bee take 
over the wiki, but didn't get any take-up.

* After receiving no feedback for six months, I moved forward. I announced 
what I did in IRC, and no one answered. It didn't seem like anyone cared.

* To clarify the current state, I ran a script and marked the whole wiki as 
"obsolete" with a link to the official documentation. The bot touched about one-
thousand pages. We then unmarked the approximately 100 pages that are still 
relevant. I documented this in the wiki, and clarified the warning message 
based on feedback from Martin.

* A few weeks after I took substantial action, lots of people stepped forward 
to complain. However, the resulting conversation has been useful.

* Martin continuing to call my actions "vandalism", even after my explaining 
myself, is a bit hurtful. After reading Martin's appeal for help with the 
Honeycomb project, I thought he would be more sympathetic to my position. 
People won't step forward to help if their motives are questioned any time 
they do something you don't agree with.

__The Future of the Wiki__

My proposal is that going forward, the wiki should only be used for 
collaboration as an open source project, i.e. two-way communication. I have 
slowly been updating the relevant articles, and would appreciate help. A good 
example is the project overview page:

https://wiki.alfresco.com/wiki/Project_Overview

Please help where you can. A list of pages that need work is here:

https://wiki.alfresco.com/wiki/Category:Page_Needs_Work

If you come across a relevant page that has the obsolete notice, please remove 
it. But before you do so, consider if that page really belongs in the wiki, 
and who will maintain it. (Peter: I personally think the CMIS documentation 
should retain the "obsolete" tag.)

If you see an obsolete page frequently come up in a query, please link to the 
correct page in the official documentation. If you link to the Community Edition 
documentation, the URL will not change between releases.

If you find yourself sharing a wiki page because it contains useful information 
that is not in the official documentation, please report the issue to us and 
link to the wiki page.

If you were using the wiki for something that you think is not being accounted 
for in this plan, please let me know. And feel free to send me any questions 
or ideas you have on this topic.

This is my vision for the future of the wiki. We can change it at any time, 
but our approach needs to take into account the effort involved with dealing 
with the 900 pages that are currently confusing people.

Thank you for your interest in collaborating with me on this project,

Richard

-- 
Richard Esplin
Product Manager, Alfresco Community Edition
Tel: +1 801 855 0866
Mobile: +1 801 735 4220
Skype: esplinr

On Friday, May 22, 2015 20:00:04 Peter Monks wrote:
> G’day Mark,
> 
> The best solution is what Richard said:
> 
> “clear that tag on good pages or mark the ones that need work but should be
> kept.”
 
> This is an exercise virtually everyone in the community can participate in,
> as it’s both low effort / expertise (was a page useful? remove the tag!)
> and high value - over the long run it will allow us (the inclusive “us”,
> not the divisive “us”…) to remove pages that retained the tag - a kind of
> “Sieve of Esplinosthenes” if you will.  ;-)
 
> And while clearly outdated pages are obvious to longstanding members of the
> community, I suspect they were (prior to the tag) a significant source of
> confusion for newcomers who don’t know what they don’t know (yet).
 
> Cheers,
> Peter
> 
> 
> On 2015-05-22, at 12:33 PM, Mark Stang
> <markjstang at gmail.com<mailto:markjstang at gmail.com>> wrote:
 
> I was a bit shocked to see all the wiki pages marked as Obsolete.  I asked
> an "Alfresco Insider" who informed me that:
 
> Richard marked every wiki page obsolete. He is hoping people will either
> clear that tag on good pages or mark the ones that need work but should be
> kept.
 
> I don't know if the CMIS stuff was moved to docs or not.
> 
> Some of it is obviously out-of-date and has been for awhile.  The rest is
> still current AFAIK.  So, going forward, I am ignoring the warning.
 
> I am not sure what the best solution would be.
> 
> regards,
> 
> Mark
> 
> On Fri, May 22, 2015 at 1:24 PM, Martin Cosgrave
> <martin at ocretail.com<mailto:martin at ocretail.com>> wrote:
 I've read the
> whole thread, except I started a few messages in, and the last thing I've
> done is to come back to the first post and actually look at the chart in
> question. I actually don't have a problem with it, as has been said you
> expect marketing types to do that, but at least there at the bottom is a
> clear download link to CE. I couldn't be more pleased that the two are
> presented together. I'm sure that everyone must have had experiences
> similar to mine of knowing that a product has an open source version, and
> struggling to find any mention of it until you find the tiny 'Community'
> link in dark brown on black at the bottom of the page. 
> There is certainly no harm in creating a counterpoint page, it could be
> quite tongue in cheek, maybe we can put a lot of red X's next to EE :-P
 
> A quick side note about Honeycomb, there really is a lot of good stuff you
> guys could contribute, especially if you know puppet or a similar devops
> tool, but if not even just building it and commenting on or modifying the
> configurations we have chosen would be really useful. There are only two of
> us involved in it right now and I've been a bit busy starting a job and
> moving city in the last month or so. I just noticed it was mentioned a
> couple of times in the thread so I guess there is some value there and
> mindshare even if nobody's stepping forward.
 
> It's a shame the thread spiralled out of control at the end there. At the
> beginning it was really constructive and it's definitely worth going back
> and looking over those bits :-) . However it's obvious there are strong
> feelings on both sides. Personally I feel very strongly that the vandalism
> to the wiki pages which marks all the useful community-oriented
> documentation as obsolete be reverted.
<snip>