Smalltalk › Squeak › Squeak - Dev

Roadmap proposal for the Squeak Documentation Team in 2007

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

16 messages Options

Tapple Gao

Roadmap proposal for the Squeak Documentation Team in 2007

>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

--
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808

Damien Cassou-3

Re: Roadmap proposal for the Squeak Documentation Team in 2007

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

--
Damien Cassou

Tapple Gao

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by Tapple Gao

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

timrowledge

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

On 5-Apr-07, at 3:10 PM, Matthew Fulmer wrote:

>
> Max OrHai reminded me that we already have an excellent medium
> for storing Squeak documentation, better than Sophie, Pier, or
> anything else:
>
> COMMENTS!!!

Remember that comments (class or method) can make use of the linkage
capabilities built into Squeak.
You can link pretty much any bit of text to class comments, class
definitons, class hierarchies, methods or URLs.
cmd-6 opens the menu with those items near the end. To quote a
message I sent to colleagues earlier this week:-

> I wouldn't claim it was well implemented or wonderful but it's there.
>
> To link from a comment (method or class) to a class comment
> a) type the correct name of the class in your comment (duh)
> b) select it
> c) cmd-6 opens a menu - near the bottom you will see several items
> related to this
> Do It
> Print It
> Link to comment of class
> Link to definition of class
> Link to hierarchy of class
> Link to method
> be a web URL link
> d) choose 'link to comment of class'
>
> Now if you click on the linked word (blue text) a browser will open
> at the relevant class comment. The other options are useful at
> times; in this context the 'Do It ' and 'Print it' actually make
> links that do or print something. For example
> Date today
> select, choose 'Print It' and then click on it.
>
> The 'link to method ' is a tiny bit more complex; you have to type
> something like
> Integer +
> and select it, choose 'link to method'.
>
> Probably the least useful part is that the implementation is
> somewhat tacky. If you type
> Foo
> select it, choose one of the menu options and then carry on typing
> you will find the new text is included in the link. To remove the
> linkiness you will have to select across the bit that shouldn't be
> linky, cmd-6 and choose 'Edit hidden info'. This will print the
> hidden info ie the 'Integer +' bit from above) and remove the
> linkiness. Usually. Like I said, rather tacky - in fact so tacky
> that the 'hidden info' is printed at the current text selection
> instead of where one might really expect it, next to the link.
>
> You can get extra clever and do something like an html anchor;
> click here for extra pleasure<Integer +>
> will do the same as above but displays 'click here for extra
> pleasure' in the run of text. 'show hidden info' shows the Integer
> + part.
>
> So, you can connect the class comment of a subsidiary class to a
> main class to guide people to the subsystem doc. You can connect
> comments to particular methods. You can connect a method to the
> comment for an important class or other method.

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Strange OpCodes: HAL: Murder Operator

Stéphane Rollandin

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

tim Rowledge wrote:
> cmd-6 opens the menu with those items near the end.

what is cmd-6 on Windows ? I don't find it..

Stef

Bert Freudenberg

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

On Apr 6, 2007, at 9:07 , Stéphane Rollandin wrote:

> tim Rowledge wrote:
>> cmd-6 opens the menu with those items near the end.
>
> what is cmd-6 on Windows ? I don't find it..

Alt-6

- Bert -

Russell N Hyer

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by Tapple Gao

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 <[hidden email]> 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
--
Diploma: English Law with German
University of Kent

RIFFS_PK.PDF (4K) Download Attachment

Edgar J. De Cleene

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by Stéphane Rollandin

El 4/6/07 4:07 AM, "Stéphane Rollandin" <[hidden email]> escribió:

> what is cmd-6 on Windows ? I don't find it..
>
>
> Stef

What ? You don't have a Mac ? Squeak still believe what was '96 and is
running in 68040 Apple computers :=)

Edgar

Stéphane Rollandin

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by Bert Freudenberg

Bert Freudenberg wrote:

>
> On Apr 6, 2007, at 9:07 , Stéphane Rollandin wrote:
>
>> tim Rowledge wrote:
>>> cmd-6 opens the menu with those items near the end.
>>
>> what is cmd-6 on Windows ? I don't find it..
>
> Alt-6
>
> - Bert -

