Blender wiki is badly maintained because developers are only forced to document when they add a feature and not when they improve it etc So many of the pages are outdated , pictures are from version years ago and look very diffirent to modern versions of Blender. Its not a wiki problem its a maintance problem. But Blender has a huge community of video tutorials online. Even professional communities like Blendercookie and blenderguru. So it can afford to not care so much about keeping everything uptodate. Still people complain about the Blender wiki .
If Pharo accepts source code that at least has proper class comments then thats a big step forward. Even a hint of documentation is 1000 times better than no documentation at all. I think that this will definitely bring more people to contribute. I think I can also help there too. d Blender also takes advantage of auto documentation, python offers doc strings, think of it as class comments and method comments with formatting. For example you can embed a unit test inside the class comment and the test will be runable by the user. The entire Blender API for python coders is auto documented this way. So I agree this a really good idea for documentation. Also pharo people have done a great job with Pier and Pillar. Its definitely more powerful than a wiki and having a solution especially tailored for Pharo is a big plus. We dont need a wiki. As long as everything is linked back to the main website its fine. Pillar is much easier to learn than Latex and not very dissimilar to wiki syntax. I am very happy with pillar personally and Damien's conversion from Latex to Pillar works very well too. Another good thing is that pharo documentation is really well written, there are things that are missing but most of it is a very good state. Its great not to have to rewrite documentation just because its not well understood. So its only a matter of keeping it updated. On Tue, Aug 5, 2014 at 12:20 PM, Esteban Lorenzano <esteba...@gmail.com> wrote: > > On 05 Aug 2014, at 11:05, kilon alios <kilon.al...@gmail.com> wrote: > > I don't question people contribution to Pharo. > > I do think however that we need to prioritize documentation. For example > Blender development works in a way that a developers adding a feature to > Blender main repo (not external code and external libraries) must add > documentation to Blender wiki for the users. > > > +1 > we do not like wikis (bah, I like them, but others don’t… and they have a > point: a wiki must be maintained, otherwise is a waist of time and effort). > but… since Pharo4 we started a practice which is: we do not integrate any > new stuff that is not correctly commented (in classes), with tests and (if > possible), examples. > > in the long way this is the best because Pharo relies a lot in > “autodocumentation”. > > now, we can improve this: > - even if new stuff has to come that way, most of the code inside image is > poorly documented, tested and examples. We can improve that. We need to. I > remember the comment per day Luc started a couple of years ago… is > complicated to have them running in long way (until documentation is > finished) because people get tired, but we could have a “two weeks > comments” each three months or something like that. Not perfect, but better > than what we have now. > - I dream with PetitParser integrated into Pharo, and then a > markdown/pillar parser into class comments, allowing us to have better > formating and references, etc. to improve navigation. > > and of course, more can be done: > -tutorials for newbies (your work on the videos is great there, btw!) > -example projects in different areas (I think the laser game is a good > one, but we need more “professional” examples: web apps, desktop apps, etc.) > -etc. > > > > Also Blender has coding guidelines that need to be followed in order for > code to added to main repo, does Pharo has something similar ? If yes where > is such a document ? > > > Not really (at least that I know). We should. > > > Also Blender mailing list is very active with major bug fixes and features > enhancement , in Pharo it looks to me that a lot of this discussion is > located to fogbug . That means however than unless you frequent there its > very difficult to track changes that affect your workflow. > > > we still need to find the best workflow, yes. I’m not happy with fogbugz > in general, not because of the tool, which is great (and I’m very grateful > that we have it), but because it does not seems to adapt correctly to an > open source project, or at least to our own project. Anyway, maybe if we > continue the "moving to github” effort, probably we will prefer to use the > github tracker, eventually (even if not as powerful as fogbugz). > > Esteban > > > Not just Blender but many open source projects work similarly. > > > On Tue, Aug 5, 2014 at 1:13 AM, Nicolai Hess <nicolaih...@web.de> wrote: > >> 2014-08-04 22:37 GMT+02:00 kilon alios <kilon.al...@gmail.com>: >> >> I can tell you why. Because its rarely is simple for people not familiar >>> with Pharo like me. >>> >>> I once tried to help Damien with PharoLauncher. I added the progress >>> bars you get when you download a new image it was simple as pie. Then >>> Damien recommended for me to try to add support to PharoLauncher for CLI . >>> I understand how Pharo does CLI stuff but was not able to understand >>> anything about how PharoLauncher downloads and handles images. I literally >>> spent hours trying to understand the internal architecture and gave up >>> after 2 hours or so cause I had no clue how things worked. >>> >>> Also finding a bug to fix in Pharo is time consuming, you have to go >>> through one bug after another till you find that you can figure out whats >>> wrong and how to fix. Its not easy and its very annoying at times. >>> >>> Generally what kills me is lack of motivation, I don't like reading >>> other's people code, I don't even like reading my code. I prefer >>> documentation , If I am to fix a bug I want at least someone to show me how >>> it works because figuring it by myself takes a lot of time and I am simply >>> not willing to invest that time just because people find documentation >>> something that should write one day when their software reaches version 1 >>> meaning years later. >>> >>> So you want to motivate people to contribute to bug fixes ? Do not allow >>> any code to enter pharo main distribution without full class comments. I >>> really mean "full class comment" not 2 , or 3 lines. >>> >>> PBE has been left hanging years after the release of 1.4 , why ? you >>> expect people to contribute to bug fixes even when the most basic of >>> documentation is abandoned ? >>> >>> Sorry if I sound harsh but you wanted a honest answer . For me >>> undocumented code is far more annoying than a bug or a missing feature. >>> >> >> I find it a bit to harsh :) >> +1 for more source code documentation, but keep in mind that there are >> people that may not do proper documentation (even change code >> or fix bugs and don't document their code) but doing A LOT for pharo >> behind the scenes. >> >> >> >>> >>> >>> On Mon, Aug 4, 2014 at 10:51 PM, stepharo <steph...@free.fr> wrote: >>> >>>> Hi guys >>>> >>>> I'm sure that most of you did not realize it, but Pharo does not >>>> magically improve. It improves because some of us are looking >>>> at the tracker issues and looking at the code and improving it. >>>> >>>> Since Pharo is yours I wonder why you do not take the time to improve. >>>> In fact, this is the key advantage of true open-source: being able to have >>>> an impact. An example, I was fed up to have a stupid widget to move >>>> method between protocol and classes between packages. I fixed it. >>>> It took my 20 min without knowing anything about Nautilus. >>>> >>>> And it improved Pharo Right now, Right there. >>>> Of course if more people would be improving Pharo we could also focus >>>> on enabling technology and frameworks. But >>>> apparently we have to choose either we improve Pharo now or we invent >>>> cool stuff that takes time. >>>> I wonder why I do not go for the fame of writing a cool stuff instead >>>> of just improving systematically the system. >>>> >>>> I wrote some roadmaps for people willing also to help. >>>> >>>> https://github.com/pharo-project/pharo-workingRoadmaps >>>> >>>> Stef >>>> >>>> >>>> >>> >> > >
