HelpSystem (was Documentation Team)

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

HelpSystem (was Documentation Team)

Torsten Bergmann
To clearify a few things from my side on the discussion
on squeak-dev:

  1. HelpSystem is working, if ASCII is OK for now we can use
     it Pharo/Squeak - otherwise I would see it as an early preview.
     I have clear goals how it should look like in the
     next iterations. For this more patience is necessary.

  2. HelpSystem is independent from where and how the actual
     information is stored (I think I demonstrated this with
     the IRC example, the books and the API help).

  3. I hope to keep HelpSystem in sync for major Squeak distributions
     (Squeak, Pharo, Cuis, ...)

     The last additions from Hannes already broke the code
     in Pharo. Seems to be a Pharo issue this time
     http://code.google.com/p/pharo/issues/detail?id=2342
     
     But please dont commit when it is only working in
     Squeak since my development environment is Pharo.
       
  4. Yes, the content is currently ASCII but the design is prepared
     to add other types in future releases.

     A HelpTopic defines an ivar "contents" - currently referring
     to a string. I may add another ivar "contentType"
     in the future to handle/distinguish additionaly types
     (HTML, SqueaksRichText, Morphs/BookMorph, ...)

  5. HelpSystem should not be limited to Squeak. It should also
     serve the case that when you write and deploy a commercial
     app in Squeak you may use it to provide help to your
     end user/customer

  6. There are two types of help I see:

       A. SystemHelp:      Help books/Tutorials/Manuals
       B. SystemReference: API Help, class comments
 
     HelpSystem is supporting both.
     I already wrote about the differences and details in
     http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
 
  7. I would really like to see support for HTML viewing
     in the image (HTMLViewMorph or so) - maybe based on Scamper
     to get a better viewer (headings, tables, ...) than the
     current plain text.
     If people want to contribute they should start right with this
     task.

     I know that Laurent already made Scamper loadable in Pharo,
     dont know about the state in Squeak.
   
     There is also another HTML browser with markup and CSS now available
     open source as MIT (WithStyle), I already mentioned this.

     http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
 
  8. I know that we now have discussions on which syntax (Wiki,...)
     to use for describing the contents.
     My answer is: it is important but I dont care (yet) since
     this discussion is useless until we have an HTML viewer (see 7.)
     and  even when there are different syntax styles you can provides
     builders to transform them into HTML or other contentTypes
     afterwards.

     See the class HelpBuilder and subclasses.

  9. If you want to write a book for SystemHelp (see 6.A) then
     the help system provides a class "CustomHelp" similar
     to TestCase in SUnit. This class is used to directly
     map book structures to the class hierarchy.

     The intention was to be able to create, store and manage
     these books directly with the usual Smalltalk tools.
     You can even restructure your book with the RefactoringBrowser.

 10. If you want to write API help you (see 6.B) can contribute
     right now by commenting all the undocumented classes in the
     standard image.
 
     HelpSystem just queries these informations from the usual
     sources (class comments, ...). I would not change this
     or make it too complicated since this is what people are
     used too.

     I dont see more documented classes by introducing a
     special syntax (wiki or whatever) people have to learn/know about
     - so lets clean up documenting the classes first.

 11. HelpSystem is able to get contents from external sources
     (see the IRC example) - but I would prefer that authoring/viewing
     could be done right from within the image.
     Even when the result is stored external afterwards.
 
     Look at my example books: I can view and change them
     right from the image and make them available to other images
     using Metacello/Squeaksource.
     Accessibility of docu (viewing and authoring) is the key to keep
     the system and docu in sync and up to date.
     
     External authoring mostly results in unmaintained docu (see
     the Squeak Swiki).

 12. I thought again if it is ready to integrate into Pharo and
     Squeak. From all the discussions I would say it is too early.

 13. If one wants the docu on the web the answer is easy: we
     can generate static files or serve them with Seaside.
     But I have no need for that right now, especially since
     this is already available in various forms.

We can do many things (similar to Python, JavaDoc, you name it)    

But - let's do it step by step. As I said:

 - Someone working on a good HTML Viewer that I can integrate
   would really help moving this forward
   (based on Scamper or by porting WithStyle)
 - Updating class comments would also help a lot

Bye
Torsten

     
     

     
     


--
GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

laurent laffont
Hi,

It's cool to have so many interests in documentation. I deeply think it's a key point to success.

As an hobbyist contributor to Pharo documentation :) I wonder whether I should write doc in HelpSystem (which indeed is very cool !) or in the collaborator active book (which is very attractive for me).

So a way to get the best of both world may be to generate an HelpSystem book from the collaborator book. Every day, if there has been changes in the collaborative book, it can be "packaged" automatically as an HelpSystem book / SystemHelp , put on squeaksource, having ConfigurationOfHelpSystem project lastVersion pointing to the last package.

Sounds good ?

Cheers,

Laurent Laffont


