by the way here are the blender guidelines if someone wants to take a taste ---> http://wiki.blender.org/index.php/Dev:Doc/Code_Style <http://wiki.blender.org/index.php/Dev:Doc/Code_Style>
On Tue, Aug 5, 2014 at 1:37 PM, kilon alios <kilon.al...@gmail.com> wrote: > 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 >>>>> >>>>> >>>>> >>>> >>> >> >> >
