In-Image Fuel Documentation

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

In-Image Fuel Documentation

Sean P. DeNigris
Administrator
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
Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

Mariano Martinez Peck


On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <[hidden email]> 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
Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

Sean P. DeNigris
Administrator
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
Cheers,
Sean
Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

Camillo Bruni-3
In reply to this post by Mariano Martinez Peck

On 2013-01-24, at 21:03, Mariano Martinez Peck <[hidden email]> wrote:

> On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <[hidden email]>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!
Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

Sven Van Caekenberghe-2
In reply to this post by Sean P. DeNigris

On 24 Jan 2013, at 20:16, "Sean P. DeNigris" <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

tinchodias
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 <[hidden email]> wrote:

>
> On 24 Jan 2013, at 20:16, "Sean P. DeNigris" <[hidden email]> 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
>
>

Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

Ben Coman
In reply to this post by Mariano Martinez Peck
Mariano Martinez Peck wrote:

> On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris <[hidden email]>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.


Reply | Threaded
Open this post in threaded view
|

Re: In-Image Fuel Documentation

Hannes Hirzel
On 1/26/13, Ben Coman <[hidden email]> wrote:

> Mariano Martinez Peck wrote:
>> On Thu, Jan 24, 2013 at 4:16 PM, Sean P. DeNigris
>> <[hidden email]>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