On Wed, Apr 21, 2010 at 7:56 PM, Torsten Bergmann <[hidden email]> wrote:
To clearify a few things from my side on the discussion
on squeak-dev:

 1. HelpSystem is working, if ASCII is OK for now we can use
    it Pharo/Squeak - otherwise I would see it as an early preview.
    I have clear goals how it should look like in the
    next iterations. For this more patience is necessary.

 2. HelpSystem is independent from where and how the actual
    information is stored (I think I demonstrated this with
    the IRC example, the books and the API help).

 3. I hope to keep HelpSystem in sync for major Squeak distributions
    (Squeak, Pharo, Cuis, ...)

    The last additions from Hannes already broke the code
    in Pharo. Seems to be a Pharo issue this time
    http://code.google.com/p/pharo/issues/detail?id=2342

    But please dont commit when it is only working in
    Squeak since my development environment is Pharo.

 4. Yes, the content is currently ASCII but the design is prepared
    to add other types in future releases.

    A HelpTopic defines an ivar "contents" - currently referring
    to a string. I may add another ivar "contentType"
    in the future to handle/distinguish additionaly types
    (HTML, SqueaksRichText, Morphs/BookMorph, ...)

 5. HelpSystem should not be limited to Squeak. It should also
    serve the case that when you write and deploy a commercial
    app in Squeak you may use it to provide help to your
    end user/customer

 6. There are two types of help I see:

      A. SystemHelp:      Help books/Tutorials/Manuals
      B. SystemReference: API Help, class comments

    HelpSystem is supporting both.
    I already wrote about the differences and details in
    http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html

 7. I would really like to see support for HTML viewing
    in the image (HTMLViewMorph or so) - maybe based on Scamper
    to get a better viewer (headings, tables, ...) than the
    current plain text.
    If people want to contribute they should start right with this
    task.

    I know that Laurent already made Scamper loadable in Pharo,
    dont know about the state in Squeak.

    There is also another HTML browser with markup and CSS now available
    open source as MIT (WithStyle), I already mentioned this.

    http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145

 8. I know that we now have discussions on which syntax (Wiki,...)
    to use for describing the contents.
    My answer is: it is important but I dont care (yet) since
    this discussion is useless until we have an HTML viewer (see 7.)
    and  even when there are different syntax styles you can provides
    builders to transform them into HTML or other contentTypes
    afterwards.

    See the class HelpBuilder and subclasses.

 9. If you want to write a book for SystemHelp (see 6.A) then
    the help system provides a class "CustomHelp" similar
    to TestCase in SUnit. This class is used to directly
    map book structures to the class hierarchy.

    The intention was to be able to create, store and manage
    these books directly with the usual Smalltalk tools.
    You can even restructure your book with the RefactoringBrowser.

 10. If you want to write API help you (see 6.B) can contribute
    right now by commenting all the undocumented classes in the
    standard image.

    HelpSystem just queries these informations from the usual
    sources (class comments, ...). I would not change this
    or make it too complicated since this is what people are
    used too.

    I dont see more documented classes by introducing a
    special syntax (wiki or whatever) people have to learn/know about
    - so lets clean up documenting the classes first.

 11. HelpSystem is able to get contents from external sources
    (see the IRC example) - but I would prefer that authoring/viewing
    could be done right from within the image.
    Even when the result is stored external afterwards.

    Look at my example books: I can view and change them
    right from the image and make them available to other images
    using Metacello/Squeaksource.
    Accessibility of docu (viewing and authoring) is the key to keep
    the system and docu in sync and up to date.

    External authoring mostly results in unmaintained docu (see
    the Squeak Swiki).

 12. I thought again if it is ready to integrate into Pharo and
    Squeak. From all the discussions I would say it is too early.

 13. If one wants the docu on the web the answer is easy: we
    can generate static files or serve them with Seaside.
    But I have no need for that right now, especially since
    this is already available in various forms.

We can do many things (similar to Python, JavaDoc, you name it)

But - let's do it step by step. As I said:

 - Someone working on a good HTML Viewer that I can integrate
  would really help moving this forward
  (based on Scamper or by porting WithStyle)
 - Updating class comments would also help a lot

Bye
Torsten








--
GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Stéphane Ducasse
In reply to this post by Torsten Bergmann
Torsten may be you should trun your explanation mail into a book section on book.pharo-project.org because it was cool.
> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
I think that HelpSystem will be an important piece of Pharo.
And I was planning to push it into 1.1 dev :) ASCII is ok for us. Let us be incremental.
I like the
        HelpBrowser openOn: SystemReference
:)

I think that this is the way to push people to write cool comment.
Check the one of URI in 1.1 :)

Now how can we turn pragma tagged method comments and Unit tests into
entries in your HelpSystem.

HelpBuilder of course :)
        Now could we agree on a nice pragma for tagging methods
        and another one sunit tests that should be promoted into the SystemReference



I believe that we do not have the resources to write separate
documentation as VW does. So at least I would have love to have HelpSystem minus minus
where we could get book automatically created from the actual contents of the system.
Tagging is way more reachable than writing specific documentation.

Then I would love to see package level comments... this was this idea behind DrDoc and this is why I should kick my $%^&finger to finish RPackage

Stef

On Apr 21, 2010, at 7:56 PM, Torsten Bergmann wrote:

> To clearify a few things from my side on the discussion
> on squeak-dev:
>
>  1. HelpSystem is working, if ASCII is OK for now we can use
>     it Pharo/Squeak - otherwise I would see it as an early preview.
>     I have clear goals how it should look like in the
>     next iterations. For this more patience is necessary.
>
>  2. HelpSystem is independent from where and how the actual
>     information is stored (I think I demonstrated this with
>     the IRC example, the books and the API help).
>
>  3. I hope to keep HelpSystem in sync for major Squeak distributions
>     (Squeak, Pharo, Cuis, ...)
>
>     The last additions from Hannes already broke the code
>     in Pharo. Seems to be a Pharo issue this time
>     http://code.google.com/p/pharo/issues/detail?id=2342
>
>     But please dont commit when it is only working in
>     Squeak since my development environment is Pharo.
>
>  4. Yes, the content is currently ASCII but the design is prepared
>     to add other types in future releases.
>
>     A HelpTopic defines an ivar "contents" - currently referring
>     to a string. I may add another ivar "contentType"
>     in the future to handle/distinguish additionaly types
>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
>
>  5. HelpSystem should not be limited to Squeak. It should also
>     serve the case that when you write and deploy a commercial
>     app in Squeak you may use it to provide help to your
>     end user/customer
>
>  6. There are two types of help I see:
>
>       A. SystemHelp:      Help books/Tutorials/Manuals
>       B. SystemReference: API Help, class comments
>
>     HelpSystem is supporting both.
>     I already wrote about the differences and details in
>     http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
>
>  7. I would really like to see support for HTML viewing
>     in the image (HTMLViewMorph or so) - maybe based on Scamper
>     to get a better viewer (headings, tables, ...) than the
>     current plain text.
>     If people want to contribute they should start right with this
>     task.
>
>     I know that Laurent already made Scamper loadable in Pharo,
>     dont know about the state in Squeak.
>
>     There is also another HTML browser with markup and CSS now available
>     open source as MIT (WithStyle), I already mentioned this.
>
>     http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
>
>  8. I know that we now have discussions on which syntax (Wiki,...)
>     to use for describing the contents.
>     My answer is: it is important but I dont care (yet) since
>     this discussion is useless until we have an HTML viewer (see 7.)
>     and  even when there are different syntax styles you can provides
>     builders to transform them into HTML or other contentTypes
>     afterwards.
>
>     See the class HelpBuilder and subclasses.
>
>  9. If you want to write a book for SystemHelp (see 6.A) then
>     the help system provides a class "CustomHelp" similar
>     to TestCase in SUnit. This class is used to directly
>     map book structures to the class hierarchy.
>
>     The intention was to be able to create, store and manage
>     these books directly with the usual Smalltalk tools.
>     You can even restructure your book with the RefactoringBrowser.
>
> 10. If you want to write API help you (see 6.B) can contribute
>     right now by commenting all the undocumented classes in the
>     standard image.
>
>     HelpSystem just queries these informations from the usual
>     sources (class comments, ...). I would not change this
>     or make it too complicated since this is what people are
>     used too.
>
>     I dont see more documented classes by introducing a
>     special syntax (wiki or whatever) people have to learn/know about
>     - so lets clean up documenting the classes first.
>
> 11. HelpSystem is able to get contents from external sources
>     (see the IRC example) - but I would prefer that authoring/viewing
>     could be done right from within the image.
>     Even when the result is stored external afterwards.
>
>     Look at my example books: I can view and change them
>     right from the image and make them available to other images
>     using Metacello/Squeaksource.
>     Accessibility of docu (viewing and authoring) is the key to keep
>     the system and docu in sync and up to date.
>
>     External authoring mostly results in unmaintained docu (see
>     the Squeak Swiki).
>
> 12. I thought again if it is ready to integrate into Pharo and
>     Squeak. From all the discussions I would say it is too early.
>
> 13. If one wants the docu on the web the answer is easy: we
>     can generate static files or serve them with Seaside.
>     But I have no need for that right now, especially since
>     this is already available in various forms.
>
> We can do many things (similar to Python, JavaDoc, you name it)    
>
> But - let's do it step by step. As I said:
>
> - Someone working on a good HTML Viewer that I can integrate
>   would really help moving this forward
>   (based on Scamper or by porting WithStyle)
> - Updating class comments would also help a lot
>
> Bye
> Torsten
>
>
>
>
>
>
>
>
> --
> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Michael Roberts-2
In reply to this post by laurent laffont
Laurent, i think this is a tension that a number of us feel. should we
put documentation in the colab book, or in the system? For me the two
are distinct.  The book, ultimately, should read as a book. That is
there is a logical flow from start to finish and the content is
consistent, from start to finish, for a given version of the system.
Writing a book appears hard - i have never done it - but i have
attempted to copy-edit material that turned out to be as big as a
reasonably sized book; i found that near impossible.  So whilst the
colab book effort is currently in its infancy, i would expect over
time it to tend towards being published as a consistent whole. I'm
sure anyone involved in SBE/PBE could comment on the real work
required to write such a book.

