## 1. Help in general: The in-image help sucks hard… monospaced walls of text, no formatting, no styling, no images, and zero discoverability.
Some ideas — this is food for thought for moving forward, not something that I would expect anyone would do tomorrow: ### Simple-ish: online frontend * have an online frontend for all the help — because the first place most people will look is Google, and in-image help doesn't even have elementary search * use formatting… Pillar, Markdown, RST, AsciiDoc, whatever… for the web frontend it doesn't matter, there are nice outputs for all of them * even for the in-image help having some formatting markers might be better than nothing ### Complex-ish * improving in-image help… Offray is/was working on Jupyter ( https://try.jupyter.org/) style notebooks. That sounds like a good replacement. * have at least some basic formatting… some time ago there was in-image Pillar editor using GT, so it's doable. ## 2. Comments for the git help (I've just skimmed through it briefly) My impression is that it doesn't really describe git in Pharo, which is what we are pushing for… it is recommanded to tick the checkbox "Initialize this repository with a > README". This will ease the initialization of the repository (you will be able to > immediately clone your repo). GitHub is lying, you can clone it regardless Open the Monticello browser, accessible from the World menu. Add a > filetree:// repository > This is not really describing using Git in Pharo… with filetree you could use git forever. You now need to commit and push. These two operations have to be externally > to Pharo. Only if you use filetree, because filetree doesn't know about git > > As a user of Git, you need to know the following: > - From Pharo you can _only_ save and load your code frmo the harddisk (see > the chapter Alternative for more options) > Partially true. It will always go through disk (obviously), but with remote git repo you don't care about the local repo. > - Identifying difference between versions has to be done externally to > Pharo. Actually, this is not that painful. GitKraken offers a nice user > interface. Not true for GitFileTree To sum it up: you've described how to use filetree:// with Git, which was possible years ago, so I am not entirely sure what's the objective. The push for git+pharo is to use git from within Pharo, which means gitfiletree, which allows you to commit, load, diff, push, pull directly from the image. So my point is: if we want to provide help for people, we should push them in the correct direction… that is towards git IN pharo. If we push them to not actually use git in Pharo, then we will push them away from our objectives. Peter On Sun, May 8, 2016 at 5:01 AM, Alexandre Bergel <[email protected]> wrote: > Hi! > > I have written a help to use Git in Pharo. Execute the following: > > Metacello new > baseline: 'GitHelp'; > repository: 'github://bergel/Git-Help:master'; > load. > > It will load a Help topic, available on the Help Browser. > If you wish to contribute: > https://github.com/bergel/Git-Help > > One some point, I will propose an inclusion in the base image. > > Cheers, > Alexandre > -- > _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: > Alexandre Bergel http://www.bergel.eu > ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. > > > > >
