Hi,
I'm still getting my head around the magnitude of what I have just volunteered to be a part of. I've griped and groaned before about the seeming lack of information about Squeak / Smalltalk but after perusing the wiki I am astounded by how much is there. Though at this point it's usefulness to me is not determined.
Having said that, the following is a regurgitation of what has so far passed through my noob synapses about the topic of Documentation and I offer them as points of discussion...
We are working on two concurrent, yet associated, projects... * Squeak Documentation Project * Squeak Tutorial Project (listed as the first project of the Documentation Team)
These questions came to mind.
1) Is the current wiki system suitable to handle the end result, and if not, is there something available in Squeak for it? There was a little discussion today in IRC about it. And there is a desire to see magicbook created. But we only have a wiki right now and my thoughts currently are around my understanding that a Wiki is a fairly statically structured system. I sense that what we are looking to produce is going to be significantly dynamic. A static system is going to require a huge amount of effort in maintenance - something we don't seem to access to(yet?!). Also, to get the ideas flowing, what do you think about using concept maps to lay out access to information? Check this link out.... http://www.eiffel.com/developers/learning_maps/ and how about this... http://cmap.ihmc.us/ Perhaps these are tools that could be developed in Squeak?
2) Documenting everything in Squeak is a big task. BIG! At least it looks that way to me. Do we want to include documentation for non- core projects like Seaside and Pier? I ask this because documenting and Tutorialising those two projects is what brought me to the Documentation group to begin with. I can envision a core documentation team assisting with project members documenting their product, but I sense most of them have their own pages they would maintain and the core Documentation team might prompt them annually to add / change material where necessary.
3) Who are the users of the wiki? What do they want from it? How are we going to provide for those needs? Some initial definitions I come up with are... Non-Programer AKA newbies (no programming experience at all) Programmers Switchers (from other languages or other VM's) Intermediate Advanced (do they even visit the wiki?)
4) Presentation of information is almost as important as the content of that information. So thought needs to be given to this area. So look and feel of the wiki adds value to the material presented.
5) We should define the information we want to collect when entering an article/tutorial/link to the wiki. This would act as a guideline for ways to search it later, and to sort by usefuleness. Eg, Published date (eg: older articles might get a lower weighting), Title, Author(s), Topic, Tags, Abstract.
Other Random Thoughts -------------------------------- * Have a ratings & comments system for articles (ratings can only be applied by registered Squeakers) * Tags that can be associated with an article so that filtered searches are available
I believe in the KISS principle, but the above thoughts might provide for a discussion of a roadmap.
Regards Paul
On Thu, Apr 05, 2007 at 12:03:40AM -0700, Paul Bennett wrote:
- Is the current wiki system suitable to handle the end result, and
if not, is there something available in Squeak for it? There was a little discussion today in IRC about it. And there is a desire to see magicbook created. But we only have a wiki right now and my thoughts currently are around my understanding that a Wiki is a fairly statically structured system. I sense that what we are looking to produce is going to be significantly dynamic. A static system is going to require a huge amount of effort in maintenance - something we don't seem to access to(yet?!). Also, to get the ideas flowing, what do you think about using concept maps to lay out access to information? Check this link out.... http://www.eiffel.com/developers/learning_maps/ and how about this... http://cmap.ihmc.us/ Perhaps these are tools that could be developed in Squeak?
Pier is way more than a wiki. Check it out: http://wiki.squeak.org/squeak/3700
I will look into those.
- Documenting everything in Squeak is a big task. BIG! At least it
looks that way to me. Do we want to include documentation for non- core projects like Seaside and Pier? I ask this because documenting and Tutorialising those two projects is what brought me to the Documentation group to begin with. I can envision a core documentation team assisting with project members documenting their product, but I sense most of them have their own pages they would maintain and the core Documentation team might prompt them annually to add / change material where necessary.
I immagine that once there is enough maintainable documentation, peer pressure will arise, causing developers to expect documentation just as they now expect SUnit tests.
I believe in the KISS principle, but the above thoughts might provide for a discussion of a roadmap.
I just created a roadmap proposal. It is a separate email, cross-posted to squeak-dev and squeak-doc
From discussions I have had on IRC with Derek O'Connell, Max
OrHai, and Paul Bennett, I have decided it is time to propose an official road map for the Squeak Documentation Team for 2007:
We are currently in the formative stages, and a clear goal is starting to emerge, along with a path to get there. We would like to see a Squeak where: - Tutorials exist in the main image - All core functionality is documented and up-to-date - The documentation can be viewed and edited both within the image and from a central website - The documentation can be easily maintained indefinitely
How can we get there? There are several steps we must take, and they can be done mostly in parallel: - Collect all existing documentation together in one place. -- This is nearly complete. We have assembled a list of nearly all Squeak documentation that exists outside of the image: -- Squeak Tutorials (Links)[1] -- Category Index[2] - Categorize and index all of this documentation. -- We are undertaking this task in the small at Squeak Tutorials[3], where we are concerned only with categorizing and indexing Squeak Tutorials. From there, we will probably use this hierarchy as a basis for our new index. We stand to gain two things from completing this project: --- A strong core Documentation team, willing and capable of facing the larger challenges ahead --- A first-pass at a usable introductory guide to Squeak -- The next step will be to fix the problems listed at Refactoring the Swiki[4], and complete the Documentation Table of Contents[5]. - Implement Magic Book[6], which will allow the Documentation to be kept up-to-date indefinitely. This will draw from the work done by the implementors of Sophie, Pier, SUnit, and perhaps Gjallar - Get permission and republish the documentation in a form suitable for distribution and collaboration -- Paul Bennett has volunteered for this task. - Integrate SUnit tests into the documentation. Thanks to the 3.10 release team, there should be plenty of unit tests by the time we get to this stage.
A hyperlinked version of this proposal is on the Doc team home page: http://wiki.squeak.org/squeak/808
With a clear plan and a clear goal, we can eliminate the criticism that Squeak needs better documentation. There are tasks to be done. If this road map seems good to the community, we can start systematically dividing up the tasks and assigning responsibilities. I will divide up the tasks into week-long chunks, so that one can contribute by sacrificing 2 to 10 hours per week.
I especially need help from the developers of Sophie, Pier, SUnit, Monticello, and Spoon to evaluate how difficult it will be to: - Create a system for browsing Documentation along side the code - Embed unit tests within documentation so that it can be auto-tested for correctness - Edit from both the image and the web - Distribute this documentation with the image - Distribute such documentation as part of a packages - Edit the documentation locally and commit it to a central (official) image/universe and make it available via the update mechanism (somewhat like a distributed wiki)
I know it is late, but tasks 1-4 would make a great Google Summer of Code project.
Thank you for reading this proposal, and thanks to all who reminded me how important good documentation really is. You know who you are :)
[1] Squeak Tutorials (Links): http://wiki.squeak.org/squeak/792#Links
[2] Category Index: http://wiki.squeak.org/squeak/5871
[3] Squeak Tutorials: http://wiki.squeak.org/squeak/792
[4] Refactoring the Swiki: http://wiki.squeak.org/squeak/2352
[5] Documentation Table of Contents: http://wiki.squeak.org/squeak/2983
[6] Magic Book: http://wiki.squeak.org/squeak/3004
Hi,
I don't have any problem with this plan. There is a lot of work. Thank you for managing a team.
However, I would not vote for including the tutorials into the base image. Please put everything in a loadable package. If you have an introduction to Squeak with links to tutorials and documentations, I would really like to put that in the squeak-dev and squeak-web images.
Bye
On Thu, Apr 05, 2007 at 01:22:04AM -0700, Matthew Fulmer wrote:
From discussions I have had on IRC with Derek O'Connell, Max
OrHai, and Paul Bennett, I have decided it is time to propose an official road map for the Squeak Documentation Team for 2007:
We are currently in the formative stages, and a clear goal is starting to emerge, along with a path to get there. We would like to see a Squeak where:
- Tutorials exist in the main image
- All core functionality is documented and up-to-date
- The documentation can be viewed and edited both within the image and from a central website
- The documentation can be easily maintained indefinitely
How can we get there? There are several steps we must take, and they can be done mostly in parallel:
- Collect all existing documentation together in one place.
-- This is nearly complete. We have assembled a list of nearly all Squeak documentation that exists outside of the image: -- Squeak Tutorials (Links)[1] -- Category Index[2]
- Categorize and index all of this documentation.
-- We are undertaking this task in the small at Squeak Tutorials[3], where we are concerned only with categorizing and indexing Squeak Tutorials. From there, we will probably use this hierarchy as a basis for our new index. We stand to gain two things from completing this project: --- A strong core Documentation team, willing and capable of facing the larger challenges ahead --- A first-pass at a usable introductory guide to Squeak -- The next step will be to fix the problems listed at Refactoring the Swiki[4], and complete the Documentation Table of Contents[5].
- Implement Magic Book[6], which will allow the Documentation to be kept up-to-date indefinitely. This will draw from the work done by the implementors of Sophie, Pier, SUnit, and perhaps Gjallar
Max OrHai reminded me that we already have an excellent medium for storing Squeak documentation, better than Sophie, Pier, or anything else:
COMMENTS!!!
This is much more concrete and practical than whatever I was thinking about creating, so I replaced this point with a point about comments and how they could be integrated into Pier.
- Get permission and republish the documentation in a form suitable for distribution and collaboration
-- Paul Bennett has volunteered for this task.
- Integrate SUnit tests into the documentation. Thanks to the 3.10 release team, there should be plenty of unit tests by the time we get to this stage.
I edited this to be more explicit about Magic Book and how the point is document verification
A hyperlinked version of this proposal is on the Doc team home page: http://wiki.squeak.org/squeak/808
This has been updated. Get the newer, saner version there.
With a clear plan and a clear goal, we can eliminate the criticism that Squeak needs better documentation. There are tasks to be done. If this road map seems good to the community, we can start systematically dividing up the tasks and assigning responsibilities. I will divide up the tasks into week-long chunks, so that one can contribute by sacrificing 2 to 10 hours per week.
I especially need help from the developers of Sophie, Pier, SUnit, Monticello, and Spoon to evaluate how difficult it will be to:
- Create a system for browsing Documentation along side the code
- Embed unit tests within documentation so that it can be auto-tested for correctness
- Edit from both the image and the web
- Distribute this documentation with the image
- Distribute such documentation as part of a packages
- Edit the documentation locally and commit it to a central (official) image/universe and make it available via the update mechanism (somewhat like a distributed wiki)
I know it is late, but tasks 1-4 would make a great Google Summer of Code project.
Screw that. Comments already satisfy requests 1, 4, 5, and 6, and, if combined with Pier, probably satisfy request 3 easily. Request 2 is Magic Book, and has been moved to the end of the roadmap task list.
Thank you for reading this proposal, and thanks to all who reminded me how important good documentation really is. You know who you are :)
Thank you Max for reminding me about comments.
(I am such an idiot for forgetting about comments)
[1] Squeak Tutorials (Links): http://wiki.squeak.org/squeak/792#Links
[2] Category Index: http://wiki.squeak.org/squeak/5871
[3] Squeak Tutorials: http://wiki.squeak.org/squeak/792
[4] Refactoring the Swiki: http://wiki.squeak.org/squeak/2352
[5] Documentation Table of Contents: http://wiki.squeak.org/squeak/2983
[6] Magic Book: http://wiki.squeak.org/squeak/3004
Matthew,
Re: Magic Book, I said ages ago that I thought an easy hack would be to add extra meta-data tags to a PDF, creating an xPDF (extended PDF). Of course, these hacks don't tend to work all the time on every interpreter (PDF) imaginable, but it is very possible to write our own reader that deviates slightly to enable us to use our own private commands. And anyway, firms like SAP stick loads of weird metadata inside PDFs. And so does Microsoft's Office program.
There are thus several ways of achieving this:
1) You have 1 PDF per topic and include a b64'd lump of code with it at the end of the file. [1]
2) You have PDFs that are slightly larger than the one "topic" atom, and then allow for a new hierarchical (=page based) object (implemented as a separate PDF-object with no true cross-references inside the PDF, this data will be read by a private interpreter).
2 with its new metadata, perhaps implemented in some private manner or as XML or whatever, will then enable one to be able to run scripts on the page to see whether it is out of date with respect to the Squeak that is running (the colour coded tests of the Magic Book).
[1] Just to prove this, I've attached a MINIM/RIFFS PDF (the naming scheme is mine and a friend's), which shows the b64'd stream in action. You can, of course decode without squeak using WinZip, or StuffIt, though YMMV.
On 4/5/07, Matthew Fulmer tapplek@gmail.com wrote:
On Thu, Apr 05, 2007 at 01:22:04AM -0700, Matthew Fulmer wrote:
From discussions I have had on IRC with Derek O'Connell, Max
OrHai, and Paul Bennett, I have decided it is time to propose an official road map for the Squeak Documentation Team for 2007:
We are currently in the formative stages, and a clear goal is starting to emerge, along with a path to get there. We would like to see a Squeak where:
- Tutorials exist in the main image
- All core functionality is documented and up-to-date
- The documentation can be viewed and edited both within the image and from a central website
- The documentation can be easily maintained indefinitely
How can we get there? There are several steps we must take, and they can be done mostly in parallel:
- Collect all existing documentation together in one place.
-- This is nearly complete. We have assembled a list of nearly all Squeak documentation that exists outside of the image: -- Squeak Tutorials (Links)[1] -- Category Index[2]
- Categorize and index all of this documentation.
-- We are undertaking this task in the small at Squeak Tutorials[3], where we are concerned only with categorizing and indexing Squeak Tutorials. From there, we will probably use this hierarchy as a basis for our new index. We stand to gain two things from completing this project: --- A strong core Documentation team, willing and capable of facing the larger challenges ahead --- A first-pass at a usable introductory guide to Squeak -- The next step will be to fix the problems listed at Refactoring the Swiki[4], and complete the Documentation Table of Contents[5].
- Implement Magic Book[6], which will allow the Documentation to be kept up-to-date indefinitely. This will draw from the work done by the implementors of Sophie, Pier, SUnit, and perhaps Gjallar
Max OrHai reminded me that we already have an excellent medium for storing Squeak documentation, better than Sophie, Pier, or anything else:
COMMENTS!!!
This is much more concrete and practical than whatever I was thinking about creating, so I replaced this point with a point about comments and how they could be integrated into Pier.
- Get permission and republish the documentation in a form suitable for distribution and collaboration
-- Paul Bennett has volunteered for this task.
- Integrate SUnit tests into the documentation. Thanks to the 3.10 release team, there should be plenty of unit tests by the time we get to this stage.
I edited this to be more explicit about Magic Book and how the point is document verification
A hyperlinked version of this proposal is on the Doc team home page: http://wiki.squeak.org/squeak/808
This has been updated. Get the newer, saner version there.
With a clear plan and a clear goal, we can eliminate the criticism that Squeak needs better documentation. There are tasks to be done. If this road map seems good to the community, we can start systematically dividing up the tasks and assigning responsibilities. I will divide up the tasks into week-long chunks, so that one can contribute by sacrificing 2 to 10 hours per week.
I especially need help from the developers of Sophie, Pier, SUnit, Monticello, and Spoon to evaluate how difficult it will be to:
- Create a system for browsing Documentation along side the code
- Embed unit tests within documentation so that it can be auto-tested for correctness
- Edit from both the image and the web
- Distribute this documentation with the image
- Distribute such documentation as part of a packages
- Edit the documentation locally and commit it to a central (official) image/universe and make it available via the update mechanism (somewhat like a distributed wiki)
I know it is late, but tasks 1-4 would make a great Google Summer of Code project.
Screw that. Comments already satisfy requests 1, 4, 5, and 6, and, if combined with Pier, probably satisfy request 3 easily. Request 2 is Magic Book, and has been moved to the end of the roadmap task list.
Thank you for reading this proposal, and thanks to all who reminded me how important good documentation really is. You know who you are :)
Thank you Max for reminding me about comments.
(I am such an idiot for forgetting about comments)
[1] Squeak Tutorials (Links): http://wiki.squeak.org/squeak/792#Links
[2] Category Index: http://wiki.squeak.org/squeak/5871
[3] Squeak Tutorials: http://wiki.squeak.org/squeak/792
[4] Refactoring the Swiki: http://wiki.squeak.org/squeak/2352
[5] Documentation Table of Contents: http://wiki.squeak.org/squeak/2983
[6] Magic Book: http://wiki.squeak.org/squeak/3004
-- Matthew Fulmer -- http://mtfulmer.wordpress.com/ Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808
Russell Hyer
squeak-doc@lists.squeakfoundation.org
-
Damien Cassou -
Matthew Fulmer -
Paul Bennett -
Russell N Hyer