As for help in the system, as torsten nicely articulated either "Help"
or "Reference", this should really be dynamic. It should change at the
unit of which it is changing. so if a new version of a package is
loaded, perhaps the Reference docs change. using hyperlink references
you should be able to jump around it in an arbitrary order.  I don't
see a book performing this function. really it must flow consistently
from start to finish and the layout of the book is carefully picked by
the editors. the only realy hyperlink function is from the TOC, and to
any particular index or reference. it is quite distinct from arbitrary
jumping at a system doc level.

at the moment these two forces I consider are at tension, because
there is not enough reference material in the system as we shipped
1.0, and i think the barrier to viewing & editing such reference
documentation, as a coherent whole, to my satisfaction is harder than
using Pier. therefore i find it easier to edit pier even if i have
only contributed a few paragraphs. however longer term this will not
be the case.  We must strive for something akin to Python
documentation. as an engineering artifact, it is simply stunning; you
can find documentation on anything to do with a given released
version. i'm sure this applies to other languages too, i just use
python as an example because I particularly like its style towards doc
annotation and its completeness.

so personally i don't think we should export the pier content into the
help system. i see them as quite different, and for both to succeed I
think they require a different point of view to writing the content.

Torsten - i did not reply to the other thread which stef and I both
commented on, have not had the time. For me i am a total pragmatist
when it comes toward reference documentation and i am only really
interested in reference docs. i fully understand your design and i'm
fine with that. I just hope that as a community we can author the
reference side, since that is what i feel is most missing.

cheers,
Mike

2010/4/21 laurent laffont <[hidden email]>:

