-------- Original Message -------- Subject: Re: [squeak-dev] [documentation] HelpSystem, revision control, and process From: Ian Trudel ian.trudel@gmail.com Date: Fri, April 30, 2010 5:20 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Quick question, Ken (and Casey).
How will the core related documentation will be transfered to the core image assuming what you wrote will define our process? HelpSystem includes classes and methods comments.
Ian.
Well, this is exactly why I have that leading sentence. ;) I have no idea how content distribution (which is what I assume you are asking about) is meant to work in HelpSystem. I have to assume from Casey's question that it can be distributed in a mcz. As such it can be retrieved via any method desired and from any location. What triggers loading any particular content? I don't know, is there meant to be a catalog something like SqueakMap or Package Universes? Or is help for a particular package an optional dependency? Clearly, as I stated, I have no end of questions.
Ken
2010/4/30 Ken Causey ken@kencausey.com:
I haven't been following the HelpSystem discussion very closely so there is no limit to what I don't know on this subject. That said I would be perfectly happy setting up a HelpSystem repository on source.squeak.org.
In general I feel we need to start limiting the contents of the trunk repository to those packages that compose 'core' Squeak and start considering add-ons used to build 'basic' Squeak as separate packages installed into 'core'. I'm assuming that HelpSystem is something we would want to include in a 'basic' image, but not a 'core' image. (Of course a 'core' ZIP might include ready to load optional packages including HelpSystem.)
Ken
-------- Original Message -------- Subject: [squeak-dev] [documentation] HelpSystem, revision control, and process From: Casey Ransberger casey.obrien.r@gmail.com Date: Fri, April 30, 2010 3:22 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Folks,
I'd like to get a process going around HelpSystem. It doesn't have to be a perfect process. We can tweak it as we go.
How do people feel about having help in the Trunk? It'll allow us to document things right along side of our software development.
One thing worth noting: we can have our HelpSystem "book" in Trunk without necessarily having HelpSystem itself in the Trunk; however, if we do it that way, we run the risk of changes in HelpSystem on SqueakSource making our help content impossible to load. I think having both in the Trunk is a really good idea.
If folks aren't comfortable with having some documentation and HelpSystem in Trunk, I'd like to propose opening up a 'docs' SS repository on source.squeak.org. We'd lose the ability to track the evolution of our docs in the context of the evolution of Squeak, but we'd still have the keys to the kingdom (license, code, content.)
I'd rather not go with squeaksource.com, as I'd like to think that our docs should live with the other things on squeak.org.
As always, feedback is appreciated.
-- Casey Ransberger<hr>
Ken,
Yeah; it supports keeping documentation in methods. Andreas added a patch that makes it easy to edit a help topic in a workspace, and it recompiles the source method automatically when you accept. So we should be able to use our revision control on our docs (which has proven very useful for me in the past.)
The reason I recommend using Trunk is so that folks don't need to switch contexts to add documentation. I also think that having a help system in a standard image is a good idea. I would expect to modify Smalltalk>>unloadAllKnownPackages to unload it, as I don't believe such a system belongs in a core image at all.
These are just my feelings, though. I do appreciate your caution about adding bloat to Trunk; I cringe a little suggesting it, but I still think it's a good idea. Would you be willing to wait a bit, and gauge the broader community's opinion before making a decision about this? I'm really hoping to have a few more people weigh in on pros and cons. That said, I really do respect your opinion on the matter, and a separate repo on source.squeak.orgwould be fine (maybe source.squeak.org/help).
One thing I would like to do is get a quick gauge of the complexity of HelpSystem so people can get a sense of how much I'm really talking about adding. I'll try and find some time to do that in the next day or two. Good time for me to read el bloggo de Raabo:)
On Fri, Apr 30, 2010 at 3:35 PM, Ken Causey ken@kencausey.com wrote:
-------- Original Message -------- Subject: Re: [squeak-dev] [documentation] HelpSystem, revision control, and process From: Ian Trudel ian.trudel@gmail.com Date: Fri, April 30, 2010 5:20 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Quick question, Ken (and Casey).
How will the core related documentation will be transfered to the core image assuming what you wrote will define our process? HelpSystem includes classes and methods comments.
Ian.
Well, this is exactly why I have that leading sentence. ;) I have no idea how content distribution (which is what I assume you are asking about) is meant to work in HelpSystem. I have to assume from Casey's question that it can be distributed in a mcz. As such it can be retrieved via any method desired and from any location. What triggers loading any particular content? I don't know, is there meant to be a catalog something like SqueakMap or Package Universes? Or is help for a particular package an optional dependency? Clearly, as I stated, I have no end of questions.
Ken
2010/4/30 Ken Causey ken@kencausey.com:
I haven't been following the HelpSystem discussion very closely so
there
is no limit to what I don't know on this subject. That said I would be perfectly happy setting up a HelpSystem repository on
source.squeak.org.
In general I feel we need to start limiting the contents of the trunk repository to those packages that compose 'core' Squeak and start considering add-ons used to build 'basic' Squeak as separate packages installed into 'core'. I'm assuming that HelpSystem is something we would want to include in a 'basic' image, but not a 'core' image. (Of course a 'core' ZIP might include ready to load optional packages including HelpSystem.)
Ken
-------- Original Message -------- Subject: [squeak-dev] [documentation] HelpSystem, revision control,
and
process From: Casey Ransberger casey.obrien.r@gmail.com Date: Fri, April 30, 2010 3:22 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Folks,
I'd like to get a process going around HelpSystem. It doesn't have to
be a
perfect process. We can tweak it as we go.
How do people feel about having help in the Trunk? It'll allow us to document things right along side of our software development.
One thing worth noting: we can have our HelpSystem "book" in Trunk
without
necessarily having HelpSystem itself in the Trunk; however, if we do
it that
way, we run the risk of changes in HelpSystem on SqueakSource making
our
help content impossible to load. I think having both in the Trunk is a really good idea.
If folks aren't comfortable with having some documentation and
HelpSystem in
Trunk, I'd like to propose opening up a 'docs' SS repository on source.squeak.org. We'd lose the ability to track the evolution of
our docs
in the context of the evolution of Squeak, but we'd still have the
keys to
the kingdom (license, code, content.)
I'd rather not go with squeaksource.com, as I'd like to think that
our docs
should live with the other things on squeak.org.
As always, feedback is appreciated.
-- Casey Ransberger<hr>
On 4/30/2010 4:27 PM, Casey Ransberger wrote:
The reason I recommend using Trunk is so that folks don't need to switch contexts to add documentation. I also think that having a help system in a standard image is a good idea. I would expect to modify Smalltalk>>unloadAllKnownPackages to unload it, as I don't believe such a system belongs in a core image at all.
These are just my feelings, though. I do appreciate your caution about adding bloat to Trunk; I cringe a little suggesting it, but I still think it's a good idea. Would you be willing to wait a bit, and gauge the broader community's opinion before making a decision about this?
Personally, I'm in favor of this approach for reasons of raising the perceived value of documentation. Someone who writes documentation in Squeak is improving it every bit as much as someone who is writing code. Giving them access to the trunk is one of the ways in which we can visibly acknowledge the contribution.
And of course, just as with code contributions, if we want documentation we need to make it easy to contribute and provide a clear path for contributions. Giving the people working on the documentation unfettered access to the trunk is in line with that goal.
Cheers, - Andreas
On 4/30/10, Casey Ransberger casey.obrien.r@gmail.com wrote:
The reason I recommend using Trunk is so that folks don't need to switch contexts to add documentation. I also think that having a help system in a standard image is a good idea.
+1
I would expect to modify
Smalltalk>>unloadAllKnownPackages to unload it, as I don't believe such a system belongs in a core image at all.
+1 or just having a script which removes the documentation if people want to go for a runtime system. But probably then still people want documentation to be there for service purposes.
These are just my feelings, though. I do appreciate your caution about adding bloat to Trunk;
I'am astonished that you use the word 'bloat' in connection with documentation :-(
--Hannes
Comments inline.
On Fri, Apr 30, 2010 at 5:06 PM, Hannes Hirzel hannes.hirzel@gmail.comwrote:
On 4/30/10, Casey Ransberger casey.obrien.r@gmail.com wrote:
The reason I recommend using Trunk is so that folks don't need to switch contexts to add documentation. I also think that having a help system in
a
standard image is a good idea.
+1
thanks
I would expect to modify
Smalltalk>>unloadAllKnownPackages to unload it, as I don't believe such a system belongs in a core image at all.
+1
thanks
or just having a script which removes the documentation if people want to go for a runtime system. But probably then still people want documentation to be there for service purposes.
These are just my feelings, though. I do appreciate your caution about adding bloat to Trunk;
I'am astonished that you use the word 'bloat' in connection with documentation :-(
We should be careful about how much and what stuff we keep in the Trunk. The contents of the Trunk are our Karma. That's all I'm saying. I'm not knocking docs. Keep in mind I'm suggesting to include a documentation system in Trunk... because that's my Karma. Dig it, man?
--Hannes
Ah, I missed something in your message. I am recommending Monticello for contributions of in-image documentation, but I am *not* recommending Monticello for *distribution* of in-image documentation. For distribution, I'm less particular, but I think something like SqueakMap would be a great choice. I think having the bit of plumbing necessary to load, read, and edit documentation in the standard image would be fine, but I don't think we'd want to include the actual docs by default (maybe just a menu item to install the documentation, or some such thing.) I would expect that the aforementioned plumbing would be unloaded with #unloadAllKnownPackages.
Hope that clarifies my position a bit.
On Fri, Apr 30, 2010 at 3:35 PM, Ken Causey ken@kencausey.com wrote:
-------- Original Message -------- Subject: Re: [squeak-dev] [documentation] HelpSystem, revision control, and process From: Ian Trudel ian.trudel@gmail.com Date: Fri, April 30, 2010 5:20 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Quick question, Ken (and Casey).
How will the core related documentation will be transfered to the core image assuming what you wrote will define our process? HelpSystem includes classes and methods comments.
Ian.
Well, this is exactly why I have that leading sentence. ;) I have no idea how content distribution (which is what I assume you are asking about) is meant to work in HelpSystem. I have to assume from Casey's question that it can be distributed in a mcz. As such it can be retrieved via any method desired and from any location. What triggers loading any particular content? I don't know, is there meant to be a catalog something like SqueakMap or Package Universes? Or is help for a particular package an optional dependency? Clearly, as I stated, I have no end of questions.
Ken
2010/4/30 Ken Causey ken@kencausey.com:
I haven't been following the HelpSystem discussion very closely so
there
is no limit to what I don't know on this subject. That said I would be perfectly happy setting up a HelpSystem repository on
source.squeak.org.
In general I feel we need to start limiting the contents of the trunk repository to those packages that compose 'core' Squeak and start considering add-ons used to build 'basic' Squeak as separate packages installed into 'core'. I'm assuming that HelpSystem is something we would want to include in a 'basic' image, but not a 'core' image. (Of course a 'core' ZIP might include ready to load optional packages including HelpSystem.)
Ken
-------- Original Message -------- Subject: [squeak-dev] [documentation] HelpSystem, revision control,
and
process From: Casey Ransberger casey.obrien.r@gmail.com Date: Fri, April 30, 2010 3:22 pm To: The general-purpose Squeak developers list squeak-dev@lists.squeakfoundation.org
Folks,
I'd like to get a process going around HelpSystem. It doesn't have to
be a
perfect process. We can tweak it as we go.
How do people feel about having help in the Trunk? It'll allow us to document things right along side of our software development.
One thing worth noting: we can have our HelpSystem "book" in Trunk
without
necessarily having HelpSystem itself in the Trunk; however, if we do
it that
way, we run the risk of changes in HelpSystem on SqueakSource making
our
help content impossible to load. I think having both in the Trunk is a really good idea.
If folks aren't comfortable with having some documentation and
HelpSystem in
Trunk, I'd like to propose opening up a 'docs' SS repository on source.squeak.org. We'd lose the ability to track the evolution of
our docs
in the context of the evolution of Squeak, but we'd still have the
keys to
the kingdom (license, code, content.)
I'd rather not go with squeaksource.com, as I'd like to think that
our docs
should live with the other things on squeak.org.
As always, feedback is appreciated.
-- Casey Ransberger<hr>
squeak-dev@lists.squeakfoundation.org