I tried it... it does not do this (it underlines with the top 6 key, and
prints '?' with the numeric pad 6 key)

could this be related to my azerty keyboard ?

Stef

Bert Freudenberg

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

On Apr 6, 2007, at 13:21 , Stéphane Rollandin wrote:

> Bert Freudenberg wrote:
>> On Apr 6, 2007, at 9:07 , Stéphane Rollandin wrote:
>>> tim Rowledge wrote:
>>>> cmd-6 opens the menu with those items near the end.
>>>
>>> what is cmd-6 on Windows ? I don't find it..
>> Alt-6
>> - Bert -
>
> I tried it... it does not do this (it underlines with the top 6
> key, and prints '?' with the numeric pad 6 key)
>
> could this be related to my azerty keyboard ?

Possibly ... that's the weird keyboard where numbers are shifted,
yes? Try switching to US layout temporarily.

- Bert -

Brian Brown-2

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by timrowledge

I agree with Tim and Matt that using comments would be great way to
go, with one caveat :)

The biggest frustration with using comments is that there is no good
"starting place" for a given class category. For example, go browse
the Seaside classes and categories and figure out where one should
start. You can repeat this exercise for any number of categories. I
propose that we we add a documentation attribute to the PackageInfo
stuff, so there is a category level documentation spot, with links to
the appropriate class comments.

Any thoughts?

Brian

On Apr 5, 2007, at 7:10 PM, tim Rowledge wrote:

>
> On 5-Apr-07, at 3:10 PM, Matthew Fulmer wrote:
>
>>
>> Max OrHai reminded me that we already have an excellent medium
>> for storing Squeak documentation, better than Sophie, Pier, or
>> anything else:
>>
>> COMMENTS!!!
>
> Remember that comments (class or method) can make use of the
> linkage capabilities built into Squeak.
> You can link pretty much any bit of text to class comments, class
> definitons, class hierarchies, methods or URLs.
> cmd-6 opens the menu with those items near the end. To quote a
> message I sent to colleagues earlier this week:-
>> I wouldn't claim it was well implemented or wonderful but it's
>> there.
>>
>> To link from a comment (method or class) to a class comment
>> a) type the correct name of the class in your comment (duh)
>> b) select it
>> c) cmd-6 opens a menu - near the bottom you will see several items
>> related to this
>> Do It
>> Print It
>> Link to comment of class
>> Link to definition of class
>> Link to hierarchy of class
>> Link to method
>> be a web URL link
>> d) choose 'link to comment of class'
>>
>> Now if you click on the linked word (blue text) a browser will
>> open at the relevant class comment. The other options are useful
>> at times; in this context the 'Do It ' and 'Print it' actually
>> make links that do or print something. For example
>> Date today
>> select, choose 'Print It' and then click on it.
>>
>> The 'link to method ' is a tiny bit more complex; you have to type
>> something like
>> Integer +
>> and select it, choose 'link to method'.
>>
>> Probably the least useful part is that the implementation is
>> somewhat tacky. If you type
>> Foo
>> select it, choose one of the menu options and then carry on typing
>> you will find the new text is included in the link. To remove the
>> linkiness you will have to select across the bit that shouldn't be
>> linky, cmd-6 and choose 'Edit hidden info'. This will print the
>> hidden info ie the 'Integer +' bit from above) and remove the
>> linkiness. Usually. Like I said, rather tacky - in fact so tacky
>> that the 'hidden info' is printed at the current text selection
>> instead of where one might really expect it, next to the link.
>>
>> You can get extra clever and do something like an html anchor;
>> click here for extra pleasure<Integer +>
>> will do the same as above but displays 'click here for extra
>> pleasure' in the run of text. 'show hidden info' shows the Integer
>> + part.
>>
>> So, you can connect the class comment of a subsidiary class to a
>> main class to guide people to the subsystem doc. You can connect
>> comments to particular methods. You can connect a method to the
>> comment for an important class or other method.
>
>
>
>
> tim
> --
> tim Rowledge; [hidden email]; http://www.rowledge.org/tim
> Strange OpCodes: HAL: Murder Operator
>
>
>

Tapple Gao

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

On Fri, Apr 06, 2007 at 10:21:06AM -0600, Brian Brown wrote:

> I agree with Tim and Matt that using comments would be great way to
> go, with one caveat :)
>
> The biggest frustration with using comments is that there is no good
> "starting place" for a given class category. For example, go browse
> the Seaside classes and categories and figure out where one should
> start. You can repeat this exercise for any number of categories. I
> propose that we we add a documentation attribute to the PackageInfo
> stuff, so there is a category level documentation spot, with links to
> the appropriate class comments.
>
> Any thoughts?

SqueakMap and Universes both have comment mechanisms, and are
probably the best place to start. Adding a comment mechanism to
PackageInfo would be an excellent solution in both the short
term and long term. PackageInfo is probably here to stay for a
while, and, even if it is not, the feature would have to be
supported in any future packaging system (spoon, classboxes,
etc).

Distributing other documents, such as tutorials, is not so
feasible right now, as only code is distributable at the moment.
Spoon is probably the only long-term solution to this issue.

However, this is not the immediate concern. The bigger issue is
to have a working document available *at all*. We have to create
the documentation before we can relevantly worry about where to
store it. Once we have a document that the community is willing
to adopt as "The Official Squeak Documentation", then we can
worry about distributing it and making it more accessible from
within and without the image.

--
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808

Tim Johnson-6

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by Brian Brown-2

When I am trying to figure out which class in a class category is a good
starting point, I look at which class is the lowest in the inheritance
chain...

Cheers,
Tim

timrowledge

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

On 6-Apr-07, at 1:27 PM, Tim Johnson wrote:

>> I agree with Tim and Matt that using comments would be great way to
>> go, with one caveat :)
>>
>> The biggest frustration with using comments is that there is no good
>> "starting place" for a given class category. For example, go browse
>> the Seaside classes and categories and figure out where one should
>> start. You can repeat this exercise for any number of categories. I
>> propose that we we add a documentation attribute to the PackageInfo
>> stuff, so there is a category level documentation spot, with links to
>> the appropriate class comments.
>>
>> Any thoughts?
>
> When I am trying to figure out which class in a class category is a
> good
> starting point, I look at which class is the lowest in the inheritance
> chain...

This problem of 'where to start' is why I pointed out the cross-
linking capability.

For each class involved in a package or subsystem, simply add a link
back to the 'main' class. Put the major documentation there. For
methods involved in a package that doesn't really involve most of the
class, put the link in the method comment. Classes involved in many
packages would need somewhat longer and more developed comments than
we are used to. URL links would allow pointing out to more
sophisticated doc on the web somewhere, in a form that is perhaps
more easily updated

tim
--
tim Rowledge; [hidden email]; http://www.rowledge.org/tim
Porting is such sweet sorrow

Lex Spoon-3

Re: Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by Damien Cassou-3

"Damien Cassou" <[hidden email]> writes:
> 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.

It would be great to develop a tutorials browser that itself is in a
package. Then each tutorial can be in its own package, and can
register itself with the tutorials browser.

-Lex

Lex Spoon-3

Re: [Squeak-doc] Roadmap proposal for the Squeak Documentation Team in 2007

In reply to this post by timrowledge

tim Rowledge <[hidden email]> writes:

> This problem of 'where to start' is why I pointed out the cross-
> linking capability.
>
> For each class involved in a package or subsystem, simply add a link
> back to the 'main' class. Put the major documentation there. For
> methods involved in a package that doesn't really involve most of the
> class, put the link in the method comment. Classes involved in many
> packages would need somewhat longer and more developed comments than
> we are used to. URL links would allow pointing out to more
> sophisticated doc on the web somewhere, in a form that is perhaps
> more easily updated

In addition to these explicit links, you can keep in mind common
places that programmers will look. Things to consider:

1. Think about what looks like he main classes of the package to begin
with. If there is a Seaside class, then people wanting to read
about Seaside are going to go there. In Morphic, everybody is
going to look at class Marph, so make sure it has a good comment.

2. You can create classes just for documentation. There is nothing at
all wrong with making a class like SMAAAReadme as starting point in
some category.

3. Likewise for categories. You can perfectly well make a
Morphic-Tutorials category if you like.

3. The same things apply to methods, as to classes. It works well to
put "examples" methods on the class side of important methods.

Just a few thoughts. In general, there is a world of possibility with
the existing documentation tools.

Lex