> Hi,
> It's cool to have so many interests in documentation. I deeply think it's a
> key point to success.
> As an hobbyist contributor to Pharo documentation :) I wonder whether I
> should write doc in HelpSystem (which indeed is very cool !) or in the
> collaborator active book (which is very attractive for me).
> So a way to get the best of both world may be to generate an HelpSystem book
> from the collaborator book. Every day, if there has been changes in the
> collaborative book, it can be "packaged" automatically as an HelpSystem book
> / SystemHelp , put on squeaksource, having ConfigurationOfHelpSystem project
> lastVersion pointing to the last package.
> Sounds good ?
> Cheers,
> Laurent Laffont
>
>
> On Wed, Apr 21, 2010 at 7:56 PM, Torsten Bergmann <[hidden email]> wrote:
>>
>> To clearify a few things from my side on the discussion
>> on squeak-dev:
>>
>>  1. HelpSystem is working, if ASCII is OK for now we can use
>>     it Pharo/Squeak - otherwise I would see it as an early preview.
>>     I have clear goals how it should look like in the
>>     next iterations. For this more patience is necessary.
>>
>>  2. HelpSystem is independent from where and how the actual
>>     information is stored (I think I demonstrated this with
>>     the IRC example, the books and the API help).
>>
>>  3. I hope to keep HelpSystem in sync for major Squeak distributions
>>     (Squeak, Pharo, Cuis, ...)
>>
>>     The last additions from Hannes already broke the code
>>     in Pharo. Seems to be a Pharo issue this time
>>     http://code.google.com/p/pharo/issues/detail?id=2342
>>
>>     But please dont commit when it is only working in
>>     Squeak since my development environment is Pharo.
>>
>>  4. Yes, the content is currently ASCII but the design is prepared
>>     to add other types in future releases.
>>
>>     A HelpTopic defines an ivar "contents" - currently referring
>>     to a string. I may add another ivar "contentType"
>>     in the future to handle/distinguish additionaly types
>>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
>>
>>  5. HelpSystem should not be limited to Squeak. It should also
>>     serve the case that when you write and deploy a commercial
>>     app in Squeak you may use it to provide help to your
>>     end user/customer
>>
>>  6. There are two types of help I see:
>>
>>       A. SystemHelp:      Help books/Tutorials/Manuals
>>       B. SystemReference: API Help, class comments
>>
>>     HelpSystem is supporting both.
>>     I already wrote about the differences and details in
>>
>> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
>>
>>  7. I would really like to see support for HTML viewing
>>     in the image (HTMLViewMorph or so) - maybe based on Scamper
>>     to get a better viewer (headings, tables, ...) than the
>>     current plain text.
>>     If people want to contribute they should start right with this
>>     task.
>>
>>     I know that Laurent already made Scamper loadable in Pharo,
>>     dont know about the state in Squeak.
>>
>>     There is also another HTML browser with markup and CSS now available
>>     open source as MIT (WithStyle), I already mentioned this.
>>
>>
>> http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
>>
>>  8. I know that we now have discussions on which syntax (Wiki,...)
>>     to use for describing the contents.
>>     My answer is: it is important but I dont care (yet) since
>>     this discussion is useless until we have an HTML viewer (see 7.)
>>     and  even when there are different syntax styles you can provides
>>     builders to transform them into HTML or other contentTypes
>>     afterwards.
>>
>>     See the class HelpBuilder and subclasses.
>>
>>  9. If you want to write a book for SystemHelp (see 6.A) then
>>     the help system provides a class "CustomHelp" similar
>>     to TestCase in SUnit. This class is used to directly
>>     map book structures to the class hierarchy.
>>
>>     The intention was to be able to create, store and manage
>>     these books directly with the usual Smalltalk tools.
>>     You can even restructure your book with the RefactoringBrowser.
>>
>>  10. If you want to write API help you (see 6.B) can contribute
>>     right now by commenting all the undocumented classes in the
>>     standard image.
>>
>>     HelpSystem just queries these informations from the usual
>>     sources (class comments, ...). I would not change this
>>     or make it too complicated since this is what people are
>>     used too.
>>
>>     I dont see more documented classes by introducing a
>>     special syntax (wiki or whatever) people have to learn/know about
>>     - so lets clean up documenting the classes first.
>>
>>  11. HelpSystem is able to get contents from external sources
>>     (see the IRC example) - but I would prefer that authoring/viewing
>>     could be done right from within the image.
>>     Even when the result is stored external afterwards.
>>
>>     Look at my example books: I can view and change them
>>     right from the image and make them available to other images
>>     using Metacello/Squeaksource.
>>     Accessibility of docu (viewing and authoring) is the key to keep
>>     the system and docu in sync and up to date.
>>
>>     External authoring mostly results in unmaintained docu (see
>>     the Squeak Swiki).
>>
>>  12. I thought again if it is ready to integrate into Pharo and
>>     Squeak. From all the discussions I would say it is too early.
>>
>>  13. If one wants the docu on the web the answer is easy: we
>>     can generate static files or serve them with Seaside.
>>     But I have no need for that right now, especially since
>>     this is already available in various forms.
>>
>> We can do many things (similar to Python, JavaDoc, you name it)
>>
>> But - let's do it step by step. As I said:
>>
>>  - Someone working on a good HTML Viewer that I can integrate
>>   would really help moving this forward
>>   (based on Scamper or by porting WithStyle)
>>  - Updating class comments would also help a lot
>>
>> Bye
>> Torsten
>>
>>
>>
>>
>>
>>
>>
>>
>> --
>> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
>> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
>>
>> _______________________________________________
>> Pharo-project mailing list
>> [hidden email]
>> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

laurent laffont
Yes, Python documentation is really impressive, the best I know. 

May be we can go the other way, from HelpSystem to web. I've tried something like some months ago.ex: http://magaloma.seasidehosting.st/Collections-Streams

So we can have a documentation page like http://docs.python.org/py3k/ with:
- collaborator book 
- web edition of Pharo By Example
- HelpSystem books
- API reference generated from comments in classes / methods (with the possibility to add comments like  jQuery or PHP online docs.)
All on one page, starting point to look for documentation, at http://docs.pharo-project.org

Cheers,

Laurent Laffont


On Wed, Apr 21, 2010 at 10:46 PM, Michael Roberts <[hidden email]> wrote:
Laurent, i think this is a tension that a number of us feel. should we
put documentation in the colab book, or in the system? For me the two
are distinct.  The book, ultimately, should read as a book. That is
there is a logical flow from start to finish and the content is
consistent, from start to finish, for a given version of the system.
Writing a book appears hard - i have never done it - but i have
attempted to copy-edit material that turned out to be as big as a
reasonably sized book; i found that near impossible.  So whilst the
colab book effort is currently in its infancy, i would expect over
time it to tend towards being published as a consistent whole. I'm
sure anyone involved in SBE/PBE could comment on the real work
required to write such a book.

As for help in the system, as torsten nicely articulated either "Help"
or "Reference", this should really be dynamic. It should change at the
unit of which it is changing. so if a new version of a package is
loaded, perhaps the Reference docs change. using hyperlink references
you should be able to jump around it in an arbitrary order.  I don't
see a book performing this function. really it must flow consistently
from start to finish and the layout of the book is carefully picked by
the editors. the only realy hyperlink function is from the TOC, and to
any particular index or reference. it is quite distinct from arbitrary
jumping at a system doc level.

at the moment these two forces I consider are at tension, because
there is not enough reference material in the system as we shipped
1.0, and i think the barrier to viewing & editing such reference
documentation, as a coherent whole, to my satisfaction is harder than
using Pier. therefore i find it easier to edit pier even if i have
only contributed a few paragraphs. however longer term this will not
be the case.  We must strive for something akin to Python
documentation. as an engineering artifact, it is simply stunning; you
can find documentation on anything to do with a given released
version. i'm sure this applies to other languages too, i just use
python as an example because I particularly like its style towards doc
annotation and its completeness.

so personally i don't think we should export the pier content into the
help system. i see them as quite different, and for both to succeed I
think they require a different point of view to writing the content.

Torsten - i did not reply to the other thread which stef and I both
commented on, have not had the time. For me i am a total pragmatist
when it comes toward reference documentation and i am only really
interested in reference docs. i fully understand your design and i'm
fine with that. I just hope that as a community we can author the
reference side, since that is what i feel is most missing.

cheers,
Mike

