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 <[email protected]> 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 <[email protected]>: > > 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 <[email protected]> > 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 > >> [email protected] > >> http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > > > _______________________________________________ > > Pharo-project mailing list > > [email protected] > > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project > > > > _______________________________________________ > Pharo-project mailing list > [email protected] > http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project >
_______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
