Hi Kilon,

Please, let's get positive :).

I really do not see how your remarks apply to the current situation. We put quite some effort in documenting GT tools through posts on the humane assessment blog (in the meantime, the page should be more reliable - I hope) and through examples in the image. We took specific care exactly in providing examples so that people can have something to guide themselves by.

In fact, we did not release until we had those examples. Just look at the announcement of Spotter and you will see that it has a significant usage documentation.

If it's not enough or not in the right place, you have to get specific and we can address those problems, but you cannot say that there is no documentation because that is simply not true. I think we have enough material to create a couple of chapters in a Pharo book, or even a book on its own, and I think it is reasonable to assume that given that the material is available we can find the rest of the effort to produce the "official" documentation.

Cheers,

Doru

On Mon, Dec 8, 2014 at 1:56 PM, kilon alios <kilon.alios@gmail.com> wrote:

"But, those tools are already added. And they are documented on the��humane-assessment.com��blog, and this can serve as a strong basis for a more official documentation."

my issue is not "when" but "whether" . If you want to wait out the release of Pharo 4 to make official documentation, thats fine by me . I take late documentation over no documentation, any day.

The problem I see with Pharo and one factor I feel it may even lead to the demise of Pharo as a project is that we see new and very exciting sfuff added to Pharo like your tools, but the documentation part is lackaster to say the least. The real problem comes when the original author decides to abandon or not further develop his tools it becomes extremely difficult for new people to come in and contribute. The very fact that now we replace the old workspace with a new tool is the testament to this problem. I think the situation would be dramatically��different if Worskpace was fully documented, both at the user level and developer level. Its afterall an extremely important tool for Pharo. If that was the case we would have seen a natural evolution of workspace which would have made Playground far less needed.��

So its not that I disagree just with you I disagree with the general management of Pharo that follows the mentality "let the new features in and we worry about the documentation later on".�� No , no and NO!

��I was recently asked by a newcomer to Pharo being a python developer himself whether he should invest in Pharo . He wanted my opinion because I have experience both in python and pharo . I was not suprised to find out that he struggled with the documentation and he was really reluctant to give Pharo a serious try. He loved the features and all that but his learning was a much bigger pain than his experience with python and other programming languages. I ended up recommending him to ask more question here in the mailing list and he replied he did not feel comfortable asking question that for him were "stupid". Can I blame him ? Of course not. He was not aware of many of the blog posts and other source of documentation that are not "official".

Dont know who that person is and how important as a member would become for the Pharo community but I can clearly see his problems being common to anyone or almost anyone introduced to Pharo unless that person comes already with a Smalltalk background.

What I do know is Pharo needs new people to come in and take it further and in order to do that we need to build a Pharo that is as inviting to newcomers as our abilities permits us to. Putting documentation as a second priority is a recipe to disaster.��

www.tudorgirba.com

"Every thing has its own flow"