2010/4/21 laurent laffont <[hidden email]>:
> Hi,
> It's cool to have so many interests in documentation. I deeply think it's a
> key point to success.
> As an hobbyist contributor to Pharo documentation :) I wonder whether I
> should write doc in HelpSystem (which indeed is very cool !) or in the
> collaborator active book (which is very attractive for me).
> So a way to get the best of both world may be to generate an HelpSystem book
> from the collaborator book. Every day, if there has been changes in the
> collaborative book, it can be "packaged" automatically as an HelpSystem book
> / SystemHelp , put on squeaksource, having ConfigurationOfHelpSystem project
> lastVersion pointing to the last package.
> Sounds good ?
> Cheers,
> Laurent Laffont
>
>
> On Wed, Apr 21, 2010 at 7:56 PM, Torsten Bergmann <[hidden email]> wrote:
>>
>> To clearify a few things from my side on the discussion
>> on squeak-dev:
>>
>>  1. HelpSystem is working, if ASCII is OK for now we can use
>>     it Pharo/Squeak - otherwise I would see it as an early preview.
>>     I have clear goals how it should look like in the
>>     next iterations. For this more patience is necessary.
>>
>>  2. HelpSystem is independent from where and how the actual
>>     information is stored (I think I demonstrated this with
>>     the IRC example, the books and the API help).
>>
>>  3. I hope to keep HelpSystem in sync for major Squeak distributions
>>     (Squeak, Pharo, Cuis, ...)
>>
>>     The last additions from Hannes already broke the code
>>     in Pharo. Seems to be a Pharo issue this time
>>     http://code.google.com/p/pharo/issues/detail?id=2342
>>
>>     But please dont commit when it is only working in
>>     Squeak since my development environment is Pharo.
>>
>>  4. Yes, the content is currently ASCII but the design is prepared
>>     to add other types in future releases.
>>
>>     A HelpTopic defines an ivar "contents" - currently referring
>>     to a string. I may add another ivar "contentType"
>>     in the future to handle/distinguish additionaly types
>>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
>>
>>  5. HelpSystem should not be limited to Squeak. It should also
>>     serve the case that when you write and deploy a commercial
>>     app in Squeak you may use it to provide help to your
>>     end user/customer
>>
>>  6. There are two types of help I see:
>>
>>       A. SystemHelp:      Help books/Tutorials/Manuals
>>       B. SystemReference: API Help, class comments
>>
>>     HelpSystem is supporting both.
>>     I already wrote about the differences and details in
>>
>> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
>>
>>  7. I would really like to see support for HTML viewing
>>     in the image (HTMLViewMorph or so) - maybe based on Scamper
>>     to get a better viewer (headings, tables, ...) than the
>>     current plain text.
>>     If people want to contribute they should start right with this
>>     task.
>>
>>     I know that Laurent already made Scamper loadable in Pharo,
>>     dont know about the state in Squeak.
>>
>>     There is also another HTML browser with markup and CSS now available
>>     open source as MIT (WithStyle), I already mentioned this.
>>
>>
>> http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
>>
>>  8. I know that we now have discussions on which syntax (Wiki,...)
>>     to use for describing the contents.
>>     My answer is: it is important but I dont care (yet) since
>>     this discussion is useless until we have an HTML viewer (see 7.)
>>     and  even when there are different syntax styles you can provides
>>     builders to transform them into HTML or other contentTypes
>>     afterwards.
>>
>>     See the class HelpBuilder and subclasses.
>>
>>  9. If you want to write a book for SystemHelp (see 6.A) then
>>     the help system provides a class "CustomHelp" similar
>>     to TestCase in SUnit. This class is used to directly
>>     map book structures to the class hierarchy.
>>
>>     The intention was to be able to create, store and manage
>>     these books directly with the usual Smalltalk tools.
>>     You can even restructure your book with the RefactoringBrowser.
>>
>>  10. If you want to write API help you (see 6.B) can contribute
>>     right now by commenting all the undocumented classes in the
>>     standard image.
>>
>>     HelpSystem just queries these informations from the usual
>>     sources (class comments, ...). I would not change this
>>     or make it too complicated since this is what people are
>>     used too.
>>
>>     I dont see more documented classes by introducing a
>>     special syntax (wiki or whatever) people have to learn/know about
>>     - so lets clean up documenting the classes first.
>>
>>  11. HelpSystem is able to get contents from external sources
>>     (see the IRC example) - but I would prefer that authoring/viewing
>>     could be done right from within the image.
>>     Even when the result is stored external afterwards.
>>
>>     Look at my example books: I can view and change them
>>     right from the image and make them available to other images
>>     using Metacello/Squeaksource.
>>     Accessibility of docu (viewing and authoring) is the key to keep
>>     the system and docu in sync and up to date.
>>
>>     External authoring mostly results in unmaintained docu (see
>>     the Squeak Swiki).
>>
>>  12. I thought again if it is ready to integrate into Pharo and
>>     Squeak. From all the discussions I would say it is too early.
>>
>>  13. If one wants the docu on the web the answer is easy: we
>>     can generate static files or serve them with Seaside.
>>     But I have no need for that right now, especially since
>>     this is already available in various forms.
>>
>> We can do many things (similar to Python, JavaDoc, you name it)
>>
>> But - let's do it step by step. As I said:
>>
>>  - Someone working on a good HTML Viewer that I can integrate
>>   would really help moving this forward
>>   (based on Scamper or by porting WithStyle)
>>  - Updating class comments would also help a lot
>>
>> Bye
>> Torsten
>>
>>
>>
>>
>>
>>
>>
>>
>> --
>> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
>> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
>>
>> _______________________________________________
>> Pharo-project mailing list
>> [hidden email]
>> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Michael Roberts-2
yes I think that is a nice idea. we would need to see how it fitted in
with http://pharo-project.org/documentation as it is currently, and if
we load cms-box with all content or something else for dynamically
generated stuff like your seaside example (or -> static html).

cheers,
Mike

2010/4/21 laurent laffont <[hidden email]>:

