On Sun, May 08, 2016 at 05:08:37PM +0200, Peter Uhnák wrote:
## 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.
+1 How about WebDoc (or similar) serving up the API with class comments to make it searchable on the web, and a wiki that lowers the cost of contributing? The wiki would also act as a place where the documentation can evolve until it is considered stable enough to include in the image. It can also have links to other blogs, etc. that may not be appropriate for in-image documentation Speaking of wikis, what is the status of the collaborActive book? It usually appears near the top of my google searches, but appears to be quite out of date. I'd be happy to update it a bit while still in the learning phase of Pharo if someone can provide credentials. Cheers, Alistair