[documentation] HelpSystem, revision control, and process
Locked
[documentation] HelpSystem, revision control, and process
 
|
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 |
RE: [documentation] HelpSystem, revision control, and process
|
|
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 <[hidden email]> > Date: Fri, April 30, 2010 3:22 pm > To: The general-purpose Squeak developers list > <[hidden email]> > > > 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> |
Re: [documentation] HelpSystem, revision control, and process
|
|
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. 2010/4/30 Ken Causey <[hidden email]>: > 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 <[hidden email]> >> Date: Fri, April 30, 2010 3:22 pm >> To: The general-purpose Squeak developers list >> <[hidden email]> >> >> >> 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> > > > -- http://mecenia.blogspot.com/ |
RE: [documentation] HelpSystem, revision control, and process
|
|
In reply to this post by Casey Ransberger-2
> -------- Original Message --------
> Subject: Re: [squeak-dev] [documentation] HelpSystem, revision control, > and process > From: Ian Trudel <[hidden email]> > Date: Fri, April 30, 2010 5:20 pm > To: The general-purpose Squeak developers list > <[hidden email]> > > > 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 <[hidden email]>: > > 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 <[hidden email]> > >> Date: Fri, April 30, 2010 3:22 pm > >> To: The general-purpose Squeak developers list > >> <[hidden email]> > >> > >> > >> 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> > > > > > > > > > > -- > http://mecenia.blogspot.com/ |
Re: [documentation] HelpSystem, revision control, and process
|
|
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.org would 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 <[hidden email]> wrote:
-- Casey Ransberger |
Re: [documentation] HelpSystem, revision control, and process
|
|
In reply to this post by Ken Causey-3
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 <[hidden email]> wrote:
-- Casey Ransberger |
Re: [documentation] HelpSystem, revision control, and process
|
|
In reply to this post by Casey Ransberger-2
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 |
Re: [documentation] HelpSystem, revision control, and process
|
|
In reply to this post by Casey Ransberger-2
On 4/30/10, Casey Ransberger <[hidden email]> 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 |
Re: [documentation] HelpSystem, revision control, and process
|
|
Comments inline.
On Fri, Apr 30, 2010 at 5:06 PM, Hannes Hirzel <[hidden email]> wrote:
thanks
thanks or just having a script which removes the documentation if people want 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 -- Casey Ransberger |
Re: [documentation] HelpSystem, revision control, and process
|
|
In reply to this post by Ken Causey-3
On 01.05.2010, at 00:10, "Ken Causey" <[hidden email]> wrote:
> 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 I still would put these into the trunk repo. This is independent of whether to put them into a release image or ship them externally. There is, however, some need to optimize or clean out the repo. It feels ever slower. How about moving out all package versions prior to the 4.1 release? - Bert - |
Re: [documentation] HelpSystem, revision control, and process
|
|
There is an additional advantage to use the trunk: we can capitalize
over the current success of the trunk. Plus, documentation commits will be reported (as other commits) and it's a great way to show how much positive energy is sunken in Squeak. Ian. -- http://mecenia.blogspot.com/ |
«
Return to Squeak - Dev
|
1 view|%1 views
| Free forum by Nabble | Edit this page |