> Yes, Python documentation is really impressive, the best I know.
> May be we can go the other way, from HelpSystem to web. I've tried something
> like some months
> ago.ex: http://magaloma.seasidehosting.st/Collections-Streams.
> So we can have a documentation page like http://docs.python.org/py3k/ with:
> - collaborator book
> - web edition of Pharo By Example
> - HelpSystem books
> - API reference generated from comments in classes / methods (with the
> possibility to add comments like  jQuery or PHP online docs.)
> All on one page, starting point to look for documentation, at
> http://docs.pharo-project.org
> Cheers,
> Laurent Laffont
>
>
> On Wed, Apr 21, 2010 at 10:46 PM, Michael Roberts <[hidden email]> wrote:
>>
>> Laurent, i think this is a tension that a number of us feel. should we
>> put documentation in the colab book, or in the system? For me the two
>> are distinct.  The book, ultimately, should read as a book. That is
>> there is a logical flow from start to finish and the content is
>> consistent, from start to finish, for a given version of the system.
>> Writing a book appears hard - i have never done it - but i have
>> attempted to copy-edit material that turned out to be as big as a
>> reasonably sized book; i found that near impossible.  So whilst the
>> colab book effort is currently in its infancy, i would expect over
>> time it to tend towards being published as a consistent whole. I'm
>> sure anyone involved in SBE/PBE could comment on the real work
>> required to write such a book.
>>
>> As for help in the system, as torsten nicely articulated either "Help"
>> or "Reference", this should really be dynamic. It should change at the
>> unit of which it is changing. so if a new version of a package is
>> loaded, perhaps the Reference docs change. using hyperlink references
>> you should be able to jump around it in an arbitrary order.  I don't
>> see a book performing this function. really it must flow consistently
>> from start to finish and the layout of the book is carefully picked by
>> the editors. the only realy hyperlink function is from the TOC, and to
>> any particular index or reference. it is quite distinct from arbitrary
>> jumping at a system doc level.
>>
>> at the moment these two forces I consider are at tension, because
>> there is not enough reference material in the system as we shipped
>> 1.0, and i think the barrier to viewing & editing such reference
>> documentation, as a coherent whole, to my satisfaction is harder than
>> using Pier. therefore i find it easier to edit pier even if i have
>> only contributed a few paragraphs. however longer term this will not
>> be the case.  We must strive for something akin to Python
>> documentation. as an engineering artifact, it is simply stunning; you
>> can find documentation on anything to do with a given released
>> version. i'm sure this applies to other languages too, i just use
>> python as an example because I particularly like its style towards doc
>> annotation and its completeness.
>>
>> so personally i don't think we should export the pier content into the
>> help system. i see them as quite different, and for both to succeed I
>> think they require a different point of view to writing the content.
>>
>> Torsten - i did not reply to the other thread which stef and I both
>> commented on, have not had the time. For me i am a total pragmatist
>> when it comes toward reference documentation and i am only really
>> interested in reference docs. i fully understand your design and i'm
>> fine with that. I just hope that as a community we can author the
>> reference side, since that is what i feel is most missing.
>>
>> cheers,
>> Mike
>>
>> 2010/4/21 laurent laffont <[hidden email]>:
>> > Hi,
>> > It's cool to have so many interests in documentation. I deeply think
>> > it's a
>> > key point to success.
>> > As an hobbyist contributor to Pharo documentation :) I wonder whether I
>> > should write doc in HelpSystem (which indeed is very cool !) or in the
>> > collaborator active book (which is very attractive for me).
>> > So a way to get the best of both world may be to generate an HelpSystem
>> > book
>> > from the collaborator book. Every day, if there has been changes in the
>> > collaborative book, it can be "packaged" automatically as an HelpSystem
>> > book
>> > / SystemHelp , put on squeaksource, having ConfigurationOfHelpSystem
>> > project
>> > lastVersion pointing to the last package.
>> > Sounds good ?
>> > Cheers,
>> > Laurent Laffont
>> >
>> >
>> > On Wed, Apr 21, 2010 at 7:56 PM, Torsten Bergmann <[hidden email]>
>> > wrote:
>> >>
>> >> To clearify a few things from my side on the discussion
>> >> on squeak-dev:
>> >>
>> >>  1. HelpSystem is working, if ASCII is OK for now we can use
>> >>     it Pharo/Squeak - otherwise I would see it as an early preview.
>> >>     I have clear goals how it should look like in the
>> >>     next iterations. For this more patience is necessary.
>> >>
>> >>  2. HelpSystem is independent from where and how the actual
>> >>     information is stored (I think I demonstrated this with
>> >>     the IRC example, the books and the API help).
>> >>
>> >>  3. I hope to keep HelpSystem in sync for major Squeak distributions
>> >>     (Squeak, Pharo, Cuis, ...)
>> >>
>> >>     The last additions from Hannes already broke the code
>> >>     in Pharo. Seems to be a Pharo issue this time
>> >>     http://code.google.com/p/pharo/issues/detail?id=2342
>> >>
>> >>     But please dont commit when it is only working in
>> >>     Squeak since my development environment is Pharo.
>> >>
>> >>  4. Yes, the content is currently ASCII but the design is prepared
>> >>     to add other types in future releases.
>> >>
>> >>     A HelpTopic defines an ivar "contents" - currently referring
>> >>     to a string. I may add another ivar "contentType"
>> >>     in the future to handle/distinguish additionaly types
>> >>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
>> >>
>> >>  5. HelpSystem should not be limited to Squeak. It should also
>> >>     serve the case that when you write and deploy a commercial
>> >>     app in Squeak you may use it to provide help to your
>> >>     end user/customer
>> >>
>> >>  6. There are two types of help I see:
>> >>
>> >>       A. SystemHelp:      Help books/Tutorials/Manuals
>> >>       B. SystemReference: API Help, class comments
>> >>
>> >>     HelpSystem is supporting both.
>> >>     I already wrote about the differences and details in
>> >>
>> >>
>> >> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
>> >>
>> >>  7. I would really like to see support for HTML viewing
>> >>     in the image (HTMLViewMorph or so) - maybe based on Scamper
>> >>     to get a better viewer (headings, tables, ...) than the
>> >>     current plain text.
>> >>     If people want to contribute they should start right with this
>> >>     task.
>> >>
>> >>     I know that Laurent already made Scamper loadable in Pharo,
>> >>     dont know about the state in Squeak.
>> >>
>> >>     There is also another HTML browser with markup and CSS now
>> >> available
>> >>     open source as MIT (WithStyle), I already mentioned this.
>> >>
>> >>
>> >>
>> >> http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
>> >>
>> >>  8. I know that we now have discussions on which syntax (Wiki,...)
>> >>     to use for describing the contents.
>> >>     My answer is: it is important but I dont care (yet) since
>> >>     this discussion is useless until we have an HTML viewer (see 7.)
>> >>     and  even when there are different syntax styles you can provides
>> >>     builders to transform them into HTML or other contentTypes
>> >>     afterwards.
>> >>
>> >>     See the class HelpBuilder and subclasses.
>> >>
>> >>  9. If you want to write a book for SystemHelp (see 6.A) then
>> >>     the help system provides a class "CustomHelp" similar
>> >>     to TestCase in SUnit. This class is used to directly
>> >>     map book structures to the class hierarchy.
>> >>
>> >>     The intention was to be able to create, store and manage
>> >>     these books directly with the usual Smalltalk tools.
>> >>     You can even restructure your book with the RefactoringBrowser.
>> >>
>> >>  10. If you want to write API help you (see 6.B) can contribute
>> >>     right now by commenting all the undocumented classes in the
>> >>     standard image.
>> >>
>> >>     HelpSystem just queries these informations from the usual
>> >>     sources (class comments, ...). I would not change this
>> >>     or make it too complicated since this is what people are
>> >>     used too.
>> >>
>> >>     I dont see more documented classes by introducing a
>> >>     special syntax (wiki or whatever) people have to learn/know about
>> >>     - so lets clean up documenting the classes first.
>> >>
>> >>  11. HelpSystem is able to get contents from external sources
>> >>     (see the IRC example) - but I would prefer that authoring/viewing
>> >>     could be done right from within the image.
>> >>     Even when the result is stored external afterwards.
>> >>
>> >>     Look at my example books: I can view and change them
>> >>     right from the image and make them available to other images
>> >>     using Metacello/Squeaksource.
>> >>     Accessibility of docu (viewing and authoring) is the key to keep
>> >>     the system and docu in sync and up to date.
>> >>
>> >>     External authoring mostly results in unmaintained docu (see
>> >>     the Squeak Swiki).
>> >>
>> >>  12. I thought again if it is ready to integrate into Pharo and
>> >>     Squeak. From all the discussions I would say it is too early.
>> >>
>> >>  13. If one wants the docu on the web the answer is easy: we
>> >>     can generate static files or serve them with Seaside.
>> >>     But I have no need for that right now, especially since
>> >>     this is already available in various forms.
>> >>
>> >> We can do many things (similar to Python, JavaDoc, you name it)
>> >>
>> >> But - let's do it step by step. As I said:
>> >>
>> >>  - Someone working on a good HTML Viewer that I can integrate
>> >>   would really help moving this forward
>> >>   (based on Scamper or by porting WithStyle)
>> >>  - Updating class comments would also help a lot
>> >>
>> >> Bye
>> >> Torsten
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> --
>> >> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
>> >> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
>> >>
>> >> _______________________________________________
>> >> Pharo-project mailing list
>> >> [hidden email]
>> >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>> >
>> >
>> > _______________________________________________
>> > Pharo-project mailing list
>> > [hidden email]
>> > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>> >
>>
>> _______________________________________________
>> Pharo-project mailing list
>> [hidden email]
>> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>

