[Pharo-project] In-Image Fuel Documentation
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose. Even a HelpSystem entry simply pointing to [1] would be really helpful for beginners like me ;) (although a full Help entry would have the nice benefit of executable examples) Thanks, Sean [1] http://rmod.lille.inria.fr/web/pier/software/Fuel/Version1.8.1/Documentation -- View this message in context: http://forum.world.st/In-Image-Fuel-Documentation-tp4665190.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <sean@clipperadams.com>wrote:
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose.
what do you mean by this? FLUserGuidesTest contains the examples used in the website (although there may not be everything and still it could be outdated). Maybe we can move this test into a Fuel-Examples package?
Even a HelpSystem entry simply pointing to [1] would be really helpful for beginners like me ;) (although a full Help entry would have the nice benefit of executable examples)
Hi Sean. One problem I found is that then we have too many places with the same doc. Hence, a simple update means changing a lot of places: - Doc in image - Examples in image / tests - Website - Help system - PBE chapter so...that does not scale. I don't know yet the best way to solve this. Markdown and then output all the different pieces is not an option I think. thoughts?
Thanks, Sean
[1]
http://rmod.lille.inria.fr/web/pier/software/Fuel/Version1.8.1/Documentation
-- View this message in context: http://forum.world.st/In-Image-Fuel-Documentation-tp4665190.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
-- Mariano http://marianopeck.wordpress.com
Mariano Martinez Peck wrote
FLUserGuidesTest contains the examples used in the website
Oops, didn't see that one! I went to the serialization tests and got lost. I guess what I'm suggesting is to have pointers to the prefered docs (in this case FLUserGuidesTest) where a user might look e.g. HelpSystem -- View this message in context: http://forum.world.st/In-Image-Fuel-Documentation-tp4665190p4665210.html Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
On 2013-01-24, at 21:03, Mariano Martinez Peck <marianopeck@gmail.com> wrote:
On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <sean@clipperadams.com>wrote:
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose.
what do you mean by this? FLUserGuidesTest contains the examples used in the website (although there may not be everything and still it could be outdated). Maybe we can move this test into a Fuel-Examples package?
Even a HelpSystem entry simply pointing to [1] would be really helpful for beginners like me ;) (although a full Help entry would have the nice benefit of executable examples)
Hi Sean. One problem I found is that then we have too many places with the same doc. Hence, a simple update means changing a lot of places:
- Doc in image - Examples in image / tests - Website - Help system - PBE chapter
so...that does not scale.
I don't know yet the best way to solve this. Markdown and then output all the different pieces is not an option I think. thoughts?
For me the first place to put information is in the Image, hence I would only create a HelpDoc (using a common Markdown et. al scheme). The secondary thing is to output that to proper website to get a nice global index on google. This is specially useful if you do not have the code installed yet and you are looking for some piece of code doing a certain thing. Note that it happens way to often on this mailing list that people ask for something and reimplement it due to missing answers ;), google should answer you the right thing!
Mariano Martinez Peck wrote:
On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <sean@clipperadams.com>wrote:
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose.
what do you mean by this? FLUserGuidesTest contains the examples used in the website (although there may not be everything and still it could be outdated). Maybe we can move this test into a Fuel-Examples package?
+1 When a someone first installs a package, to find and know about FLUserGuidesTest is a random walk and a guess. Having a package named *-Examples draws the user's attention immediately.
On 1/26/13, Ben Coman <btc@openinworld.com> wrote:
Mariano Martinez Peck wrote:
On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <sean@clipperadams.com>wrote:
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose.
what do you mean by this? FLUserGuidesTest contains the examples used in the website (although there may not be everything and still it could be outdated). Maybe we can move this test into a Fuel-Examples package?
+1 When a someone first installs a package, to find and know about FLUserGuidesTest is a random walk and a guess. Having a package named *-Examples draws the user's attention immediately.
+1 for the Examples package, I did not find the tests either .... --Hannes
On 24 Jan 2013, at 20:16, "Sean P. DeNigris" <sean@clipperadams.com> wrote:
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose. Even a HelpSystem entry simply pointing to [1] would be really helpful for beginners like me ;) (although a full Help entry would have the nice benefit of executable examples)
Thanks, Sean
[1] http://rmod.lille.inria.fr/web/pier/software/Fuel/Version1.8.1/Documentation
This is very nice documentation ! Thanks for the pointer, and thanks Mariano for writing it - this is really great. Sven PS: IMHO the only thing we need is a way or a convention to document a Monticello package as a whole. That can then be the starting or entry point. Like README.md in github. This should then be in the code and browseable externally. -- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
Thanks. In latest releases we added several guides, and we also refactored the website to keep the guides for the previous versions (http://rmod.lille.inria.fr/web/pier/software/Fuel in the "Versions" section). How can you access the readme in a particular old version, in github? I don't have experience with it so I don't know. I like the idea of avoiding redundant documentation. I don't know if for every Monticello package, but at least can be interesting for each ConfigurationOf* package... Martin On Thu, Jan 24, 2013 at 10:32 PM, Sven Van Caekenberghe <sven@stfx.eu> wrote:
On 24 Jan 2013, at 20:16, "Sean P. DeNigris" <sean@clipperadams.com> wrote:
I eventually found this awesome website [1]. It would be great if there were some basic examples in the image. I found the tests too well factored to be used for this purpose. Even a HelpSystem entry simply pointing to [1] would be really helpful for beginners like me ;) (although a full Help entry would have the nice benefit of executable examples)
Thanks, Sean
[1] http://rmod.lille.inria.fr/web/pier/software/Fuel/Version1.8.1/Documentation
This is very nice documentation !
Thanks for the pointer, and thanks Mariano for writing it - this is really great.
Sven
PS: IMHO the only thing we need is a way or a convention to document a Monticello package as a whole. That can then be the starting or entry point. Like README.md in github. This should then be in the code and browseable externally.
-- Sven Van Caekenberghe http://stfx.eu Smalltalk is the Red Pill
participants (7)
-
Ben Coman -
Camillo Bruni -
H. Hirzel -
Mariano Martinez Peck -
Martin Dias -
Sean P. DeNigris -
Sven Van Caekenberghe