yes I have bought PBE and Deep Into Pharo and I have read at least 3 times each book , I love them. The documentation is well written.
PFTE is turning into a well written Pharo bible, so yeah things are going very well on documentation front. I am helping with porting PBE to Pharo 3, first 3 chapters are already ported. I will start chapter 4 sortly. I think the one thing that misses in PBE is a chapter on Object Orientation. The book assumes that the coder is already familiar with OOP and so the chapters are not beginner friendly for people not used to OOP. I am considering making a chapter about it fairly soon. I will add it to my "Pharo Universe" book that has a repo here https://github.com/kilon/Pharo-Universe and people can get the pdf here https://ci.inria.fr/pharo-contribution/job/PharoUniverse/lastSuccessfulBuild/artifact/ I also have translated the chapter on Pharo Sound from PFTE which is also included in the book as a separate chapter. I have not checked the automatic translation from google so mistakes may be inside. On Fri, Jun 20, 2014 at 2:42 PM, Freemail <[email protected]> wrote: > Documentation is not that bad. Good parts are > definitly pharo by example, for the enterprise and deep into pharo. > But roassal2 for example has many undocumented classes. > I am willing to help here. > > At the moment I am trying to get all athens examples to work. > > And of course, people in this list are really helpful, > but it would be good, if problems and solutions don't get > lost in this mailinglist. > > Nicolai > > On Fri Jun 20 12:47:24 2014 Sven Van Caekenberghe <[email protected]> wrote: > > You are not targeting me, you are targeting everybody, that is why I, as > > a member of this community trying to improve things, feel offended. > > > > By saying 'the class comments are not good', you imply all of them. > > > > If I say 'people from country X are lazy' or even 'many/most of them are > > lazy', most people of that country, especially those who are > > definitively not will be rightfully offended. It is a generalisation > > that creates a bad reputation which is unfair. > > > > Of course you don't have to call out individual people, but if there are > > large packages out there (inside Pharo even) with 10s or 100s of classes > > with zero comments, then we as users have every right to say WTF !? And > > for me, those are terrible parts (with respects to documentation), > > because it is very hard to even start looking at the code and find your > > way. > > > > Spec _is_ partially documented - the website www.spec.org and the > papers > > are pretty good - it took Ben and Johan lots of time and I appreciate > > that a lot. > > > > The problem of Spec is that it is a bit strange, hard to get your finger > > on (it is a UI specification, abstraction and composition layer, not a > > GUI toolkit as such). It confuses people (things are called model, but > > these are UI models, not domain models). Furthermore, it evolved a lot > > so that there are historic inconsistencies between current code, > > examples and documentation. > > > > But I know you are helping to improve Pharo, especially around > > documentation, so I am not angry at all - I know for a fact that the > > situation around documentation has been improving a lot, and > > improvements accelerated in the last year. > > > > On 20 Jun 2014, at 12:17, kilon alios <[email protected]> wrote: > > > > > " It sounds a bit like there is no documentation at all" > > > > > > Ι never implied this, and I refuse to believe that my wording can > > > sound like that. I just say that the class comments are usually too > > > small and many important classes are not documented at all. I don't > > > know why you think I targeted you specifically with my comments. > > > > > > "terrible parts" is not the word I will use. I find the lack of > > > documentation frustrating but that does not make the classes > > > themselves "terrible". Pharo has its fair share of messy code but I > > > have failed to see something I would call terrible. > > > > > > Its awesome that you spent large amount of time documenting, but all I > > > said is that documenting key classes in the range of 10-15 lines each > > > should not take a lot of time and pharo developers should do it. Thats > > > my opinion, you are more than welcome to disagree or ignore it. > > > > > > I am willing to help any way I can. I am not willing to put blame on > > > people. > > > > > > I do feel however because I believe I am a logical person that people > > > that are introduced to Pharo will be disappointed in this department > > > as I am. I think this is unfair to Pharo, because you guys have put a > > > lot of effort in it that partly goes to waste. Imagine what would > > > happen if people had easy access to the libraries , how many more > > > would contribute and help pharo. > > > > > > I cannot imagine where I would be if there was no PBE or PFTE or the > > > class comments that already are in there. For me any form of > > > documentation is like bread and butter. > > > > > > Am I unreasonable ? > > > > > > I hope not. > > > > > > > > > > > > > > > On Fri, Jun 20, 2014 at 11:45 AM, Sven Van Caekenberghe <[email protected]> > > > > wrote: I am a bit offended by the generalisations in your remarks, > > > Kilon. It sounds a bit like there is no documentation at all. > > > > > > There are several books, covering many of the high level aspects. > > > > > > There is lots of documentation in the image, many class comments are > > > pretty good, as are many method comments - even quite a lot of > > > implementation comments can be found. > > > > > > OK, there are some terrible parts as well, and some people seems to > > > make a sport out of _not_ writing any comments at all - please call > > > them out specifically, but don't generalise. > > > > > > I have spent a large amount of time documenting all code that I > > > published as well as writing separate high level documentation and > > > tutorials for most of it as well as for Pharo in general. I know many > > > others who did the same. > > > > > > On 20 Jun 2014, at 10:10, Yuriy Tymchuk <[email protected]> wrote: > > > > > > > I have not worked with spec a lot, but I think that it’s nice in > > > > terms of comments, they are very helpful. Also lately I’ve worked > > > > with Roassal2 - no comments at all, but you can ask Alex for help :) > > > > > > > > Uko > > > > > > > > On 20 Jun 2014, at 10:06, kilon alios <[email protected]> > wrote: > > > > > > > > > yes good idea Damien , thank you. Right now I am working with > > > > > Rubric building a new workspace tool basing it on the rubric > > > > > example. Spec and Morphic are on my list too. > > > > > > > > > > Should I open also an issue on the bug tracker with a slice of my > > > > > class comment ? Or is posting it here enough ? > > > > > > > > > > > > > > > On Fri, Jun 20, 2014 at 10:47 AM, Damien Cassou > > > > > <[email protected]> wrote: > > > > > > > > > > On Fri, Jun 20, 2014 at 9:10 AM, kilon alios > > > > > <[email protected]> wrote: Saying that I will start adding > > > > > class comments wherever I can but obviously the people that have > > > > > created the code are far more qualified than me . > > > > > > > > > > > > > > > I suggest that you ask on this mailing list when you would like to > > > > > have documentation on a class and you can't write it yourself. > > > > > That way, we all will read the answer. Hopefully, someone, will > > > > > merge this and write a class comment. > > > > > > > > > > > > > > > -- > > > > > Damien Cassou > > > > > http://damiencassou.seasidehosting.st > > > > > > > > > > "Success is the ability to go from one failure to another without > > > > > losing enthusiasm." Winston Churchill > > > > > > > > > > > > > > > > > > > > > > > >