_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
Reply | Threaded
Open this post in threaded view
|

Re: HelpSystem (was Documentation Team)

Stéphane Ducasse
In reply to this post by laurent laffont
What would be good is to have a class comments for each of the class we see in

HelpSystem openOn: SystemReference.

This would be a countable progress.

stef

On Apr 21, 2010, at 11:32 PM, laurent laffont wrote:

> Yes, Python documentation is really impressive, the best I know.
>
> May be we can go the other way, from HelpSystem to web. I've tried something like some months ago.ex: http://magaloma.seasidehosting.st/Collections-Streams.
>
> So we can have a documentation page like http://docs.python.org/py3k/ with:
> - collaborator book
> - web edition of Pharo By Example
> - HelpSystem books
> - API reference generated from comments in classes / methods (with the possibility to add comments like  jQuery or PHP online docs.)
> All on one page, starting point to look for documentation, at http://docs.pharo-project.org
>
> Cheers,
>
> Laurent Laffont
>
>
> On Wed, Apr 21, 2010 at 10:46 PM, Michael Roberts <[hidden email]> wrote:
> Laurent, i think this is a tension that a number of us feel. should we
> put documentation in the colab book, or in the system? For me the two
> are distinct.  The book, ultimately, should read as a book. That is
> there is a logical flow from start to finish and the content is
> consistent, from start to finish, for a given version of the system.
> Writing a book appears hard - i have never done it - but i have
> attempted to copy-edit material that turned out to be as big as a
> reasonably sized book; i found that near impossible.  So whilst the
> colab book effort is currently in its infancy, i would expect over
> time it to tend towards being published as a consistent whole. I'm
> sure anyone involved in SBE/PBE could comment on the real work
> required to write such a book.
>
> As for help in the system, as torsten nicely articulated either "Help"
> or "Reference", this should really be dynamic. It should change at the
> unit of which it is changing. so if a new version of a package is
> loaded, perhaps the Reference docs change. using hyperlink references
> you should be able to jump around it in an arbitrary order.  I don't
> see a book performing this function. really it must flow consistently
> from start to finish and the layout of the book is carefully picked by
> the editors. the only realy hyperlink function is from the TOC, and to
> any particular index or reference. it is quite distinct from arbitrary
> jumping at a system doc level.
>
> at the moment these two forces I consider are at tension, because
> there is not enough reference material in the system as we shipped
> 1.0, and i think the barrier to viewing & editing such reference
> documentation, as a coherent whole, to my satisfaction is harder than
> using Pier. therefore i find it easier to edit pier even if i have
> only contributed a few paragraphs. however longer term this will not
> be the case.  We must strive for something akin to Python
> documentation. as an engineering artifact, it is simply stunning; you
> can find documentation on anything to do with a given released
> version. i'm sure this applies to other languages too, i just use
> python as an example because I particularly like its style towards doc
> annotation and its completeness.
>
> so personally i don't think we should export the pier content into the
> help system. i see them as quite different, and for both to succeed I
> think they require a different point of view to writing the content.
>
> Torsten - i did not reply to the other thread which stef and I both
> commented on, have not had the time. For me i am a total pragmatist
> when it comes toward reference documentation and i am only really
> interested in reference docs. i fully understand your design and i'm
> fine with that. I just hope that as a community we can author the
> reference side, since that is what i feel is most missing.
>
> cheers,
> Mike
>
> 2010/4/21 laurent laffont <[hidden email]>:
> > Hi,
> > It's cool to have so many interests in documentation. I deeply think it's a
> > key point to success.
> > As an hobbyist contributor to Pharo documentation :) I wonder whether I
> > should write doc in HelpSystem (which indeed is very cool !) or in the
> > collaborator active book (which is very attractive for me).
> > So a way to get the best of both world may be to generate an HelpSystem book
> > from the collaborator book. Every day, if there has been changes in the
> > collaborative book, it can be "packaged" automatically as an HelpSystem book
> > / SystemHelp , put on squeaksource, having ConfigurationOfHelpSystem project
> > lastVersion pointing to the last package.
> > Sounds good ?
> > Cheers,
> > Laurent Laffont
> >
> >
> > On Wed, Apr 21, 2010 at 7:56 PM, Torsten Bergmann <[hidden email]> wrote:
> >>
> >> To clearify a few things from my side on the discussion
> >> on squeak-dev:
> >>
> >>  1. HelpSystem is working, if ASCII is OK for now we can use
> >>     it Pharo/Squeak - otherwise I would see it as an early preview.
> >>     I have clear goals how it should look like in the
> >>     next iterations. For this more patience is necessary.
> >>
> >>  2. HelpSystem is independent from where and how the actual
> >>     information is stored (I think I demonstrated this with
> >>     the IRC example, the books and the API help).
> >>
> >>  3. I hope to keep HelpSystem in sync for major Squeak distributions
> >>     (Squeak, Pharo, Cuis, ...)
> >>
> >>     The last additions from Hannes already broke the code
> >>     in Pharo. Seems to be a Pharo issue this time
> >>     http://code.google.com/p/pharo/issues/detail?id=2342
> >>
> >>     But please dont commit when it is only working in
> >>     Squeak since my development environment is Pharo.
> >>
> >>  4. Yes, the content is currently ASCII but the design is prepared
> >>     to add other types in future releases.
> >>
> >>     A HelpTopic defines an ivar "contents" - currently referring
> >>     to a string. I may add another ivar "contentType"
> >>     in the future to handle/distinguish additionaly types
> >>     (HTML, SqueaksRichText, Morphs/BookMorph, ...)
> >>
> >>  5. HelpSystem should not be limited to Squeak. It should also
> >>     serve the case that when you write and deploy a commercial
> >>     app in Squeak you may use it to provide help to your
> >>     end user/customer
> >>
> >>  6. There are two types of help I see:
> >>
> >>       A. SystemHelp:      Help books/Tutorials/Manuals
> >>       B. SystemReference: API Help, class comments
> >>
> >>     HelpSystem is supporting both.
> >>     I already wrote about the differences and details in
> >>
> >> http://lists.gforge.inria.fr/pipermail/pharo-project/2010-April/024857.html
> >>
> >>  7. I would really like to see support for HTML viewing
> >>     in the image (HTMLViewMorph or so) - maybe based on Scamper
> >>     to get a better viewer (headings, tables, ...) than the
> >>     current plain text.
> >>     If people want to contribute they should start right with this
> >>     task.
> >>
> >>     I know that Laurent already made Scamper loadable in Pharo,
> >>     dont know about the state in Squeak.
> >>
> >>     There is also another HTML browser with markup and CSS now available
> >>     open source as MIT (WithStyle), I already mentioned this.
> >>
> >>
> >> http://www.cincomsmalltalk.com/userblogs/rowanb/blogView?showComments=true&printTitle=Im_back..._but_SWS_isnt&entry=3364012145
> >>
> >>  8. I know that we now have discussions on which syntax (Wiki,...)
> >>     to use for describing the contents.
> >>     My answer is: it is important but I dont care (yet) since
> >>     this discussion is useless until we have an HTML viewer (see 7.)
> >>     and  even when there are different syntax styles you can provides
> >>     builders to transform them into HTML or other contentTypes
> >>     afterwards.
> >>
> >>     See the class HelpBuilder and subclasses.
> >>
> >>  9. If you want to write a book for SystemHelp (see 6.A) then
> >>     the help system provides a class "CustomHelp" similar
> >>     to TestCase in SUnit. This class is used to directly
> >>     map book structures to the class hierarchy.
> >>
> >>     The intention was to be able to create, store and manage
> >>     these books directly with the usual Smalltalk tools.
> >>     You can even restructure your book with the RefactoringBrowser.
> >>
> >>  10. If you want to write API help you (see 6.B) can contribute
> >>     right now by commenting all the undocumented classes in the
> >>     standard image.
> >>
> >>     HelpSystem just queries these informations from the usual
> >>     sources (class comments, ...). I would not change this
> >>     or make it too complicated since this is what people are
> >>     used too.
> >>
> >>     I dont see more documented classes by introducing a
> >>     special syntax (wiki or whatever) people have to learn/know about
> >>     - so lets clean up documenting the classes first.
> >>
> >>  11. HelpSystem is able to get contents from external sources
> >>     (see the IRC example) - but I would prefer that authoring/viewing
> >>     could be done right from within the image.
> >>     Even when the result is stored external afterwards.
> >>
> >>     Look at my example books: I can view and change them
> >>     right from the image and make them available to other images
> >>     using Metacello/Squeaksource.
> >>     Accessibility of docu (viewing and authoring) is the key to keep
> >>     the system and docu in sync and up to date.
> >>
> >>     External authoring mostly results in unmaintained docu (see
> >>     the Squeak Swiki).
> >>
> >>  12. I thought again if it is ready to integrate into Pharo and
> >>     Squeak. From all the discussions I would say it is too early.
> >>
> >>  13. If one wants the docu on the web the answer is easy: we
> >>     can generate static files or serve them with Seaside.
> >>     But I have no need for that right now, especially since
> >>     this is already available in various forms.
> >>
> >> We can do many things (similar to Python, JavaDoc, you name it)
> >>
> >> But - let's do it step by step. As I said:
> >>
> >>  - Someone working on a good HTML Viewer that I can integrate
> >>   would really help moving this forward
> >>   (based on Scamper or by porting WithStyle)
> >>  - Updating class comments would also help a lot
> >>
> >> Bye
> >> Torsten
> >>
> >>
> >>
> >>
> >>
> >>
> >>
> >>
> >> --
> >> GRATIS für alle GMX-Mitglieder: Die maxdome Movie-FLAT!
> >> Jetzt freischalten unter http://portal.gmx.net/de/go/maxdome01
> >>
> >> _______________________________________________
> >> Pharo-project mailing list
> >> [hidden email]
> >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
> >
> >
> > _______________________________________________
> > Pharo-project mailing list
> > [hidden email]
> > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
> >
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
>
> _______________________________________________
> Pharo-project mailing list
> [hidden email]
> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project


_______________________________________________
Pharo-project mailing list
[hidden email]
http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project