> On 09 May 2016, at 11:10, Dimitris Chloupis <[email protected]> wrote: > > Search wise you can use GTSpotter to search help topic, I even added that > myself as a plugin to GTSpotter at some point with even the ability to > preview help inside GTSpotter.
this would be something nice to add :) > > Look wise, sure pharo help isnt the prettiest thing but I would not it say it > sucks, it does its job okish, it displays help text. yes, but we need something better, in the future. Esteban > > If you want docs that are looking very good, Pillar is doing already that and > it outputs in the most portable formats, html and pdf , that makes it easy to > take documentation where you cannot use pharo, on tablets and smartphones. > > As a pharo developer I am very much against of cramming things that already > exist outside pharo image and do an incredible good job that would take years > if not decades for pharo to catch up , instead of putting things inside to > make things harder with close to zero benefit. > > Lets face it the only reason to put things inside the pharo image is with the > promise that we will be modifying , improving and extending them. > Documentation however is a large effort by itself , so why not instead of > worrying about a Pharo Documentation API , worry about the actual > documentation ? > > Personally I am more interested in reducing the complexity of Pharo and > increasing its documentation than the opposite. > > Funny fact: I used to be a big proponent of onboard/in-image documentation > but the great work of the Pillar devs made me change my mind completely. > Pillar for me documentation wise is the way forward and it already works > incredible well. I would not even complain if the help tool was completely > replaced with the a link to the pillar documentation , it does not contain > much documentation anyway, nowhere close to the amount and quality of > documentation produced by Pillar. > > On Mon, May 9, 2016 at 10:45 AM Sven Van Caekenberghe <[email protected] > <mailto:[email protected]>> wrote: > > > On 09 May 2016, at 09:37, Peter Uhnák <[email protected] > > <mailto:[email protected]>> wrote: > > > > How about WebDoc (or similar) serving up the API with class comments to > > make it searchable on the web > > > > Although the in-image help is really bad, I would argue that for the API > > itself it's quite the opposite. > > Pharo is centered around code, so there is a lot of different and amazing > > ways to search the API and easily find what you are looking for (including > > trivially scripted searching). > > I don't think that any web interface can compete with that (unless it's > > powered by Pharo itself). > > > > In fact there used to be WebDoc for Pharo API, however as there are no > > comments and examples it wasn't useful at all. You can do better search and > > actually try the code directly in the image, or search for examples. > > See http://files.pharo.org/doc/ <http://files.pharo.org/doc/> for WebDoc. > > I do totally agree with the fact that Pharo is first and foremost an in-image > IDE, we should concentrate on that. The web based documentation is mostly > relevant for search indexing and newcomers. > > > The wiki would also act as a place where the documentation can evolve > > until it is considered stable enough to include in the image. > > > > For this we have books imho. Simple documentation should be added to image. > > > > also have links to other blogs, etc. that may not be appropriate for > > in-image documentation > > > > I don't see why not, but it would be better to just copy the content > > without having to click (depends on the content). > >
