Call for better (easier) documentation standards

Are you talking about a complete build system / web hosting setup, or
using an existing build system and web host? As far as maven with
github is concerned, the setup I did for you is quite simple. I don't
use maven at all, I use sbt for all my projects, so I am not that
familiar with how maven works but setting you up only took about 10
mins (I did it because I was mostly just curious to see if there was
something out there that would do it). The only problem I had with it
was that it did not automatically fall back to using my own git and
ssh config, requiring a settings.xml file that defined where my ssh
private key was.

I would like to have a plugin for sbt that would do the same thing,
maybe it is out there, but again it wouldn't be something I'd want to
be there automatically with every project as not every project will be
using git and stored at github, so there would have to be some amount
of setup and config.

Or do you mean something like Ruby gems where the code and
documentation are rolled up into one easy-to-install package? The
problem with that is maven repositories seem to be the standard way of
hosting dependencies for the jvm. For my own projects that would mean
any dependency not hosted in a maven friendly way would have to be
manually included.

On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
wrote:
> A little bit of background:
> I have a site on github which promises to make regular expressions easier to
> use.
> However, I'm not a programmer, I'm a tech writer by nature.
> After reading about gh-pages, I decided it was too complex for the likes of
> me.
>
> Derek has very kindly offered the following:
> I forked your repo and added changes to pom.xml to allow you to use
> wagon-gitsite to auto publish. Tested it and the results can be seen
> at: http://derekjw.github.com/rex
>
> Just make sure you have a settings.xml in your maven directory
> (~/.m2/settings.xml in linux) that looks something like this:
>
>
>  
>    
>      rexsite
>      git
>      /home/derek/.ssh/id_rsa
>    
>  
>
>
> But why should users be required to have settings in their Maven directory?
> Why should they even need to know what a Maven directory is? (I certainly
> didn't want to)
>
> I've been in the tech writing business for a while now, and it is one of the
> most overlooked ways of getting attention to projects. People will much more
> readily read a well done document that explains the pluses and minuses of
> cases, than they will go to the trouble of dl'ing a distro, compiling it,
> running with all the attendant errors, and finally deploying it. Let's make
> sense, which is more cost effective. A well-reasoned appeal to a highly
> intelligent, but discerning, audience, or a piece of (effectively) raw code.
> So here's the gauntlet I'm throwing down. Come up with a way that
> distributes, IN TANDEM, the documentation that accompanies a piece of code,
> an easy way of installing and reading that code, and one that doesn't
> require complex file setups, absurd config files, etc. etc. Because I
> guarantee you, if you can do that, you'll get a lot more eyeballs.
> Now maybe this already exists and I just haven't seen it. But I've been
> looking for awhile...
> Cheers,
> Ken

On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:

> Are you talking about a complete build system / web hosting setup, or
> using an existing build system and web host?

The second. Bye the way thanks for all the help!
> As far as maven with
> github is concerned, the setup I did for you is quite simple. I don't
> use maven at all, I use sbt for all my projects, so I am not that
> familiar with how maven works but setting you up only took about 10
> mins (I did it because I was mostly just curious to see if there was
> something out there that would do it). The only problem I had with it
> was that it did not automatically fall back to using my own git and
> ssh config, requiring a settings.xml file that defined where my ssh
> private key was.

This may be minor to you. But it could be major to someone who just wants to write, and document, good Scala code. I've configured ssh in the past, so at least knew what it was, but ssh, while simple to use once you are in the know, is not a trivial learning curve. To paraphrase a quote from I don't know where, "Things should be just simple enough, and no simpler." In my opinion, the successful documenter should need to know the following:
1) The source documentation of the scaladoc (in the build tree).
2) The destination doc of the scaladoc (in the WWW).
No further knowledge should be necessary. If it is, it should be prompted for during the installation process.

I can remember the days when I used to love to catch the original knowledge of bits and bytes. (Yep, kids, in those days, we really were learning bits and bytes. Why, I almost remember the knickname I had for 6502 register...no, no, let's not go there. Bye the way, did you know the 6502 was a simply awesome bit of computing. If I recall, it was the only Asych logic CPU on the market. Ah, how times move on.) But as people get older, other things assume more important roles. Wife, family, social life. Time becomes precious--too precious to be spent learning and relearning bits of hackery.
>
> I would like to have a plugin for sbt that would do the same thing,
> maybe it is out there, but again it wouldn't be something I'd want to
> be there automatically with every project as not every project will be
> using git and stored at github, so there would have to be some amount
> of setup and config.
>
> Or do you mean something like Ruby gems where the code and
> documentation are rolled up into one easy-to-install package? The
> problem with that is maven repositories seem to be the standard way of
> hosting dependencies for the jvm. For my own projects that would mean
> any dependency not hosted in a maven friendly way would have to be
> manually included.

I think the latter. I note the following of your implementation (nothing to do with you)

http://derekjw.github.com/rex/ does not exactly provide a clear path to the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of links deep.

I provided a __README__ class whose only function was to serve as the "central" document. Clicking on this produces an error. Not sure why. Maybe the pages were too large?
>
> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
> wrote:
>> A little bit of background:
>> I have a site on github which promises to make regular expressions easier to
>> use.
>> However, I'm not a programmer, I'm a tech writer by nature.
>> After reading about gh-pages, I decided it was too complex for the likes of
>> me.
>>
>> Derek has very kindly offered the following:
>> I forked your repo and added changes to pom.xml to allow you to use
>> wagon-gitsite to auto publish. Tested it and the results can be seen
>> at: http://derekjw.github.com/rex
>>
>> Just make sure you have a settings.xml in your maven directory
>> (~/.m2/settings.xml in linux) that looks something like this:
>>
>>
>>
>>
>> rexsite
>> git
>> /home/derek/.ssh/id_rsa
>>
>>
>>
>>
>> But why should users be required to have settings in their Maven directory?
>> Why should they even need to know what a Maven directory is? (I certainly
>> didn't want to)
>>
>> I've been in the tech writing business for a while now, and it is one of the
>> most overlooked ways of getting attention to projects. People will much more
>> readily read a well done document that explains the pluses and minuses of
>> cases, than they will go to the trouble of dl'ing a distro, compiling it,
>> running with all the attendant errors, and finally deploying it. Let's make
>> sense, which is more cost effective. A well-reasoned appeal to a highly
>> intelligent, but discerning, audience, or a piece of (effectively) raw code.
>> So here's the gauntlet I'm throwing down. Come up with a way that
>> distributes, IN TANDEM, the documentation that accompanies a piece of code,
>> an easy way of installing and reading that code, and one that doesn't
>> require complex file setups, absurd config files, etc. etc. Because I
>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>> Now maybe this already exists and I just haven't seen it. But I've been
>> looking for awhile...
>> Cheers,
>> Ken
>
>
>

Ken,

Interesting discussion. Have you considered making some kind of SBT
plugin to assist in this process? I mean, perhaps a gh-pages
plugin... it could automate the setup of the steps your originally
outlined. Just spitballing :-)

Cheers, Tim

On 31 October 2010 17:50, Kenneth McDonald
wrote:
>
> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>
>> Are you talking about a complete build system / web hosting setup, or
>> using an existing build system and web host?
>
> The second. Bye the way thanks for all the help!
>> As far as maven with
>> github is concerned, the setup I did for you is quite simple. I don't
>> use maven at all, I use sbt for all my projects, so I am not that
>> familiar with how maven works but setting you up only took about 10
>> mins (I did it because I was mostly just curious to see if there was
>> something out there that would do it). The only problem I had with it
>> was that it did not automatically fall back to using my own git and
>> ssh config, requiring a settings.xml file that defined where my ssh
>> private key was.
>
> This may be minor to you. But it could be major to someone who just wants to write, and document, good Scala code. I've configured ssh in the past, so at least knew what it was, but ssh, while simple to use once you are in the know, is not a trivial learning curve. To paraphrase a quote from I don't know where, "Things should be just simple enough, and no simpler." In my opinion, the successful documenter should need to know the following:
>        1) The source documentation of the scaladoc (in the build tree).
>        2) The destination doc of the scaladoc (in the WWW).
> No further knowledge should be necessary. If it is, it should be prompted for during the installation process.
>
> I can remember the days when I used to love to catch the original knowledge of bits and bytes. (Yep, kids, in those days, we really were learning bits and bytes. Why, I almost remember the knickname I had for 6502 register...no, no, let's not go there. Bye the way, did you know the 6502 was a simply awesome bit of computing. If I recall, it was the only Asych logic CPU on the market. Ah, how times move on.) But as people get older, other things assume more important roles. Wife, family, social life. Time becomes precious--too precious to be spent learning and relearning bits of hackery.
>>
>> I would like to have a plugin for sbt that would do the same thing,
>> maybe it is out there, but again it wouldn't be something I'd want to
>> be there automatically with every project as not every project will be
>> using git and stored at github, so there would have to be some amount
>> of setup and config.
>>
>> Or do you mean something like Ruby gems where the code and
>> documentation are rolled up into one easy-to-install package? The
>> problem with that is maven repositories seem to be the standard way of
>> hosting dependencies for the jvm. For my own projects that would mean
>> any dependency not hosted in a maven friendly way would have to be
>> manually included.
>
> I think the latter. I note the following of your implementation (nothing to do with you)
>
> http://derekjw.github.com/rex/ does not exactly provide a clear path to the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of links deep.
>
> I provided a __README__ class whose only function was to serve as the "central" document. Clicking on this produces an error. Not sure why. Maybe the pages were too large?
>>
>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> wrote:
>>> A little bit of background:
>>> I have a site on github which promises to make regular expressions easier to
>>> use.
>>> However, I'm not a programmer, I'm a tech writer by nature.
>>> After reading about gh-pages, I decided it was too complex for the likes of
>>> me.
>>>
>>> Derek has very kindly offered the following:
>>> I forked your repo and added changes to pom.xml to allow you to use
>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>> at: http://derekjw.github.com/rex
>>>
>>> Just make sure you have a settings.xml in your maven directory
>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>
>>>
>>>  
>>>    
>>>      rexsite
>>>      git
>>>      /home/derek/.ssh/id_rsa
>>>    
>>>  
>>>
>>>
>>> But why should users be required to have settings in their Maven directory?
>>> Why should they even need to know what a Maven directory is? (I certainly
>>> didn't want to)
>>>
>>> I've been in the tech writing business for a while now, and it is one of the
>>> most overlooked ways of getting attention to projects. People will much more
>>> readily read a well done document that explains the pluses and minuses of
>>> cases, than they will go to the trouble of dl'ing a distro, compiling it,
>>> running with all the attendant errors, and finally deploying it. Let's make
>>> sense, which is more cost effective. A well-reasoned appeal to a highly
>>> intelligent, but discerning, audience, or a piece of (effectively) raw code.
>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>> distributes, IN TANDEM, the documentation that accompanies a piece of code,
>>> an easy way of installing and reading that code, and one that doesn't
>>> require complex file setups, absurd config files, etc. etc. Because I
>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>> Now maybe this already exists and I just haven't seen it. But I've been
>>> looking for awhile...
>>> Cheers,
>>> Ken
>>
>>
>>
>> --
>> Derek
>
> Thanks,
> Ken
>
>

Tim,

Thanks for the interest. I'll take a look at it if I get a chance, but as I've mentioned, I'm really not a programmer, I'm a tech writer with an inclination towards programming. I would need to do a lot of coming up to speed to be able to do that, I suspect.

Basically, I like doing rather small projects, and then giving them the docs they need to be useful. Twenty years ago, I would've been in there hacking with the best (or at least most enthusiastic), but my tastes have changed over time.

Cheers,
Ken

On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:

> Ken,
>
> Interesting discussion. Have you considered making some kind of SBT
> plugin to assist in this process? I mean, perhaps a gh-pages
> plugin... it could automate the setup of the steps your originally
> outlined. Just spitballing :-)
>
> Cheers, Tim
>
> On 31 October 2010 17:50, Kenneth McDonald
> wrote:
>>
>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>>
>>> Are you talking about a complete build system / web hosting setup, or
>>> using an existing build system and web host?
>>
>> The second. Bye the way thanks for all the help!
>>> As far as maven with
>>> github is concerned, the setup I did for you is quite simple. I don't
>>> use maven at all, I use sbt for all my projects, so I am not that
>>> familiar with how maven works but setting you up only took about 10
>>> mins (I did it because I was mostly just curious to see if there was
>>> something out there that would do it). The only problem I had with it
>>> was that it did not automatically fall back to using my own git and
>>> ssh config, requiring a settings.xml file that defined where my ssh
>>> private key was.
>>
>> This may be minor to you. But it could be major to someone who just wants to write, and document, good Scala code. I've configured ssh in the past, so at least knew what it was, but ssh, while simple to use once you are in the know, is not a trivial learning curve. To paraphrase a quote from I don't know where, "Things should be just simple enough, and no simpler." In my opinion, the successful documenter should need to know the following:
>> 1) The source documentation of the scaladoc (in the build tree).
>> 2) The destination doc of the scaladoc (in the WWW).
>> No further knowledge should be necessary. If it is, it should be prompted for during the installation process.
>>
>> I can remember the days when I used to love to catch the original knowledge of bits and bytes. (Yep, kids, in those days, we really were learning bits and bytes. Why, I almost remember the knickname I had for 6502 register...no, no, let's not go there. Bye the way, did you know the 6502 was a simply awesome bit of computing. If I recall, it was the only Asych logic CPU on the market. Ah, how times move on.) But as people get older, other things assume more important roles. Wife, family, social life. Time becomes precious--too precious to be spent learning and relearning bits of hackery.
>>>
>>> I would like to have a plugin for sbt that would do the same thing,
>>> maybe it is out there, but again it wouldn't be something I'd want to
>>> be there automatically with every project as not every project will be
>>> using git and stored at github, so there would have to be some amount
>>> of setup and config.
>>>
>>> Or do you mean something like Ruby gems where the code and
>>> documentation are rolled up into one easy-to-install package? The
>>> problem with that is maven repositories seem to be the standard way of
>>> hosting dependencies for the jvm. For my own projects that would mean
>>> any dependency not hosted in a maven friendly way would have to be
>>> manually included.
>>
>> I think the latter. I note the following of your implementation (nothing to do with you)
>>
>> http://derekjw.github.com/rex/ does not exactly provide a clear path to the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of links deep.
>>
>> I provided a __README__ class whose only function was to serve as the "central" document. Clicking on this produces an error. Not sure why. Maybe the pages were too large?
>>>
>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>>> wrote:
>>>> A little bit of background:
>>>> I have a site on github which promises to make regular expressions easier to
>>>> use.
>>>> However, I'm not a programmer, I'm a tech writer by nature.
>>>> After reading about gh-pages, I decided it was too complex for the likes of
>>>> me.
>>>>
>>>> Derek has very kindly offered the following:
>>>> I forked your repo and added changes to pom.xml to allow you to use
>>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>>> at: http://derekjw.github.com/rex
>>>>
>>>> Just make sure you have a settings.xml in your maven directory
>>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>>
>>>>
>>>>
>>>>
>>>> rexsite
>>>> git
>>>> /home/derek/.ssh/id_rsa
>>>>
>>>>
>>>>
>>>>
>>>> But why should users be required to have settings in their Maven directory?
>>>> Why should they even need to know what a Maven directory is? (I certainly
>>>> didn't want to)
>>>>
>>>> I've been in the tech writing business for a while now, and it is one of the
>>>> most overlooked ways of getting attention to projects. People will much more
>>>> readily read a well done document that explains the pluses and minuses of
>>>> cases, than they will go to the trouble of dl'ing a distro, compiling it,
>>>> running with all the attendant errors, and finally deploying it. Let's make
>>>> sense, which is more cost effective. A well-reasoned appeal to a highly
>>>> intelligent, but discerning, audience, or a piece of (effectively) raw code.
>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>>> distributes, IN TANDEM, the documentation that accompanies a piece of code,
>>>> an easy way of installing and reading that code, and one that doesn't
>>>> require complex file setups, absurd config files, etc. etc. Because I
>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>>> Now maybe this already exists and I just haven't seen it. But I've been
>>>> looking for awhile...
>>>> Cheers,
>>>> Ken
>>>
>>>
>>>
>>> --
>>> Derek
>>
>> Thanks,
>> Ken
>>
>>

By the way, you know that github has a button to generate a starter github pages page?

On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald <kenneth.m.mcdonald@sbcglobal.net> wrote:

Tim,

Thanks for the interest. I'll take a look at it if I get a chance, but as I've mentioned, I'm really not a programmer, I'm a tech writer with an inclination towards programming. I would need to do a lot of coming up to speed to be able to do that, I suspect.

Basically, I like doing rather small projects, and then giving them the docs they need to be useful. Twenty years ago, I would've been in there hacking with the best (or at least most enthusiastic), but my tastes have changed over time.

Cheers,
Ken


On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:

> Ken,
>
> Interesting discussion. Have you considered making some kind of SBT
> plugin to assist in this process?  I mean, perhaps a gh-pages
> plugin... it could automate the setup of the steps your originally
> outlined. Just spitballing :-)
>
> Cheers, Tim
>
> On 31 October 2010 17:50, Kenneth McDonald
> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>
>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>>
>>> Are you talking about a complete build system / web hosting setup, or
>>> using an existing build system and web host?
>>
>> The second. Bye the way thanks for all the help!
>>> As far as maven with
>>> github is concerned, the setup I did for you is quite simple. I don't
>>> use maven at all, I use sbt for all my projects, so I am not that
>>> familiar with how maven works but setting you up only took about 10
>>> mins (I did it because I was mostly just curious to see if there was
>>> something out there that would do it). The only problem I had with it
>>> was that it did not automatically fall back to using my own git and
>>> ssh config, requiring a settings.xml file that defined where my ssh
>>> private key was.
>>
>> This may be minor to you. But it could be major to someone who just wants to write, and document, good Scala code. I've configured ssh in the past, so at least knew what it was, but ssh, while simple to use once you are in the know, is not a trivial learning curve. To paraphrase a quote from I don't know where, "Things should be just simple enough, and no simpler." In my opinion, the successful documenter should need to know the following:
>>        1) The source documentation of the scaladoc (in the build tree).
>>        2) The destination doc of the scaladoc (in the WWW).
>> No further knowledge should be necessary. If it is, it should be prompted for during the installation process.
>>
>> I can remember the days when I used to love to catch the original knowledge of bits and bytes. (Yep, kids, in those days, we really were learning bits and bytes. Why, I almost remember the knickname I had for 6502 register...no, no, let's not go there. Bye the way, did you know the 6502 was a simply awesome bit of computing. If I recall, it was the only Asych logic CPU on the market. Ah, how times move on.) But as people get older, other things assume more important roles. Wife, family, social life. Time becomes precious--too precious to be spent learning and relearning bits of hackery.
>>>
>>> I would like to have a plugin for sbt that would do the same thing,
>>> maybe it is out there, but again it wouldn't be something I'd want to
>>> be there automatically with every project as not every project will be
>>> using git and stored at github, so there would have to be some amount
>>> of setup and config.
>>>
>>> Or do you mean something like Ruby gems where the code and
>>> documentation are rolled up into one easy-to-install package? The
>>> problem with that is maven repositories seem to be the standard way of
>>> hosting dependencies for the jvm. For my own projects that would mean
>>> any dependency not hosted in a maven friendly way would have to be
>>> manually included.
>>
>> I think the latter. I note the following of your implementation (nothing to do with you)
>>
>> http://derekjw.github.com/rex/ does not exactly provide a clear path to the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of links deep.
>>
>> I provided a __README__ class whose only function was to serve as the "central" document. Clicking on this produces an error. Not sure why. Maybe the pages were too large?
>>>
>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>> A little bit of background:
>>>> I have a site on github which promises to make regular expressions easier to
>>>> use.
>>>> However, I'm not a programmer, I'm a tech writer by nature.
>>>> After reading about gh-pages, I decided it was too complex for the likes of
>>>> me.
>>>>
>>>> Derek has very kindly offered the following:
>>>> I forked your repo and added changes to pom.xml to allow you to use
>>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>>> at: http://derekjw.github.com/rex
>>>>
>>>> Just make sure you have a settings.xml in your maven directory
>>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>>
>>>> <settings>
>>>>  <servers>
>>>>    <server>
>>>>      <id>rexsite</id>
>>>>      <username>git</username>
>>>>      <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>>>>    </server>
>>>>  </servers>
>>>> </settings>
>>>>
>>>> But why should users be required to have settings in their Maven directory?
>>>> Why should they even need to know what a Maven directory is? (I certainly
>>>> didn't want to)
>>>>
>>>> I've been in the tech writing business for a while now, and it is one of the
>>>> most overlooked ways of getting attention to projects. People will much more
>>>> readily read a well done document that explains the pluses and minuses of
>>>> cases, than they will go to the trouble of dl'ing a distro, compiling it,
>>>> running with all the attendant errors, and finally deploying it. Let's make
>>>> sense, which is more cost effective. A well-reasoned appeal to a highly
>>>> intelligent, but discerning, audience, or a piece of (effectively) raw code.
>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>>> distributes, IN TANDEM, the documentation that accompanies a piece of code,
>>>> an easy way of installing and reading that code, and one that doesn't
>>>> require complex file setups, absurd config files, etc. etc. Because I
>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>>> Now maybe this already exists and I just haven't seen it. But I've been
>>>> looking for awhile...
>>>> Cheers,
>>>> Ken
>>>
>>>
>>>
>>> --
>>> Derek
>>
>> Thanks,
>> Ken
>>
>>

Kenneth,

You are a tech writer, but are you a tech reader [1] ?
What failed with the instructions, I provided, to help you push site
on github gh-pages (with the response I could write a better
documentation) ?

[1] http://maven.apache.org/plugins/maven-site-plugin/

/davidB

On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim wrote:
> By the way, you know that github has a button to generate a starter github
> pages page?
>
> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
> wrote:
>>
>> Tim,
>>
>> Thanks for the interest. I'll take a look at it if I get a chance, but as
>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>> inclination towards programming. I would need to do a lot of coming up to
>> speed to be able to do that, I suspect.
>>
>> Basically, I like doing rather small projects, and then giving them the
>> docs they need to be useful. Twenty years ago, I would've been in there
>> hacking with the best (or at least most enthusiastic), but my tastes have
>> changed over time.
>>
>> Cheers,
>> Ken
>>
>>
>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>>
>> > Ken,
>> >
>> > Interesting discussion. Have you considered making some kind of SBT
>> > plugin to assist in this process?  I mean, perhaps a gh-pages
>> > plugin... it could automate the setup of the steps your originally
>> > outlined. Just spitballing :-)
>> >
>> > Cheers, Tim
>> >
>> > On 31 October 2010 17:50, Kenneth McDonald
>> > wrote:
>> >>
>> >> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>> >>
>> >>> Are you talking about a complete build system / web hosting setup, or
>> >>> using an existing build system and web host?
>> >>
>> >> The second. Bye the way thanks for all the help!
>> >>> As far as maven with
>> >>> github is concerned, the setup I did for you is quite simple. I don't
>> >>> use maven at all, I use sbt for all my projects, so I am not that
>> >>> familiar with how maven works but setting you up only took about 10
>> >>> mins (I did it because I was mostly just curious to see if there was
>> >>> something out there that would do it). The only problem I had with it
>> >>> was that it did not automatically fall back to using my own git and
>> >>> ssh config, requiring a settings.xml file that defined where my ssh
>> >>> private key was.
>> >>
>> >> This may be minor to you. But it could be major to someone who just
>> >> wants to write, and document, good Scala code. I've configured ssh in the
>> >> past, so at least knew what it was, but ssh, while simple to use once you
>> >> are in the know, is not a trivial learning curve. To paraphrase a quote from
>> >> I don't know where, "Things should be just simple enough, and no simpler."
>> >> In my opinion, the successful documenter should need to know the following:
>> >>        1) The source documentation of the scaladoc (in the build tree).
>> >>        2) The destination doc of the scaladoc (in the WWW).
>> >> No further knowledge should be necessary. If it is, it should be
>> >> prompted for during the installation process.
>> >>
>> >> I can remember the days when I used to love to catch the original
>> >> knowledge of bits and bytes. (Yep, kids, in those days, we really were
>> >> learning bits and bytes. Why, I almost remember the knickname I had for 6502
>> >> register...no, no, let's not go there. Bye the way, did you know the 6502
>> >> was a simply awesome bit of computing. If I recall, it was the only Asych
>> >> logic CPU on the market. Ah, how times move on.) But as people get older,
>> >> other things assume more important roles. Wife, family, social life. Time
>> >> becomes precious--too precious to be spent learning and relearning bits of
>> >> hackery.
>> >>>
>> >>> I would like to have a plugin for sbt that would do the same thing,
>> >>> maybe it is out there, but again it wouldn't be something I'd want to
>> >>> be there automatically with every project as not every project will be
>> >>> using git and stored at github, so there would have to be some amount
>> >>> of setup and config.
>> >>>
>> >>> Or do you mean something like Ruby gems where the code and
>> >>> documentation are rolled up into one easy-to-install package? The
>> >>> problem with that is maven repositories seem to be the standard way of
>> >>> hosting dependencies for the jvm. For my own projects that would mean
>> >>> any dependency not hosted in a maven friendly way would have to be
>> >>> manually included.
>> >>
>> >> I think the latter. I note the following of your implementation
>> >> (nothing to do with you)
>> >>
>> >> http://derekjw.github.com/rex/ does not exactly provide a clear path to
>> >> the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of
>> >> links deep.
>> >>
>> >> I provided a __README__ class whose only function was to serve as the
>> >> "central" document. Clicking on this produces an error. Not sure why. Maybe
>> >> the pages were too large?
>> >>>
>> >>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> >>> wrote:
>> >>>> A little bit of background:
>> >>>> I have a site on github which promises to make regular expressions
>> >>>> easier to
>> >>>> use.
>> >>>> However, I'm not a programmer, I'm a tech writer by nature.
>> >>>> After reading about gh-pages, I decided it was too complex for the
>> >>>> likes of
>> >>>> me.
>> >>>>
>> >>>> Derek has very kindly offered the following:
>> >>>> I forked your repo and added changes to pom.xml to allow you to use
>> >>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>> >>>> at: http://derekjw.github.com/rex
>> >>>>
>> >>>> Just make sure you have a settings.xml in your maven directory
>> >>>> (~/.m2/settings.xml in linux) that looks something like this:
>> >>>>
>> >>>>
>> >>>>  
>> >>>>    
>> >>>>      rexsite
>> >>>>      git
>> >>>>      /home/derek/.ssh/id_rsa
>> >>>>    
>> >>>>  
>> >>>>
>> >>>>
>> >>>> But why should users be required to have settings in their Maven
>> >>>> directory?
>> >>>> Why should they even need to know what a Maven directory is? (I
>> >>>> certainly
>> >>>> didn't want to)
>> >>>>
>> >>>> I've been in the tech writing business for a while now, and it is one
>> >>>> of the
>> >>>> most overlooked ways of getting attention to projects. People will
>> >>>> much more
>> >>>> readily read a well done document that explains the pluses and
>> >>>> minuses of
>> >>>> cases, than they will go to the trouble of dl'ing a distro, compiling
>> >>>> it,
>> >>>> running with all the attendant errors, and finally deploying it.
>> >>>> Let's make
>> >>>> sense, which is more cost effective. A well-reasoned appeal to a
>> >>>> highly
>> >>>> intelligent, but discerning, audience, or a piece of (effectively)
>> >>>> raw code.
>> >>>> So here's the gauntlet I'm throwing down. Come up with a way that
>> >>>> distributes, IN TANDEM, the documentation that accompanies a piece of
>> >>>> code,
>> >>>> an easy way of installing and reading that code, and one that doesn't
>> >>>> require complex file setups, absurd config files, etc. etc. Because I
>> >>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>> >>>> Now maybe this already exists and I just haven't seen it. But I've
>> >>>> been
>> >>>> looking for awhile...
>> >>>> Cheers,
>> >>>> Ken
>> >>>
>> >>>
>> >>>
>> >>> --
>> >>> Derek
>> >>
>> >> Thanks,
>> >> Ken
>> >>
>> >>
>>
>
>

David,

You have been incredibly helpful. What failed, effectively, was that I ended up copying the entire docs tree (up to the git root dir) over git, rather than just the docs tree itself. This is a result of my misunderstanding, not yours. I need to get to know git, so I can understand the implications of the various commands. But I really don't want to learn git to the level needed, to accomplish such an apparently simple task. Again, my bad, not yours.

I'll also comment that it's something that's frustrated me about CS for more than 20 years. Year in, year out, people are expected to learn the latest comments and commands--with hardly any emphasis on simplicity. As a counterexample to this general trend, I give you Apple--hardly my favorite company, but one that has understood that people value simplicity. Programmers are people. Does it not logically follow that programmers value simplicity?

Alas, I fear this is not the case. I've known too many programmers who value the latest features over the greatest features. Many programmers seem to have a (to me) unhealthy fascination for technology for technology's sake. They are delighted when they can demonstrate their expertise of arcane commands vs. other people. (Yes, I've seen this, over and over again.) Not always, but too often, too much ego is tied up in esoteric knowledge, not enough in simply getting the task done.

NAFTOLI:

By the way, you know that github has a button to generate a starter github pages page?

That's great. WHERE? I'm looking at my project page, and it's not obvious to me.

Thanks,
Ken

On Nov 1, 2010, at 3:43 PM, David Bernard wrote:

> Kenneth,
>
> You are a tech writer, but are you a tech reader [1] ?
> What failed with the instructions, I provided, to help you push site
> on github gh-pages (with the response I could write a better
> documentation) ?
>
> [1] http://maven.apache.org/plugins/maven-site-plugin/
>
> /davidB
>
> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim wrote:
>> By the way, you know that github has a button to generate a starter github
>> pages page?
>>
>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> wrote:
>>>
>>> Tim,
>>>
>>> Thanks for the interest. I'll take a look at it if I get a chance, but as
>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>>> inclination towards programming. I would need to do a lot of coming up to
>>> speed to be able to do that, I suspect.
>>>
>>> Basically, I like doing rather small projects, and then giving them the
>>> docs they need to be useful. Twenty years ago, I would've been in there
>>> hacking with the best (or at least most enthusiastic), but my tastes have
>>> changed over time.
>>>
>>> Cheers,
>>> Ken
>>>
>>>
>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>>>
>>>> Ken,
>>>>
>>>> Interesting discussion. Have you considered making some kind of SBT
>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>>>> plugin... it could automate the setup of the steps your originally
>>>> outlined. Just spitballing :-)
>>>>
>>>> Cheers, Tim
>>>>
>>>> On 31 October 2010 17:50, Kenneth McDonald
>>>> wrote:
>>>>>
>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>>>>>
>>>>>> Are you talking about a complete build system / web hosting setup, or
>>>>>> using an existing build system and web host?
>>>>>
>>>>> The second. Bye the way thanks for all the help!
>>>>>> As far as maven with
>>>>>> github is concerned, the setup I did for you is quite simple. I don't
>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>>>>>> familiar with how maven works but setting you up only took about 10
>>>>>> mins (I did it because I was mostly just curious to see if there was
>>>>>> something out there that would do it). The only problem I had with it
>>>>>> was that it did not automatically fall back to using my own git and
>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>>>>>> private key was.
>>>>>
>>>>> This may be minor to you. But it could be major to someone who just
>>>>> wants to write, and document, good Scala code. I've configured ssh in the
>>>>> past, so at least knew what it was, but ssh, while simple to use once you
>>>>> are in the know, is not a trivial learning curve. To paraphrase a quote from
>>>>> I don't know where, "Things should be just simple enough, and no simpler."
>>>>> In my opinion, the successful documenter should need to know the following:
>>>>> 1) The source documentation of the scaladoc (in the build tree).
>>>>> 2) The destination doc of the scaladoc (in the WWW).
>>>>> No further knowledge should be necessary. If it is, it should be
>>>>> prompted for during the installation process.
>>>>>
>>>>> I can remember the days when I used to love to catch the original
>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really were
>>>>> learning bits and bytes. Why, I almost remember the knickname I had for 6502
>>>>> register...no, no, let's not go there. Bye the way, did you know the 6502
>>>>> was a simply awesome bit of computing. If I recall, it was the only Asych
>>>>> logic CPU on the market. Ah, how times move on.) But as people get older,
>>>>> other things assume more important roles. Wife, family, social life. Time
>>>>> becomes precious--too precious to be spent learning and relearning bits of
>>>>> hackery.
>>>>>>
>>>>>> I would like to have a plugin for sbt that would do the same thing,
>>>>>> maybe it is out there, but again it wouldn't be something I'd want to
>>>>>> be there automatically with every project as not every project will be
>>>>>> using git and stored at github, so there would have to be some amount
>>>>>> of setup and config.
>>>>>>
>>>>>> Or do you mean something like Ruby gems where the code and
>>>>>> documentation are rolled up into one easy-to-install package? The
>>>>>> problem with that is maven repositories seem to be the standard way of
>>>>>> hosting dependencies for the jvm. For my own projects that would mean
>>>>>> any dependency not hosted in a maven friendly way would have to be
>>>>>> manually included.
>>>>>
>>>>> I think the latter. I note the following of your implementation
>>>>> (nothing to do with you)
>>>>>
>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear path to
>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of
>>>>> links deep.
>>>>>
>>>>> I provided a __README__ class whose only function was to serve as the
>>>>> "central" document. Clicking on this produces an error. Not sure why. Maybe
>>>>> the pages were too large?
>>>>>>
>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>>>>>> wrote:
>>>>>>> A little bit of background:
>>>>>>> I have a site on github which promises to make regular expressions
>>>>>>> easier to
>>>>>>> use.
>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>>>>>>> After reading about gh-pages, I decided it was too complex for the
>>>>>>> likes of
>>>>>>> me.
>>>>>>>
>>>>>>> Derek has very kindly offered the following:
>>>>>>> I forked your repo and added changes to pom.xml to allow you to use
>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>>>>>> at: http://derekjw.github.com/rex
>>>>>>>
>>>>>>> Just make sure you have a settings.xml in your maven directory
>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> rexsite
>>>>>>> git
>>>>>>> /home/derek/.ssh/id_rsa
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> But why should users be required to have settings in their Maven
>>>>>>> directory?
>>>>>>> Why should they even need to know what a Maven directory is? (I
>>>>>>> certainly
>>>>>>> didn't want to)
>>>>>>>
>>>>>>> I've been in the tech writing business for a while now, and it is one
>>>>>>> of the
>>>>>>> most overlooked ways of getting attention to projects. People will
>>>>>>> much more
>>>>>>> readily read a well done document that explains the pluses and
>>>>>>> minuses of
>>>>>>> cases, than they will go to the trouble of dl'ing a distro, compiling
>>>>>>> it,
>>>>>>> running with all the attendant errors, and finally deploying it.
>>>>>>> Let's make
>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>>>>>>> highly
>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>>>>>>> raw code.
>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece of
>>>>>>> code,
>>>>>>> an easy way of installing and reading that code, and one that doesn't
>>>>>>> require complex file setups, absurd config files, etc. etc. Because I
>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>>>>>>> been
>>>>>>> looking for awhile...
>>>>>>> Cheers,
>>>>>>> Ken
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Derek
>>>>>
>>>>> Thanks,
>>>>> Ken
>>>>>
>>>>>
>>>
>>
>>

On 11/01/2010 02:05 PM, Kenneth McDonald wrote:
> By the way, you know that github has a button to generate a starter github pages page?
>
> That's great. WHERE? I'm looking at my project page, and it's not obvious to me.

See http://pages.github.com/ under "Project Page Generator". It's even
got pictures. :)

It is only there before you create a gh-pages branch as an alternative.

The wiki that github offers is probably a better solution to the type of documentation you want, but I can understand the desire to keep the docs with the code. Scaladoc is a very good tool for API documentation but that isn't what you want. A Github plugin for sbt that maintained API docs as well as wiki documents might be useful.

On 2010-11-01 3:13 PM, "Kenneth McDonald" <kenneth.m.mcdonald@sbcglobal.net> wrote:
> David,
>
> You have been incredibly helpful. What failed, effectively, was that I ended up copying the entire docs tree (up to the git root dir) over git, rather than just the docs tree itself. This is a result of my misunderstanding, not yours. I need to get to know git, so I can understand the implications of the various commands. But I really don't want to learn git to the level needed, to accomplish such an apparently simple task. Again, my bad, not yours.
>
> I'll also comment that it's something that's frustrated me about CS for more than 20 years. Year in, year out, people are expected to learn the latest comments and commands--with hardly any emphasis on simplicity. As a counterexample to this general trend, I give you Apple--hardly my favorite company, but one that has understood that people value simplicity. Programmers are people. Does it not logically follow that programmers value simplicity?
>
> Alas, I fear this is not the case. I've known too many programmers who value the latest features over the greatest features. Many programmers seem to have a (to me) unhealthy fascination for technology for technology's sake. They are delighted when they can demonstrate their expertise of arcane commands vs. other people. (Yes, I've seen this, over and over again.) Not always, but too often, too much ego is tied up in esoteric knowledge, not enough in simply getting the task done.
>
> NAFTOLI:
>
> By the way, you know that github has a button to generate a starter github pages page?
>
> That's great. WHERE? I'm looking at my project page, and it's not obvious to me.
>
> Thanks,
> Ken
>
> On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>
>> Kenneth,
>>
>> You are a tech writer, but are you a tech reader [1] ?
>> What failed with the instructions, I provided, to help you push site
>> on github gh-pages (with the response I could write a better
>> documentation) ?
>>
>> [1] http://maven.apache.org/plugins/maven-site-plugin/
>>
>> /davidB
>>
>> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com> wrote:
>>> By the way, you know that github has a button to generate a starter github
>>> pages page?
>>>
>>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>
>>>> Tim,
>>>>
>>>> Thanks for the interest. I'll take a look at it if I get a chance, but as
>>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>>>> inclination towards programming. I would need to do a lot of coming up to
>>>> speed to be able to do that, I suspect.
>>>>
>>>> Basically, I like doing rather small projects, and then giving them the
>>>> docs they need to be useful. Twenty years ago, I would've been in there
>>>> hacking with the best (or at least most enthusiastic), but my tastes have
>>>> changed over time.
>>>>
>>>> Cheers,
>>>> Ken
>>>>
>>>>
>>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>>>>
>>>>> Ken,
>>>>>
>>>>> Interesting discussion. Have you considered making some kind of SBT
>>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>>>>> plugin... it could automate the setup of the steps your originally
>>>>> outlined. Just spitballing :-)
>>>>>
>>>>> Cheers, Tim
>>>>>
>>>>> On 31 October 2010 17:50, Kenneth McDonald
>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>>>
>>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>>>>>>
>>>>>>> Are you talking about a complete build system / web hosting setup, or
>>>>>>> using an existing build system and web host?
>>>>>>
>>>>>> The second. Bye the way thanks for all the help!
>>>>>>> As far as maven with
>>>>>>> github is concerned, the setup I did for you is quite simple. I don't
>>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>>>>>>> familiar with how maven works but setting you up only took about 10
>>>>>>> mins (I did it because I was mostly just curious to see if there was
>>>>>>> something out there that would do it). The only problem I had with it
>>>>>>> was that it did not automatically fall back to using my own git and
>>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>>>>>>> private key was.
>>>>>>
>>>>>> This may be minor to you. But it could be major to someone who just
>>>>>> wants to write, and document, good Scala code. I've configured ssh in the
>>>>>> past, so at least knew what it was, but ssh, while simple to use once you
>>>>>> are in the know, is not a trivial learning curve. To paraphrase a quote from
>>>>>> I don't know where, "Things should be just simple enough, and no simpler."
>>>>>> In my opinion, the successful documenter should need to know the following:
>>>>>> 1) The source documentation of the scaladoc (in the build tree).
>>>>>> 2) The destination doc of the scaladoc (in the WWW).
>>>>>> No further knowledge should be necessary. If it is, it should be
>>>>>> prompted for during the installation process.
>>>>>>
>>>>>> I can remember the days when I used to love to catch the original
>>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really were
>>>>>> learning bits and bytes. Why, I almost remember the knickname I had for 6502
>>>>>> register...no, no, let's not go there. Bye the way, did you know the 6502
>>>>>> was a simply awesome bit of computing. If I recall, it was the only Asych
>>>>>> logic CPU on the market. Ah, how times move on.) But as people get older,
>>>>>> other things assume more important roles. Wife, family, social life. Time
>>>>>> becomes precious--too precious to be spent learning and relearning bits of
>>>>>> hackery.
>>>>>>>
>>>>>>> I would like to have a plugin for sbt that would do the same thing,
>>>>>>> maybe it is out there, but again it wouldn't be something I'd want to
>>>>>>> be there automatically with every project as not every project will be
>>>>>>> using git and stored at github, so there would have to be some amount
>>>>>>> of setup and config.
>>>>>>>
>>>>>>> Or do you mean something like Ruby gems where the code and
>>>>>>> documentation are rolled up into one easy-to-install package? The
>>>>>>> problem with that is maven repositories seem to be the standard way of
>>>>>>> hosting dependencies for the jvm. For my own projects that would mean
>>>>>>> any dependency not hosted in a maven friendly way would have to be
>>>>>>> manually included.
>>>>>>
>>>>>> I think the latter. I note the following of your implementation
>>>>>> (nothing to do with you)
>>>>>>
>>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear path to
>>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of
>>>>>> links deep.
>>>>>>
>>>>>> I provided a __README__ class whose only function was to serve as the
>>>>>> "central" document. Clicking on this produces an error. Not sure why. Maybe
>>>>>> the pages were too large?
>>>>>>>
>>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>>>>> A little bit of background:
>>>>>>>> I have a site on github which promises to make regular expressions
>>>>>>>> easier to
>>>>>>>> use.
>>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>>>>>>>> After reading about gh-pages, I decided it was too complex for the
>>>>>>>> likes of
>>>>>>>> me.
>>>>>>>>
>>>>>>>> Derek has very kindly offered the following:
>>>>>>>> I forked your repo and added changes to pom.xml to allow you to use
>>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>>>>>>> at: http://derekjw.github.com/rex
>>>>>>>>
>>>>>>>> Just make sure you have a settings.xml in your maven directory
>>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>>>>>>
>>>>>>>> <settings>
>>>>>>>> <servers>
>>>>>>>> <server>
>>>>>>>> <id>rexsite</id>
>>>>>>>> <username>git</username>
>>>>>>>> <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>>>>>>>> </server>
>>>>>>>> </servers>
>>>>>>>> </settings>
>>>>>>>>
>>>>>>>> But why should users be required to have settings in their Maven
>>>>>>>> directory?
>>>>>>>> Why should they even need to know what a Maven directory is? (I
>>>>>>>> certainly
>>>>>>>> didn't want to)
>>>>>>>>
>>>>>>>> I've been in the tech writing business for a while now, and it is one
>>>>>>>> of the
>>>>>>>> most overlooked ways of getting attention to projects. People will
>>>>>>>> much more
>>>>>>>> readily read a well done document that explains the pluses and
>>>>>>>> minuses of
>>>>>>>> cases, than they will go to the trouble of dl'ing a distro, compiling
>>>>>>>> it,
>>>>>>>> running with all the attendant errors, and finally deploying it.
>>>>>>>> Let's make
>>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>>>>>>>> highly
>>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>>>>>>>> raw code.
>>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece of
>>>>>>>> code,
>>>>>>>> an easy way of installing and reading that code, and one that doesn't
>>>>>>>> require complex file setups, absurd config files, etc. etc. Because I
>>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>>>>>>>> been
>>>>>>>> looking for awhile...
>>>>>>>> Cheers,
>>>>>>>> Ken
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Derek
>>>>>>
>>>>>> Thanks,
>>>>>> Ken
>>>>>>
>>>>>>
>>>>
>>>
>>>
>

It's probably not that hard to delete the branch though...

On Mon, Nov 1, 2010 at 5:37 PM, Derek Williams <derek@nebvin.ca> wrote:

It is only there before you create a gh-pages branch as an alternative.

The wiki that github offers is probably a better solution to the type of documentation you want, but I can understand the desire to keep the docs with the code. Scaladoc is a very good tool for API documentation but that isn't what you want. A Github plugin for sbt that maintained API docs as well as wiki documents might be useful.

On 2010-11-01 3:13 PM, "Kenneth McDonald" <kenneth.m.mcdonald@sbcglobal.net> wrote:
> David,
>
> You have been incredibly helpful. What failed, effectively, was that I ended up copying the entire docs tree (up to the git root dir) over git, rather than just the docs tree itself. This is a result of my misunderstanding, not yours. I need to get to know git, so I can understand the implications of the various commands. But I really don't want to learn git to the level needed, to accomplish such an apparently simple task. Again, my bad, not yours.
>
> I'll also comment that it's something that's frustrated me about CS for more than 20 years. Year in, year out, people are expected to learn the latest comments and commands--with hardly any emphasis on simplicity. As a counterexample to this general trend, I give you Apple--hardly my favorite company, but one that has understood that people value simplicity. Programmers are people. Does it not logically follow that programmers value simplicity?
>
> Alas, I fear this is not the case. I've known too many programmers who value the latest features over the greatest features. Many programmers seem to have a (to me) unhealthy fascination for technology for technology's sake. They are delighted when they can demonstrate their expertise of arcane commands vs. other people. (Yes, I've seen this, over and over again.) Not always, but too often, too much ego is tied up in esoteric knowledge, not enough in simply getting the task done.
>
> NAFTOLI:
>
> By the way, you know that github has a button to generate a starter github pages page?
>
> That's great. WHERE? I'm looking at my project page, and it's not obvious to me.
>
> Thanks,
> Ken
>
> On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>
>> Kenneth,
>>
>> You are a tech writer, but are you a tech reader [1] ?
>> What failed with the instructions, I provided, to help you push site
>> on github gh-pages (with the response I could write a better
>> documentation) ?
>>
>> [1] http://maven.apache.org/plugins/maven-site-plugin/
>>
>> /davidB
>>
>> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com> wrote:
>>> By the way, you know that github has a button to generate a starter github
>>> pages page?
>>>
>>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>
>>>> Tim,
>>>>
>>>> Thanks for the interest. I'll take a look at it if I get a chance, but as
>>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>>>> inclination towards programming. I would need to do a lot of coming up to
>>>> speed to be able to do that, I suspect.
>>>>
>>>> Basically, I like doing rather small projects, and then giving them the
>>>> docs they need to be useful. Twenty years ago, I would've been in there
>>>> hacking with the best (or at least most enthusiastic), but my tastes have
>>>> changed over time.
>>>>
>>>> Cheers,
>>>> Ken
>>>>
>>>>
>>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>>>>
>>>>> Ken,
>>>>>
>>>>> Interesting discussion. Have you considered making some kind of SBT
>>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>>>>> plugin... it could automate the setup of the steps your originally
>>>>> outlined. Just spitballing :-)
>>>>>
>>>>> Cheers, Tim
>>>>>
>>>>> On 31 October 2010 17:50, Kenneth McDonald
>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>>>
>>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>>>>>>
>>>>>>> Are you talking about a complete build system / web hosting setup, or
>>>>>>> using an existing build system and web host?
>>>>>>
>>>>>> The second. Bye the way thanks for all the help!
>>>>>>> As far as maven with
>>>>>>> github is concerned, the setup I did for you is quite simple. I don't
>>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>>>>>>> familiar with how maven works but setting you up only took about 10
>>>>>>> mins (I did it because I was mostly just curious to see if there was
>>>>>>> something out there that would do it). The only problem I had with it
>>>>>>> was that it did not automatically fall back to using my own git and
>>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>>>>>>> private key was.
>>>>>>
>>>>>> This may be minor to you. But it could be major to someone who just
>>>>>> wants to write, and document, good Scala code. I've configured ssh in the
>>>>>> past, so at least knew what it was, but ssh, while simple to use once you
>>>>>> are in the know, is not a trivial learning curve. To paraphrase a quote from
>>>>>> I don't know where, "Things should be just simple enough, and no simpler."
>>>>>> In my opinion, the successful documenter should need to know the following:
>>>>>> 1) The source documentation of the scaladoc (in the build tree).
>>>>>> 2) The destination doc of the scaladoc (in the WWW).
>>>>>> No further knowledge should be necessary. If it is, it should be
>>>>>> prompted for during the installation process.
>>>>>>
>>>>>> I can remember the days when I used to love to catch the original
>>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really were
>>>>>> learning bits and bytes. Why, I almost remember the knickname I had for 6502
>>>>>> register...no, no, let's not go there. Bye the way, did you know the 6502
>>>>>> was a simply awesome bit of computing. If I recall, it was the only Asych
>>>>>> logic CPU on the market. Ah, how times move on.) But as people get older,
>>>>>> other things assume more important roles. Wife, family, social life. Time
>>>>>> becomes precious--too precious to be spent learning and relearning bits of
>>>>>> hackery.
>>>>>>>
>>>>>>> I would like to have a plugin for sbt that would do the same thing,
>>>>>>> maybe it is out there, but again it wouldn't be something I'd want to
>>>>>>> be there automatically with every project as not every project will be
>>>>>>> using git and stored at github, so there would have to be some amount
>>>>>>> of setup and config.
>>>>>>>
>>>>>>> Or do you mean something like Ruby gems where the code and
>>>>>>> documentation are rolled up into one easy-to-install package? The
>>>>>>> problem with that is maven repositories seem to be the standard way of
>>>>>>> hosting dependencies for the jvm. For my own projects that would mean
>>>>>>> any dependency not hosted in a maven friendly way would have to be
>>>>>>> manually included.
>>>>>>
>>>>>> I think the latter. I note the following of your implementation
>>>>>> (nothing to do with you)
>>>>>>
>>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear path to
>>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of
>>>>>> links deep.
>>>>>>
>>>>>> I provided a __README__ class whose only function was to serve as the
>>>>>> "central" document. Clicking on this produces an error. Not sure why. Maybe
>>>>>> the pages were too large?
>>>>>>>
>>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>>>>> A little bit of background:
>>>>>>>> I have a site on github which promises to make regular expressions
>>>>>>>> easier to
>>>>>>>> use.
>>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>>>>>>>> After reading about gh-pages, I decided it was too complex for the
>>>>>>>> likes of
>>>>>>>> me.
>>>>>>>>
>>>>>>>> Derek has very kindly offered the following:
>>>>>>>> I forked your repo and added changes to pom.xml to allow you to use
>>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>>>>>>> at: http://derekjw.github.com/rex
>>>>>>>>
>>>>>>>> Just make sure you have a settings.xml in your maven directory
>>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>>>>>>
>>>>>>>> <settings>
>>>>>>>> <servers>
>>>>>>>> <server>
>>>>>>>> <id>rexsite</id>
>>>>>>>> <username>git</username>
>>>>>>>> <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>>>>>>>> </server>
>>>>>>>> </servers>
>>>>>>>> </settings>
>>>>>>>>
>>>>>>>> But why should users be required to have settings in their Maven
>>>>>>>> directory?
>>>>>>>> Why should they even need to know what a Maven directory is? (I
>>>>>>>> certainly
>>>>>>>> didn't want to)
>>>>>>>>
>>>>>>>> I've been in the tech writing business for a while now, and it is one
>>>>>>>> of the
>>>>>>>> most overlooked ways of getting attention to projects. People will
>>>>>>>> much more
>>>>>>>> readily read a well done document that explains the pluses and
>>>>>>>> minuses of
>>>>>>>> cases, than they will go to the trouble of dl'ing a distro, compiling
>>>>>>>> it,
>>>>>>>> running with all the attendant errors, and finally deploying it.
>>>>>>>> Let's make
>>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>>>>>>>> highly
>>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>>>>>>>> raw code.
>>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece of
>>>>>>>> code,
>>>>>>>> an easy way of installing and reading that code, and one that doesn't
>>>>>>>> require complex file setups, absurd config files, etc. etc. Because I
>>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>>>>>>>> been
>>>>>>>> looking for awhile...
>>>>>>>> Cheers,
>>>>>>>> Ken
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Derek
>>>>>>
>>>>>> Thanks,
>>>>>> Ken
>>>>>>
>>>>>>
>>>>
>>>
>>>
>

Go to the admin screen for the repository, go to the Repository Options tab, then check GitHubPages. A popup will show, containing a button "Automatic GitHub Page Generator".

On Mon, Nov 1, 2010 at 5:05 PM, Kenneth McDonald <kenneth.m.mcdonald@sbcglobal.net> wrote:

David,

You have been incredibly helpful. What failed, effectively, was that I ended up copying the entire docs tree (up to the git root dir) over git, rather than just the docs tree itself. This is a result of my misunderstanding, not yours. I need to get to know git, so I can understand the implications of the various commands. But I really don't want to learn git to the level needed, to accomplish such an apparently simple task. Again, my bad, not yours.

I'll also comment that it's something that's frustrated me about CS for more than 20 years. Year in, year out, people are expected to learn the latest comments and commands--with hardly any emphasis on simplicity. As a counterexample to this general trend, I give you Apple--hardly my favorite company, but one that has understood that people value simplicity. Programmers are people. Does it not logically follow that programmers value simplicity?

Alas, I fear this is not the case. I've known too many programmers who value the latest features over the greatest features. Many programmers seem to have a (to me) unhealthy fascination for technology for technology's sake. They are delighted when they can demonstrate their expertise of arcane commands vs. other people. (Yes, I've seen this, over and over again.) Not always, but too often, too much ego is tied up in esoteric knowledge, not enough in simply getting the task done.

NAFTOLI:

By the way, you know that github has a button to generate a starter github pages page?

That's great. WHERE? I'm looking at my project page, and it's not obvious to me.

Thanks,
Ken

On Nov 1, 2010, at 3:43 PM, David Bernard wrote:

> Kenneth,
>
> You are a tech writer, but are you a tech reader [1] ?
> What failed with the instructions, I provided, to help you push site
> on github gh-pages (with the response I could write a better
> documentation) ?
>
> [1] http://maven.apache.org/plugins/maven-site-plugin/
>
> /davidB
>
> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com> wrote:
>> By the way, you know that github has a button to generate a starter github
>> pages page?
>>
>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>
>>> Tim,
>>>
>>> Thanks for the interest. I'll take a look at it if I get a chance, but as
>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>>> inclination towards programming. I would need to do a lot of coming up to
>>> speed to be able to do that, I suspect.
>>>
>>> Basically, I like doing rather small projects, and then giving them the
>>> docs they need to be useful. Twenty years ago, I would've been in there
>>> hacking with the best (or at least most enthusiastic), but my tastes have
>>> changed over time.
>>>
>>> Cheers,
>>> Ken
>>>
>>>
>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>>>
>>>> Ken,
>>>>
>>>> Interesting discussion. Have you considered making some kind of SBT
>>>> plugin to assist in this process?  I mean, perhaps a gh-pages
>>>> plugin... it could automate the setup of the steps your originally
>>>> outlined. Just spitballing :-)
>>>>
>>>> Cheers, Tim
>>>>
>>>> On 31 October 2010 17:50, Kenneth McDonald
>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>>
>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>>>>>
>>>>>> Are you talking about a complete build system / web hosting setup, or
>>>>>> using an existing build system and web host?
>>>>>
>>>>> The second. Bye the way thanks for all the help!
>>>>>> As far as maven with
>>>>>> github is concerned, the setup I did for you is quite simple. I don't
>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>>>>>> familiar with how maven works but setting you up only took about 10
>>>>>> mins (I did it because I was mostly just curious to see if there was
>>>>>> something out there that would do it). The only problem I had with it
>>>>>> was that it did not automatically fall back to using my own git and
>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>>>>>> private key was.
>>>>>
>>>>> This may be minor to you. But it could be major to someone who just
>>>>> wants to write, and document, good Scala code. I've configured ssh in the
>>>>> past, so at least knew what it was, but ssh, while simple to use once you
>>>>> are in the know, is not a trivial learning curve. To paraphrase a quote from
>>>>> I don't know where, "Things should be just simple enough, and no simpler."
>>>>> In my opinion, the successful documenter should need to know the following:
>>>>>        1) The source documentation of the scaladoc (in the build tree).
>>>>>        2) The destination doc of the scaladoc (in the WWW).
>>>>> No further knowledge should be necessary. If it is, it should be
>>>>> prompted for during the installation process.
>>>>>
>>>>> I can remember the days when I used to love to catch the original
>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really were
>>>>> learning bits and bytes. Why, I almost remember the knickname I had for 6502
>>>>> register...no, no, let's not go there. Bye the way, did you know the 6502
>>>>> was a simply awesome bit of computing. If I recall, it was the only Asych
>>>>> logic CPU on the market. Ah, how times move on.) But as people get older,
>>>>> other things assume more important roles. Wife, family, social life. Time
>>>>> becomes precious--too precious to be spent learning and relearning bits of
>>>>> hackery.
>>>>>>
>>>>>> I would like to have a plugin for sbt that would do the same thing,
>>>>>> maybe it is out there, but again it wouldn't be something I'd want to
>>>>>> be there automatically with every project as not every project will be
>>>>>> using git and stored at github, so there would have to be some amount
>>>>>> of setup and config.
>>>>>>
>>>>>> Or do you mean something like Ruby gems where the code and
>>>>>> documentation are rolled up into one easy-to-install package? The
>>>>>> problem with that is maven repositories seem to be the standard way of
>>>>>> hosting dependencies for the jvm. For my own projects that would mean
>>>>>> any dependency not hosted in a maven friendly way would have to be
>>>>>> manually included.
>>>>>
>>>>> I think the latter. I note the following of your implementation
>>>>> (nothing to do with you)
>>>>>
>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear path to
>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a couple of
>>>>> links deep.
>>>>>
>>>>> I provided a __README__ class whose only function was to serve as the
>>>>> "central" document. Clicking on this produces an error. Not sure why. Maybe
>>>>> the pages were too large?
>>>>>>
>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>>>>>>> A little bit of background:
>>>>>>> I have a site on github which promises to make regular expressions
>>>>>>> easier to
>>>>>>> use.
>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>>>>>>> After reading about gh-pages, I decided it was too complex for the
>>>>>>> likes of
>>>>>>> me.
>>>>>>>
>>>>>>> Derek has very kindly offered the following:
>>>>>>> I forked your repo and added changes to pom.xml to allow you to use
>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be seen
>>>>>>> at: http://derekjw.github.com/rex
>>>>>>>
>>>>>>> Just make sure you have a settings.xml in your maven directory
>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>>>>>>>
>>>>>>> <settings>
>>>>>>>  <servers>
>>>>>>>    <server>
>>>>>>>      <id>rexsite</id>
>>>>>>>      <username>git</username>
>>>>>>>      <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>>>>>>>    </server>
>>>>>>>  </servers>
>>>>>>> </settings>
>>>>>>>
>>>>>>> But why should users be required to have settings in their Maven
>>>>>>> directory?
>>>>>>> Why should they even need to know what a Maven directory is? (I
>>>>>>> certainly
>>>>>>> didn't want to)
>>>>>>>
>>>>>>> I've been in the tech writing business for a while now, and it is one
>>>>>>> of the
>>>>>>> most overlooked ways of getting attention to projects. People will
>>>>>>> much more
>>>>>>> readily read a well done document that explains the pluses and
>>>>>>> minuses of
>>>>>>> cases, than they will go to the trouble of dl'ing a distro, compiling
>>>>>>> it,
>>>>>>> running with all the attendant errors, and finally deploying it.
>>>>>>> Let's make
>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>>>>>>> highly
>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>>>>>>> raw code.
>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece of
>>>>>>> code,
>>>>>>> an easy way of installing and reading that code, and one that doesn't
>>>>>>> require complex file setups, absurd config files, etc. etc. Because I
>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>>>>>>> been
>>>>>>> looking for awhile...
>>>>>>> Cheers,
>>>>>>> Ken
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Derek
>>>>>
>>>>> Thanks,
>>>>> Ken
>>>>>
>>>>>
>>>
>>
>>

More difficult than it should be (I think it is on github's todo list to make it simpler), especially since part of the problem Ken is having is git's steep learning curve.

On 2010-11-01 3:45 PM, "Naftoli Gugenheim" <naftoligug@gmail.com> wrote:
> It's probably not that hard to delete the branch though...
>
> On Mon, Nov 1, 2010 at 5:37 PM, Derek Williams <derek@nebvin.ca> wrote:
>
>> It is only there before you create a gh-pages branch as an alternative.
>>
>> The wiki that github offers is probably a better solution to the type of
>> documentation you want, but I can understand the desire to keep the docs
>> with the code. Scaladoc is a very good tool for API documentation but that
>> isn't what you want. A Github plugin for sbt that maintained API docs as
>> well as wiki documents might be useful.
>> On 2010-11-01 3:13 PM, "Kenneth McDonald" <
>> kenneth.m.mcdonald@sbcglobal.net> wrote:
>> > David,
>> >
>> > You have been incredibly helpful. What failed, effectively, was that I
>> ended up copying the entire docs tree (up to the git root dir) over git,
>> rather than just the docs tree itself. This is a result of my
>> misunderstanding, not yours. I need to get to know git, so I can understand
>> the implications of the various commands. But I really don't want to learn
>> git to the level needed, to accomplish such an apparently simple task.
>> Again, my bad, not yours.
>> >
>> > I'll also comment that it's something that's frustrated me about CS for
>> more than 20 years. Year in, year out, people are expected to learn the
>> latest comments and commands--with hardly any emphasis on simplicity. As a
>> counterexample to this general trend, I give you Apple--hardly my favorite
>> company, but one that has understood that people value simplicity.
>> Programmers are people. Does it not logically follow that programmers value
>> simplicity?
>> >
>> > Alas, I fear this is not the case. I've known too many programmers who
>> value the latest features over the greatest features. Many programmers seem
>> to have a (to me) unhealthy fascination for technology for technology's
>> sake. They are delighted when they can demonstrate their expertise of arcane
>> commands vs. other people. (Yes, I've seen this, over and over again.) Not
>> always, but too often, too much ego is tied up in esoteric knowledge, not
>> enough in simply getting the task done.
>> >
>> > NAFTOLI:
>> >
>> > By the way, you know that github has a button to generate a starter
>> github pages page?
>> >
>> > That's great. WHERE? I'm looking at my project page, and it's not obvious
>> to me.
>> >
>> > Thanks,
>> > Ken
>> >
>> > On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>> >
>> >> Kenneth,
>> >>
>> >> You are a tech writer, but are you a tech reader [1] ?
>> >> What failed with the instructions, I provided, to help you push site
>> >> on github gh-pages (with the response I could write a better
>> >> documentation) ?
>> >>
>> >> [1] http://maven.apache.org/plugins/maven-site-plugin/
>> >>
>> >> /davidB
>> >>
>> >> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com>
>> wrote:
>> >>> By the way, you know that github has a button to generate a starter
>> github
>> >>> pages page?
>> >>>
>> >>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> >>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>
>> >>>> Tim,
>> >>>>
>> >>>> Thanks for the interest. I'll take a look at it if I get a chance, but
>> as
>> >>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>> >>>> inclination towards programming. I would need to do a lot of coming up
>> to
>> >>>> speed to be able to do that, I suspect.
>> >>>>
>> >>>> Basically, I like doing rather small projects, and then giving them
>> the
>> >>>> docs they need to be useful. Twenty years ago, I would've been in
>> there
>> >>>> hacking with the best (or at least most enthusiastic), but my tastes
>> have
>> >>>> changed over time.
>> >>>>
>> >>>> Cheers,
>> >>>> Ken
>> >>>>
>> >>>>
>> >>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>> >>>>
>> >>>>> Ken,
>> >>>>>
>> >>>>> Interesting discussion. Have you considered making some kind of SBT
>> >>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>> >>>>> plugin... it could automate the setup of the steps your originally
>> >>>>> outlined. Just spitballing :-)
>> >>>>>
>> >>>>> Cheers, Tim
>> >>>>>
>> >>>>> On 31 October 2010 17:50, Kenneth McDonald
>> >>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>
>> >>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>> >>>>>>
>> >>>>>>> Are you talking about a complete build system / web hosting setup,
>> or
>> >>>>>>> using an existing build system and web host?
>> >>>>>>
>> >>>>>> The second. Bye the way thanks for all the help!
>> >>>>>>> As far as maven with
>> >>>>>>> github is concerned, the setup I did for you is quite simple. I
>> don't
>> >>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>> >>>>>>> familiar with how maven works but setting you up only took about 10
>> >>>>>>> mins (I did it because I was mostly just curious to see if there
>> was
>> >>>>>>> something out there that would do it). The only problem I had with
>> it
>> >>>>>>> was that it did not automatically fall back to using my own git and
>> >>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>> >>>>>>> private key was.
>> >>>>>>
>> >>>>>> This may be minor to you. But it could be major to someone who just
>> >>>>>> wants to write, and document, good Scala code. I've configured ssh
>> in the
>> >>>>>> past, so at least knew what it was, but ssh, while simple to use
>> once you
>> >>>>>> are in the know, is not a trivial learning curve. To paraphrase a
>> quote from
>> >>>>>> I don't know where, "Things should be just simple enough, and no
>> simpler."
>> >>>>>> In my opinion, the successful documenter should need to know the
>> following:
>> >>>>>> 1) The source documentation of the scaladoc (in the build tree).
>> >>>>>> 2) The destination doc of the scaladoc (in the WWW).
>> >>>>>> No further knowledge should be necessary. If it is, it should be
>> >>>>>> prompted for during the installation process.
>> >>>>>>
>> >>>>>> I can remember the days when I used to love to catch the original
>> >>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really
>> were
>> >>>>>> learning bits and bytes. Why, I almost remember the knickname I had
>> for 6502
>> >>>>>> register...no, no, let's not go there. Bye the way, did you know the
>> 6502
>> >>>>>> was a simply awesome bit of computing. If I recall, it was the only
>> Asych
>> >>>>>> logic CPU on the market. Ah, how times move on.) But as people get
>> older,
>> >>>>>> other things assume more important roles. Wife, family, social life.
>> Time
>> >>>>>> becomes precious--too precious to be spent learning and relearning
>> bits of
>> >>>>>> hackery.
>> >>>>>>>
>> >>>>>>> I would like to have a plugin for sbt that would do the same thing,
>> >>>>>>> maybe it is out there, but again it wouldn't be something I'd want
>> to
>> >>>>>>> be there automatically with every project as not every project will
>> be
>> >>>>>>> using git and stored at github, so there would have to be some
>> amount
>> >>>>>>> of setup and config.
>> >>>>>>>
>> >>>>>>> Or do you mean something like Ruby gems where the code and
>> >>>>>>> documentation are rolled up into one easy-to-install package? The
>> >>>>>>> problem with that is maven repositories seem to be the standard way
>> of
>> >>>>>>> hosting dependencies for the jvm. For my own projects that would
>> mean
>> >>>>>>> any dependency not hosted in a maven friendly way would have to be
>> >>>>>>> manually included.
>> >>>>>>
>> >>>>>> I think the latter. I note the following of your implementation
>> >>>>>> (nothing to do with you)
>> >>>>>>
>> >>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear
>> path to
>> >>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a
>> couple of
>> >>>>>> links deep.
>> >>>>>>
>> >>>>>> I provided a __README__ class whose only function was to serve as
>> the
>> >>>>>> "central" document. Clicking on this produces an error. Not sure
>> why. Maybe
>> >>>>>> the pages were too large?
>> >>>>>>>
>> >>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> >>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>>> A little bit of background:
>> >>>>>>>> I have a site on github which promises to make regular expressions
>> >>>>>>>> easier to
>> >>>>>>>> use.
>> >>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>> >>>>>>>> After reading about gh-pages, I decided it was too complex for the
>> >>>>>>>> likes of
>> >>>>>>>> me.
>> >>>>>>>>
>> >>>>>>>> Derek has very kindly offered the following:
>> >>>>>>>> I forked your repo and added changes to pom.xml to allow you to
>> use
>> >>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be
>> seen
>> >>>>>>>> at: http://derekjw.github.com/rex
>> >>>>>>>>
>> >>>>>>>> Just make sure you have a settings.xml in your maven directory
>> >>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>> >>>>>>>>
>> >>>>>>>> <settings>
>> >>>>>>>> <servers>
>> >>>>>>>> <server>
>> >>>>>>>> <id>rexsite</id>
>> >>>>>>>> <username>git</username>
>> >>>>>>>> <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>> >>>>>>>> </server>
>> >>>>>>>> </servers>
>> >>>>>>>> </settings>
>> >>>>>>>>
>> >>>>>>>> But why should users be required to have settings in their Maven
>> >>>>>>>> directory?
>> >>>>>>>> Why should they even need to know what a Maven directory is? (I
>> >>>>>>>> certainly
>> >>>>>>>> didn't want to)
>> >>>>>>>>
>> >>>>>>>> I've been in the tech writing business for a while now, and it is
>> one
>> >>>>>>>> of the
>> >>>>>>>> most overlooked ways of getting attention to projects. People will
>> >>>>>>>> much more
>> >>>>>>>> readily read a well done document that explains the pluses and
>> >>>>>>>> minuses of
>> >>>>>>>> cases, than they will go to the trouble of dl'ing a distro,
>> compiling
>> >>>>>>>> it,
>> >>>>>>>> running with all the attendant errors, and finally deploying it.
>> >>>>>>>> Let's make
>> >>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>> >>>>>>>> highly
>> >>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>> >>>>>>>> raw code.
>> >>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>> >>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece
>> of
>> >>>>>>>> code,
>> >>>>>>>> an easy way of installing and reading that code, and one that
>> doesn't
>> >>>>>>>> require complex file setups, absurd config files, etc. etc.
>> Because I
>> >>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>> >>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>> >>>>>>>> been
>> >>>>>>>> looking for awhile...
>> >>>>>>>> Cheers,
>> >>>>>>>> Ken
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> --
>> >>>>>>> Derek
>> >>>>>>
>> >>>>>> Thanks,
>> >>>>>> Ken
>> >>>>>>
>> >>>>>>
>> >>>>
>> >>>
>> >>>
>> >
>>

Right but I was just saying it might be simpler to delete the branch, have github automatically create and initialize it, and then go from there...

On Mon, Nov 1, 2010 at 5:56 PM, Derek Williams <derek@nebvin.ca> wrote:

More difficult than it should be (I think it is on github's todo list to make it simpler), especially since part of the problem Ken is having is git's steep learning curve.

On 2010-11-01 3:45 PM, "Naftoli Gugenheim" <naftoligug@gmail.com> wrote:
> It's probably not that hard to delete the branch though...
>
> On Mon, Nov 1, 2010 at 5:37 PM, Derek Williams <derek@nebvin.ca> wrote:
>
>> It is only there before you create a gh-pages branch as an alternative.
>>
>> The wiki that github offers is probably a better solution to the type of
>> documentation you want, but I can understand the desire to keep the docs
>> with the code. Scaladoc is a very good tool for API documentation but that
>> isn't what you want. A Github plugin for sbt that maintained API docs as
>> well as wiki documents might be useful.
>> On 2010-11-01 3:13 PM, "Kenneth McDonald" <
>> kenneth.m.mcdonald@sbcglobal.net> wrote:
>> > David,
>> >
>> > You have been incredibly helpful. What failed, effectively, was that I
>> ended up copying the entire docs tree (up to the git root dir) over git,
>> rather than just the docs tree itself. This is a result of my
>> misunderstanding, not yours. I need to get to know git, so I can understand
>> the implications of the various commands. But I really don't want to learn
>> git to the level needed, to accomplish such an apparently simple task.
>> Again, my bad, not yours.
>> >
>> > I'll also comment that it's something that's frustrated me about CS for
>> more than 20 years. Year in, year out, people are expected to learn the
>> latest comments and commands--with hardly any emphasis on simplicity. As a
>> counterexample to this general trend, I give you Apple--hardly my favorite
>> company, but one that has understood that people value simplicity.
>> Programmers are people. Does it not logically follow that programmers value
>> simplicity?
>> >
>> > Alas, I fear this is not the case. I've known too many programmers who
>> value the latest features over the greatest features. Many programmers seem
>> to have a (to me) unhealthy fascination for technology for technology's
>> sake. They are delighted when they can demonstrate their expertise of arcane
>> commands vs. other people. (Yes, I've seen this, over and over again.) Not
>> always, but too often, too much ego is tied up in esoteric knowledge, not
>> enough in simply getting the task done.
>> >
>> > NAFTOLI:
>> >
>> > By the way, you know that github has a button to generate a starter
>> github pages page?
>> >
>> > That's great. WHERE? I'm looking at my project page, and it's not obvious
>> to me.
>> >
>> > Thanks,
>> > Ken
>> >
>> > On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>> >
>> >> Kenneth,
>> >>
>> >> You are a tech writer, but are you a tech reader [1] ?
>> >> What failed with the instructions, I provided, to help you push site
>> >> on github gh-pages (with the response I could write a better
>> >> documentation) ?
>> >>
>> >> [1] http://maven.apache.org/plugins/maven-site-plugin/
>> >>
>> >> /davidB
>> >>
>> >> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com>
>> wrote:
>> >>> By the way, you know that github has a button to generate a starter
>> github
>> >>> pages page?
>> >>>
>> >>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> >>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>
>> >>>> Tim,
>> >>>>
>> >>>> Thanks for the interest. I'll take a look at it if I get a chance, but
>> as
>> >>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>> >>>> inclination towards programming. I would need to do a lot of coming up
>> to
>> >>>> speed to be able to do that, I suspect.
>> >>>>
>> >>>> Basically, I like doing rather small projects, and then giving them
>> the
>> >>>> docs they need to be useful. Twenty years ago, I would've been in
>> there
>> >>>> hacking with the best (or at least most enthusiastic), but my tastes
>> have
>> >>>> changed over time.
>> >>>>
>> >>>> Cheers,
>> >>>> Ken
>> >>>>
>> >>>>
>> >>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>> >>>>
>> >>>>> Ken,
>> >>>>>
>> >>>>> Interesting discussion. Have you considered making some kind of SBT
>> >>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>> >>>>> plugin... it could automate the setup of the steps your originally
>> >>>>> outlined. Just spitballing :-)
>> >>>>>
>> >>>>> Cheers, Tim
>> >>>>>
>> >>>>> On 31 October 2010 17:50, Kenneth McDonald
>> >>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>
>> >>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>> >>>>>>
>> >>>>>>> Are you talking about a complete build system / web hosting setup,
>> or
>> >>>>>>> using an existing build system and web host?
>> >>>>>>
>> >>>>>> The second. Bye the way thanks for all the help!
>> >>>>>>> As far as maven with
>> >>>>>>> github is concerned, the setup I did for you is quite simple. I
>> don't
>> >>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>> >>>>>>> familiar with how maven works but setting you up only took about 10
>> >>>>>>> mins (I did it because I was mostly just curious to see if there
>> was
>> >>>>>>> something out there that would do it). The only problem I had with
>> it
>> >>>>>>> was that it did not automatically fall back to using my own git and
>> >>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>> >>>>>>> private key was.
>> >>>>>>
>> >>>>>> This may be minor to you. But it could be major to someone who just
>> >>>>>> wants to write, and document, good Scala code. I've configured ssh
>> in the
>> >>>>>> past, so at least knew what it was, but ssh, while simple to use
>> once you
>> >>>>>> are in the know, is not a trivial learning curve. To paraphrase a
>> quote from
>> >>>>>> I don't know where, "Things should be just simple enough, and no
>> simpler."
>> >>>>>> In my opinion, the successful documenter should need to know the
>> following:
>> >>>>>> 1) The source documentation of the scaladoc (in the build tree).
>> >>>>>> 2) The destination doc of the scaladoc (in the WWW).
>> >>>>>> No further knowledge should be necessary. If it is, it should be
>> >>>>>> prompted for during the installation process.
>> >>>>>>
>> >>>>>> I can remember the days when I used to love to catch the original
>> >>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really
>> were
>> >>>>>> learning bits and bytes. Why, I almost remember the knickname I had
>> for 6502
>> >>>>>> register...no, no, let's not go there. Bye the way, did you know the
>> 6502
>> >>>>>> was a simply awesome bit of computing. If I recall, it was the only
>> Asych
>> >>>>>> logic CPU on the market. Ah, how times move on.) But as people get
>> older,
>> >>>>>> other things assume more important roles. Wife, family, social life.
>> Time
>> >>>>>> becomes precious--too precious to be spent learning and relearning
>> bits of
>> >>>>>> hackery.
>> >>>>>>>
>> >>>>>>> I would like to have a plugin for sbt that would do the same thing,
>> >>>>>>> maybe it is out there, but again it wouldn't be something I'd want
>> to
>> >>>>>>> be there automatically with every project as not every project will
>> be
>> >>>>>>> using git and stored at github, so there would have to be some
>> amount
>> >>>>>>> of setup and config.
>> >>>>>>>
>> >>>>>>> Or do you mean something like Ruby gems where the code and
>> >>>>>>> documentation are rolled up into one easy-to-install package? The
>> >>>>>>> problem with that is maven repositories seem to be the standard way
>> of
>> >>>>>>> hosting dependencies for the jvm. For my own projects that would
>> mean
>> >>>>>>> any dependency not hosted in a maven friendly way would have to be
>> >>>>>>> manually included.
>> >>>>>>
>> >>>>>> I think the latter. I note the following of your implementation
>> >>>>>> (nothing to do with you)
>> >>>>>>
>> >>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear
>> path to
>> >>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a
>> couple of
>> >>>>>> links deep.
>> >>>>>>
>> >>>>>> I provided a __README__ class whose only function was to serve as
>> the
>> >>>>>> "central" document. Clicking on this produces an error. Not sure
>> why. Maybe
>> >>>>>> the pages were too large?
>> >>>>>>>
>> >>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> >>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>>> A little bit of background:
>> >>>>>>>> I have a site on github which promises to make regular expressions
>> >>>>>>>> easier to
>> >>>>>>>> use.
>> >>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>> >>>>>>>> After reading about gh-pages, I decided it was too complex for the
>> >>>>>>>> likes of
>> >>>>>>>> me.
>> >>>>>>>>
>> >>>>>>>> Derek has very kindly offered the following:
>> >>>>>>>> I forked your repo and added changes to pom.xml to allow you to
>> use
>> >>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be
>> seen
>> >>>>>>>> at: http://derekjw.github.com/rex
>> >>>>>>>>
>> >>>>>>>> Just make sure you have a settings.xml in your maven directory
>> >>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>> >>>>>>>>
>> >>>>>>>> <settings>
>> >>>>>>>> <servers>
>> >>>>>>>> <server>
>> >>>>>>>> <id>rexsite</id>
>> >>>>>>>> <username>git</username>
>> >>>>>>>> <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>> >>>>>>>> </server>
>> >>>>>>>> </servers>
>> >>>>>>>> </settings>
>> >>>>>>>>
>> >>>>>>>> But why should users be required to have settings in their Maven
>> >>>>>>>> directory?
>> >>>>>>>> Why should they even need to know what a Maven directory is? (I
>> >>>>>>>> certainly
>> >>>>>>>> didn't want to)
>> >>>>>>>>
>> >>>>>>>> I've been in the tech writing business for a while now, and it is
>> one
>> >>>>>>>> of the
>> >>>>>>>> most overlooked ways of getting attention to projects. People will
>> >>>>>>>> much more
>> >>>>>>>> readily read a well done document that explains the pluses and
>> >>>>>>>> minuses of
>> >>>>>>>> cases, than they will go to the trouble of dl'ing a distro,
>> compiling
>> >>>>>>>> it,
>> >>>>>>>> running with all the attendant errors, and finally deploying it.
>> >>>>>>>> Let's make
>> >>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>> >>>>>>>> highly
>> >>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>> >>>>>>>> raw code.
>> >>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>> >>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece
>> of
>> >>>>>>>> code,
>> >>>>>>>> an easy way of installing and reading that code, and one that
>> doesn't
>> >>>>>>>> require complex file setups, absurd config files, etc. etc.
>> Because I
>> >>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>> >>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>> >>>>>>>> been
>> >>>>>>>> looking for awhile...
>> >>>>>>>> Cheers,
>> >>>>>>>> Ken
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> --
>> >>>>>>> Derek
>> >>>>>>
>> >>>>>> Thanks,
>> >>>>>> Ken
>> >>>>>>
>> >>>>>>
>> >>>>
>> >>>
>> >>>
>> >
>>

One of the problems with CS knowledge is that it isn't durable. Back when I was young and deeply into this stuff, I could quote you chapter and verse on the advantages/disadvantages of the COSMAC 1802 CPU over the Motorola 6502. (The COSMAC was pretty neat, by the way.) What use is that knowledge now? Nada. Whereas if I'd been a doctor, sure, I would've had to keep up on things--but for the most part, my established knowledge base _wouldn't_ have become worthless.
IIRC, there is a paragraph in Clifford Stoll's "Silicon Snake Oil" to the effect that if you learn to bake brownies, you know how to bake them for life. But if you learn the newest technology...
One final comment (because I realize this is getting rantish). However, back when I was an undergrad, the nroff/troff technologies were the cat's pyjamas in typesetting. You could write entire theses in them. The syntax was easy, though it did make for text that got broken up into short snippets, rather than more readable sentences. But that was minor, and easily adapted to.
Now, twenty years later, we have a plethora of markup languages, all supposed to make text markup "easier". And I can't see a single advantage that has been gained from all that work. In fact, I see distinct disadvantages. nroff/troff were (IIRC) semantically unambiguos. Because they relied on a very simple convention ("." at the start of a line signals a command) there was no confusion between markup and literals. (I don't remember how a literal . at the beginning of a line was indicated, but it was probably something like "..".) Now, try to write the literal "^" in scaladoc. And that's an important literal, it's used in regexes amongst other places!
Call me a dinosaur, but I just don't get how abandoning useful technologies, for other no more useful technologies, can possibly be a plus.
A caveat: In spite of my limited understanding of source code control systems, I realize there have been major advances in that area. I'm not criticizing all or even most areas of CS. I am saying that CS in general is all too willing to adopt the new and untried, rather than sticking with the tried and true. (Rather like stockpicking actually.)
Cheers,Ken

On Nov 1, 2010, at 5:06 PM, Naftoli Gugenheim wrote:

Right but I was just saying it might be simpler to delete the branch, have github automatically create and initialize it, and then go from there...

On Mon, Nov 1, 2010 at 5:56 PM, Derek Williams <derek@nebvin.ca> wrote:

More difficult than it should be (I think it is on github's todo list to make it simpler), especially since part of the problem Ken is having is git's steep learning curve.

On 2010-11-01 3:45 PM, "Naftoli Gugenheim" <naftoligug@gmail.com> wrote:
> It's probably not that hard to delete the branch though...
>
> On Mon, Nov 1, 2010 at 5:37 PM, Derek Williams <derek@nebvin.ca> wrote:
>
>> It is only there before you create a gh-pages branch as an alternative.
>>
>> The wiki that github offers is probably a better solution to the type of
>> documentation you want, but I can understand the desire to keep the docs
>> with the code. Scaladoc is a very good tool for API documentation but that
>> isn't what you want. A Github plugin for sbt that maintained API docs as
>> well as wiki documents might be useful.
>> On 2010-11-01 3:13 PM, "Kenneth McDonald" <
>> kenneth.m.mcdonald@sbcglobal.net> wrote:
>> > David,
>> >
>> > You have been incredibly helpful. What failed, effectively, was that I
>> ended up copying the entire docs tree (up to the git root dir) over git,
>> rather than just the docs tree itself. This is a result of my
>> misunderstanding, not yours. I need to get to know git, so I can understand
>> the implications of the various commands. But I really don't want to learn
>> git to the level needed, to accomplish such an apparently simple task.
>> Again, my bad, not yours.
>> >
>> > I'll also comment that it's something that's frustrated me about CS for
>> more than 20 years. Year in, year out, people are expected to learn the
>> latest comments and commands--with hardly any emphasis on simplicity. As a
>> counterexample to this general trend, I give you Apple--hardly my favorite
>> company, but one that has understood that people value simplicity.
>> Programmers are people. Does it not logically follow that programmers value
>> simplicity?
>> >
>> > Alas, I fear this is not the case. I've known too many programmers who
>> value the latest features over the greatest features. Many programmers seem
>> to have a (to me) unhealthy fascination for technology for technology's
>> sake. They are delighted when they can demonstrate their expertise of arcane
>> commands vs. other people. (Yes, I've seen this, over and over again.) Not
>> always, but too often, too much ego is tied up in esoteric knowledge, not
>> enough in simply getting the task done.
>> >
>> > NAFTOLI:
>> >
>> > By the way, you know that github has a button to generate a starter
>> github pages page?
>> >
>> > That's great. WHERE? I'm looking at my project page, and it's not obvious
>> to me.
>> >
>> > Thanks,
>> > Ken
>> >
>> > On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>> >
>> >> Kenneth,
>> >>
>> >> You are a tech writer, but are you a tech reader [1] ?
>> >> What failed with the instructions, I provided, to help you push site
>> >> on github gh-pages (with the response I could write a better
>> >> documentation) ?
>> >>
>> >> [1] http://maven.apache.org/plugins/maven-site-plugin/
>> >>
>> >> /davidB
>> >>
>> >> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com>
>> wrote:
>> >>> By the way, you know that github has a button to generate a starter
>> github
>> >>> pages page?
>> >>>
>> >>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> >>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>
>> >>>> Tim,
>> >>>>
>> >>>> Thanks for the interest. I'll take a look at it if I get a chance, but
>> as
>> >>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>> >>>> inclination towards programming. I would need to do a lot of coming up
>> to
>> >>>> speed to be able to do that, I suspect.
>> >>>>
>> >>>> Basically, I like doing rather small projects, and then giving them
>> the
>> >>>> docs they need to be useful. Twenty years ago, I would've been in
>> there
>> >>>> hacking with the best (or at least most enthusiastic), but my tastes
>> have
>> >>>> changed over time.
>> >>>>
>> >>>> Cheers,
>> >>>> Ken
>> >>>>
>> >>>>
>> >>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>> >>>>
>> >>>>> Ken,
>> >>>>>
>> >>>>> Interesting discussion. Have you considered making some kind of SBT
>> >>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>> >>>>> plugin... it could automate the setup of the steps your originally
>> >>>>> outlined. Just spitballing :-)
>> >>>>>
>> >>>>> Cheers, Tim
>> >>>>>
>> >>>>> On 31 October 2010 17:50, Kenneth McDonald
>> >>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>
>> >>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>> >>>>>>
>> >>>>>>> Are you talking about a complete build system / web hosting setup,
>> or
>> >>>>>>> using an existing build system and web host?
>> >>>>>>
>> >>>>>> The second. Bye the way thanks for all the help!
>> >>>>>>> As far as maven with
>> >>>>>>> github is concerned, the setup I did for you is quite simple. I
>> don't
>> >>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>> >>>>>>> familiar with how maven works but setting you up only took about 10
>> >>>>>>> mins (I did it because I was mostly just curious to see if there
>> was
>> >>>>>>> something out there that would do it). The only problem I had with
>> it
>> >>>>>>> was that it did not automatically fall back to using my own git and
>> >>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>> >>>>>>> private key was.
>> >>>>>>
>> >>>>>> This may be minor to you. But it could be major to someone who just
>> >>>>>> wants to write, and document, good Scala code. I've configured ssh
>> in the
>> >>>>>> past, so at least knew what it was, but ssh, while simple to use
>> once you
>> >>>>>> are in the know, is not a trivial learning curve. To paraphrase a
>> quote from
>> >>>>>> I don't know where, "Things should be just simple enough, and no
>> simpler."
>> >>>>>> In my opinion, the successful documenter should need to know the
>> following:
>> >>>>>> 1) The source documentation of the scaladoc (in the build tree).
>> >>>>>> 2) The destination doc of the scaladoc (in the WWW).
>> >>>>>> No further knowledge should be necessary. If it is, it should be
>> >>>>>> prompted for during the installation process.
>> >>>>>>
>> >>>>>> I can remember the days when I used to love to catch the original
>> >>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really
>> were
>> >>>>>> learning bits and bytes. Why, I almost remember the knickname I had
>> for 6502
>> >>>>>> register...no, no, let's not go there. Bye the way, did you know the
>> 6502
>> >>>>>> was a simply awesome bit of computing. If I recall, it was the only
>> Asych
>> >>>>>> logic CPU on the market. Ah, how times move on.) But as people get
>> older,
>> >>>>>> other things assume more important roles. Wife, family, social life.
>> Time
>> >>>>>> becomes precious--too precious to be spent learning and relearning
>> bits of
>> >>>>>> hackery.
>> >>>>>>>
>> >>>>>>> I would like to have a plugin for sbt that would do the same thing,
>> >>>>>>> maybe it is out there, but again it wouldn't be something I'd want
>> to
>> >>>>>>> be there automatically with every project as not every project will
>> be
>> >>>>>>> using git and stored at github, so there would have to be some
>> amount
>> >>>>>>> of setup and config.
>> >>>>>>>
>> >>>>>>> Or do you mean something like Ruby gems where the code and
>> >>>>>>> documentation are rolled up into one easy-to-install package? The
>> >>>>>>> problem with that is maven repositories seem to be the standard way
>> of
>> >>>>>>> hosting dependencies for the jvm. For my own projects that would
>> mean
>> >>>>>>> any dependency not hosted in a maven friendly way would have to be
>> >>>>>>> manually included.
>> >>>>>>
>> >>>>>> I think the latter. I note the following of your implementation
>> >>>>>> (nothing to do with you)
>> >>>>>>
>> >>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear
>> path to
>> >>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a
>> couple of
>> >>>>>> links deep.
>> >>>>>>
>> >>>>>> I provided a __README__ class whose only function was to serve as
>> the
>> >>>>>> "central" document. Clicking on this produces an error. Not sure
>> why. Maybe
>> >>>>>> the pages were too large?
>> >>>>>>>
>> >>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> >>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>>> A little bit of background:
>> >>>>>>>> I have a site on github which promises to make regular expressions
>> >>>>>>>> easier to
>> >>>>>>>> use.
>> >>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>> >>>>>>>> After reading about gh-pages, I decided it was too complex for the
>> >>>>>>>> likes of
>> >>>>>>>> me.
>> >>>>>>>>
>> >>>>>>>> Derek has very kindly offered the following:
>> >>>>>>>> I forked your repo and added changes to pom.xml to allow you to
>> use
>> >>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be
>> seen
>> >>>>>>>> at: http://derekjw.github.com/rex
>> >>>>>>>>
>> >>>>>>>> Just make sure you have a settings.xml in your maven directory
>> >>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>> >>>>>>>>
>> >>>>>>>> <settings>
>> >>>>>>>> <servers>
>> >>>>>>>> <server>
>> >>>>>>>> <id>rexsite</id>
>> >>>>>>>> <username>git</username>
>> >>>>>>>> <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>> >>>>>>>> </server>
>> >>>>>>>> </servers>
>> >>>>>>>> </settings>
>> >>>>>>>>
>> >>>>>>>> But why should users be required to have settings in their Maven
>> >>>>>>>> directory?
>> >>>>>>>> Why should they even need to know what a Maven directory is? (I
>> >>>>>>>> certainly
>> >>>>>>>> didn't want to)
>> >>>>>>>>
>> >>>>>>>> I've been in the tech writing business for a while now, and it is
>> one
>> >>>>>>>> of the
>> >>>>>>>> most overlooked ways of getting attention to projects. People will
>> >>>>>>>> much more
>> >>>>>>>> readily read a well done document that explains the pluses and
>> >>>>>>>> minuses of
>> >>>>>>>> cases, than they will go to the trouble of dl'ing a distro,
>> compiling
>> >>>>>>>> it,
>> >>>>>>>> running with all the attendant errors, and finally deploying it.
>> >>>>>>>> Let's make
>> >>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>> >>>>>>>> highly
>> >>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>> >>>>>>>> raw code.
>> >>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>> >>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece
>> of
>> >>>>>>>> code,
>> >>>>>>>> an easy way of installing and reading that code, and one that
>> doesn't
>> >>>>>>>> require complex file setups, absurd config files, etc. etc.
>> Because I
>> >>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>> >>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>> >>>>>>>> been
>> >>>>>>>> looking for awhile...
>> >>>>>>>> Cheers,
>> >>>>>>>> Ken
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> --
>> >>>>>>> Derek
>> >>>>>>
>> >>>>>> Thanks,
>> >>>>>> Ken
>> >>>>>>
>> >>>>>>
>> >>>>
>> >>>
>> >>>
>> >
>>

One thing that a lot of projects need is better documentation and the
people to write it. Your thoughts on your experiences with Scala is
valuable.

On Mon, Nov 1, 2010 at 4:38 PM, Kenneth McDonald
wrote:
> One of the problems with CS knowledge is that it isn't durable. Back when I
> was young and deeply into this stuff, I could quote you chapter and verse on
> the advantages/disadvantages of the COSMAC 1802 CPU over the Motorola 6502.
> (The COSMAC was pretty neat, by the way.) What use is that knowledge now?
> Nada. Whereas if I'd been a doctor, sure, I would've had to keep up on
> things--but for the most part, my established knowledge base _wouldn't_ have
> become worthless.
> IIRC, there is a paragraph in Clifford Stoll's "Silicon Snake Oil" to the
> effect that if you learn to bake brownies, you know how to bake them for
> life. But if you learn the newest technology...
> One final comment (because I realize this is getting rantish). However, back
> when I was an undergrad, the nroff/troff technologies were the cat's pyjamas
> in typesetting. You could write entire theses in them. The syntax was easy,
> though it did make for text that got broken up into short snippets, rather
> than more readable sentences. But that was minor, and easily adapted to.
> Now, twenty years later, we have a plethora of markup languages, all
> supposed to make text markup "easier". And I can't see a single advantage
> that has been gained from all that work. In fact, I see distinct
> disadvantages. nroff/troff were (IIRC) semantically unambiguos. Because they
> relied on a very simple convention ("." at the start of a line signals a
> command) there was no confusion between markup and literals. (I don't
> remember how a literal . at the beginning of a line was indicated, but it
> was probably something like "..".) Now, try to write the literal "^" in
> scaladoc. And that's an important literal, it's used in regexes amongst
> other places!
> Call me a dinosaur, but I just don't get how abandoning useful technologies,
> for other no more useful technologies, can possibly be a plus.
> A caveat: In spite of my limited understanding of source code control
> systems, I realize there have been major advances in that area. I'm not
> criticizing all or even most areas of CS. I am saying that CS in general is
> all too willing to adopt the new and untried, rather than sticking with the
> tried and true. (Rather like stockpicking actually.)
> Cheers,
> Ken
>
> On Nov 1, 2010, at 5:06 PM, Naftoli Gugenheim wrote:
>
> Right but I was just saying it might be simpler to delete the branch, have
> github automatically create and initialize it, and then go from there...
>
> On Mon, Nov 1, 2010 at 5:56 PM, Derek Williams wrote:
>>
>> More difficult than it should be (I think it is on github's todo list to
>> make it simpler), especially since part of the problem Ken is having is
>> git's steep learning curve.
>>
>> On 2010-11-01 3:45 PM, "Naftoli Gugenheim" wrote:
>> > It's probably not that hard to delete the branch though...
>> >
>> > On Mon, Nov 1, 2010 at 5:37 PM, Derek Williams wrote:
>> >
>> >> It is only there before you create a gh-pages branch as an alternative.
>> >>
>> >> The wiki that github offers is probably a better solution to the type
>> >> of
>> >> documentation you want, but I can understand the desire to keep the
>> >> docs
>> >> with the code. Scaladoc is a very good tool for API documentation but
>> >> that
>> >> isn't what you want. A Github plugin for sbt that maintained API docs
>> >> as
>> >> well as wiki documents might be useful.
>> >> On 2010-11-01 3:13 PM, "Kenneth McDonald" <
>> >> kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >> > David,
>> >> >
>> >> > You have been incredibly helpful. What failed, effectively, was that
>> >> > I
>> >> ended up copying the entire docs tree (up to the git root dir) over
>> >> git,
>> >> rather than just the docs tree itself. This is a result of my
>> >> misunderstanding, not yours. I need to get to know git, so I can
>> >> understand
>> >> the implications of the various commands. But I really don't want to
>> >> learn
>> >> git to the level needed, to accomplish such an apparently simple task.
>> >> Again, my bad, not yours.
>> >> >
>> >> > I'll also comment that it's something that's frustrated me about CS
>> >> > for
>> >> more than 20 years. Year in, year out, people are expected to learn the
>> >> latest comments and commands--with hardly any emphasis on simplicity.
>> >> As a
>> >> counterexample to this general trend, I give you Apple--hardly my
>> >> favorite
>> >> company, but one that has understood that people value simplicity.
>> >> Programmers are people. Does it not logically follow that programmers
>> >> value
>> >> simplicity?
>> >> >
>> >> > Alas, I fear this is not the case. I've known too many programmers
>> >> > who
>> >> value the latest features over the greatest features. Many programmers
>> >> seem
>> >> to have a (to me) unhealthy fascination for technology for technology's
>> >> sake. They are delighted when they can demonstrate their expertise of
>> >> arcane
>> >> commands vs. other people. (Yes, I've seen this, over and over again.)
>> >> Not
>> >> always, but too often, too much ego is tied up in esoteric knowledge,
>> >> not
>> >> enough in simply getting the task done.
>> >> >
>> >> > NAFTOLI:
>> >> >
>> >> > By the way, you know that github has a button to generate a starter
>> >> github pages page?
>> >> >
>> >> > That's great. WHERE? I'm looking at my project page, and it's not
>> >> > obvious
>> >> to me.
>> >> >
>> >> > Thanks,
>> >> > Ken
>> >> >
>> >> > On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>> >> >
>> >> >> Kenneth,
>> >> >>
>> >> >> You are a tech writer, but are you a tech reader [1] ?
>> >> >> What failed with the instructions, I provided, to help you push site
>> >> >> on github gh-pages (with the response I could write a better
>> >> >> documentation) ?
>> >> >>
>> >> >> [1] http://maven.apache.org/plugins/maven-site-plugin/
>> >> >>
>> >> >> /davidB
>> >> >>
>> >> >> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim
>> >> >>
>> >> wrote:
>> >> >>> By the way, you know that github has a button to generate a starter
>> >> github
>> >> >>> pages page?
>> >> >>>
>> >> >>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> >> >>> wrote:
>> >> >>>>
>> >> >>>> Tim,
>> >> >>>>
>> >> >>>> Thanks for the interest. I'll take a look at it if I get a chance,
>> >> >>>> but
>> >> as
>> >> >>>> I've mentioned, I'm really not a programmer, I'm a tech writer
>> >> >>>> with an
>> >> >>>> inclination towards programming. I would need to do a lot of
>> >> >>>> coming up
>> >> to
>> >> >>>> speed to be able to do that, I suspect.
>> >> >>>>
>> >> >>>> Basically, I like doing rather small projects, and then giving
>> >> >>>> them
>> >> the
>> >> >>>> docs they need to be useful. Twenty years ago, I would've been in
>> >> there
>> >> >>>> hacking with the best (or at least most enthusiastic), but my
>> >> >>>> tastes
>> >> have
>> >> >>>> changed over time.
>> >> >>>>
>> >> >>>> Cheers,
>> >> >>>> Ken
>> >> >>>>
>> >> >>>>
>> >> >>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>> >> >>>>
>> >> >>>>> Ken,
>> >> >>>>>
>> >> >>>>> Interesting discussion. Have you considered making some kind of
>> >> >>>>> SBT
>> >> >>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>> >> >>>>> plugin... it could automate the setup of the steps your
>> >> >>>>> originally
>> >> >>>>> outlined. Just spitballing :-)
>> >> >>>>>
>> >> >>>>> Cheers, Tim
>> >> >>>>>
>> >> >>>>> On 31 October 2010 17:50, Kenneth McDonald
>> >> >>>>> wrote:
>> >> >>>>>>
>> >> >>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>> >> >>>>>>
>> >> >>>>>>> Are you talking about a complete build system / web hosting
>> >> >>>>>>> setup,
>> >> or
>> >> >>>>>>> using an existing build system and web host?
>> >> >>>>>>
>> >> >>>>>> The second. Bye the way thanks for all the help!
>> >> >>>>>>> As far as maven with
>> >> >>>>>>> github is concerned, the setup I did for you is quite simple. I
>> >> don't
>> >> >>>>>>> use maven at all, I use sbt for all my projects, so I am not
>> >> >>>>>>> that
>> >> >>>>>>> familiar with how maven works but setting you up only took
>> >> >>>>>>> about 10
>> >> >>>>>>> mins (I did it because I was mostly just curious to see if
>> >> >>>>>>> there
>> >> was
>> >> >>>>>>> something out there that would do it). The only problem I had
>> >> >>>>>>> with
>> >> it
>> >> >>>>>>> was that it did not automatically fall back to using my own git
>> >> >>>>>>> and
>> >> >>>>>>> ssh config, requiring a settings.xml file that defined where my
>> >> >>>>>>> ssh
>> >> >>>>>>> private key was.
>> >> >>>>>>
>> >> >>>>>> This may be minor to you. But it could be major to someone who
>> >> >>>>>> just
>> >> >>>>>> wants to write, and document, good Scala code. I've configured
>> >> >>>>>> ssh
>> >> in the
>> >> >>>>>> past, so at least knew what it was, but ssh, while simple to use
>> >> once you
>> >> >>>>>> are in the know, is not a trivial learning curve. To paraphrase
>> >> >>>>>> a
>> >> quote from
>> >> >>>>>> I don't know where, "Things should be just simple enough, and no
>> >> simpler."
>> >> >>>>>> In my opinion, the successful documenter should need to know the
>> >> following:
>> >> >>>>>> 1) The source documentation of the scaladoc (in the build tree).
>> >> >>>>>> 2) The destination doc of the scaladoc (in the WWW).
>> >> >>>>>> No further knowledge should be necessary. If it is, it should be
>> >> >>>>>> prompted for during the installation process.
>> >> >>>>>>
>> >> >>>>>> I can remember the days when I used to love to catch the
>> >> >>>>>> original
>> >> >>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we
>> >> >>>>>> really
>> >> were
>> >> >>>>>> learning bits and bytes. Why, I almost remember the knickname I
>> >> >>>>>> had
>> >> for 6502
>> >> >>>>>> register...no, no, let's not go there. Bye the way, did you know
>> >> >>>>>> the
>> >> 6502
>> >> >>>>>> was a simply awesome bit of computing. If I recall, it was the
>> >> >>>>>> only
>> >> Asych
>> >> >>>>>> logic CPU on the market. Ah, how times move on.) But as people
>> >> >>>>>> get
>> >> older,
>> >> >>>>>> other things assume more important roles. Wife, family, social
>> >> >>>>>> life.
>> >> Time
>> >> >>>>>> becomes precious--too precious to be spent learning and
>> >> >>>>>> relearning
>> >> bits of
>> >> >>>>>> hackery.
>> >> >>>>>>>
>> >> >>>>>>> I would like to have a plugin for sbt that would do the same
>> >> >>>>>>> thing,
>> >> >>>>>>> maybe it is out there, but again it wouldn't be something I'd
>> >> >>>>>>> want
>> >> to
>> >> >>>>>>> be there automatically with every project as not every project
>> >> >>>>>>> will
>> >> be
>> >> >>>>>>> using git and stored at github, so there would have to be some
>> >> amount
>> >> >>>>>>> of setup and config.
>> >> >>>>>>>
>> >> >>>>>>> Or do you mean something like Ruby gems where the code and
>> >> >>>>>>> documentation are rolled up into one easy-to-install package?
>> >> >>>>>>> The
>> >> >>>>>>> problem with that is maven repositories seem to be the standard
>> >> >>>>>>> way
>> >> of
>> >> >>>>>>> hosting dependencies for the jvm. For my own projects that
>> >> >>>>>>> would
>> >> mean
>> >> >>>>>>> any dependency not hosted in a maven friendly way would have to
>> >> >>>>>>> be
>> >> >>>>>>> manually included.
>> >> >>>>>>
>> >> >>>>>> I think the latter. I note the following of your implementation
>> >> >>>>>> (nothing to do with you)
>> >> >>>>>>
>> >> >>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear
>> >> path to
>> >> >>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a
>> >> couple of
>> >> >>>>>> links deep.
>> >> >>>>>>
>> >> >>>>>> I provided a __README__ class whose only function was to serve
>> >> >>>>>> as
>> >> the
>> >> >>>>>> "central" document. Clicking on this produces an error. Not sure
>> >> why. Maybe
>> >> >>>>>> the pages were too large?
>> >> >>>>>>>
>> >> >>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> >> >>>>>>> wrote:
>> >> >>>>>>>> A little bit of background:
>> >> >>>>>>>> I have a site on github which promises to make regular
>> >> >>>>>>>> expressions
>> >> >>>>>>>> easier to
>> >> >>>>>>>> use.
>> >> >>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>> >> >>>>>>>> After reading about gh-pages, I decided it was too complex for
>> >> >>>>>>>> the
>> >> >>>>>>>> likes of
>> >> >>>>>>>> me.
>> >> >>>>>>>>
>> >> >>>>>>>> Derek has very kindly offered the following:
>> >> >>>>>>>> I forked your repo and added changes to pom.xml to allow you
>> >> >>>>>>>> to
>> >> use
>> >> >>>>>>>> wagon-gitsite to auto publish. Tested it and the results can
>> >> >>>>>>>> be
>> >> seen
>> >> >>>>>>>> at: http://derekjw.github.com/rex
>> >> >>>>>>>>
>> >> >>>>>>>> Just make sure you have a settings.xml in your maven directory
>> >> >>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>> >> >>>>>>>>
>> >> >>>>>>>>
>> >> >>>>>>>>
>> >> >>>>>>>>
>> >> >>>>>>>> rexsite
>> >> >>>>>>>> git
>> >> >>>>>>>> /home/derek/.ssh/id_rsa
>> >> >>>>>>>>
>> >> >>>>>>>>
>> >> >>>>>>>>
>> >> >>>>>>>>
>> >> >>>>>>>> But why should users be required to have settings in their
>> >> >>>>>>>> Maven
>> >> >>>>>>>> directory?
>> >> >>>>>>>> Why should they even need to know what a Maven directory is?
>> >> >>>>>>>> (I
>> >> >>>>>>>> certainly
>> >> >>>>>>>> didn't want to)
>> >> >>>>>>>>
>> >> >>>>>>>> I've been in the tech writing business for a while now, and it
>> >> >>>>>>>> is
>> >> one
>> >> >>>>>>>> of the
>> >> >>>>>>>> most overlooked ways of getting attention to projects. People
>> >> >>>>>>>> will
>> >> >>>>>>>> much more
>> >> >>>>>>>> readily read a well done document that explains the pluses and
>> >> >>>>>>>> minuses of
>> >> >>>>>>>> cases, than they will go to the trouble of dl'ing a distro,
>> >> compiling
>> >> >>>>>>>> it,
>> >> >>>>>>>> running with all the attendant errors, and finally deploying
>> >> >>>>>>>> it.
>> >> >>>>>>>> Let's make
>> >> >>>>>>>> sense, which is more cost effective. A well-reasoned appeal to
>> >> >>>>>>>> a
>> >> >>>>>>>> highly
>> >> >>>>>>>> intelligent, but discerning, audience, or a piece of
>> >> >>>>>>>> (effectively)
>> >> >>>>>>>> raw code.
>> >> >>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way
>> >> >>>>>>>> that
>> >> >>>>>>>> distributes, IN TANDEM, the documentation that accompanies a
>> >> >>>>>>>> piece
>> >> of
>> >> >>>>>>>> code,
>> >> >>>>>>>> an easy way of installing and reading that code, and one that
>> >> doesn't
>> >> >>>>>>>> require complex file setups, absurd config files, etc. etc.
>> >> Because I
>> >> >>>>>>>> guarantee you, if you can do that, you'll get a lot more
>> >> >>>>>>>> eyeballs.
>> >> >>>>>>>> Now maybe this already exists and I just haven't seen it. But
>> >> >>>>>>>> I've
>> >> >>>>>>>> been
>> >> >>>>>>>> looking for awhile...
>> >> >>>>>>>> Cheers,
>> >> >>>>>>>> Ken
>> >> >>>>>>>
>> >> >>>>>>>
>> >> >>>>>>>
>> >> >>>>>>> --
>> >> >>>>>>> Derek
>> >> >>>>>>
>> >> >>>>>> Thanks,
>> >> >>>>>> Ken
>> >> >>>>>>
>> >> >>>>>>
>> >> >>>>
>> >> >>>
>> >> >>>
>> >> >
>> >>
>
>
>

I don't think knowledge of specific technologies really counts as computer science.  CS knowledge is extremely durable...it just often is very marketable by itself.
I believe Alan Kay calls the phenomenon you're describing "reinventing the flat tire," and yes the technology industry loves to do it.
But a lot of this is subjective.  For example, IMHO git is extremely complicated.  Too complicated for me to want to use.  But I think the complexity comes from the fact that it models the way large scale distributed version control really should work.  It fits it like a glove.  It's a complex solution to a complex problem.
Mercurial, on the other hand, pastes over a lot of that complexity, which makes the learning curve much friendlier.  So I generally use Mercurial, because I don't have any need for large scale distributed version control.
Anyway, there's a lot of tools that are worth it if you have the problems they solve that are absolutely abominable (especially to learn) if you don't have those problems.  To make matters worse, a lot of people assume that everyone has more-or-less the same problems they do, and there are a lot of people on this list (and other lists and forums) who really do have complex problems.
On Mon, Nov 1, 2010 at 6:38 PM, Kenneth McDonald <kenneth.m.mcdonald@sbcglobal.net> wrote:

One of the problems with CS knowledge is that it isn't durable. Back when I was young and deeply into this stuff, I could quote you chapter and verse on the advantages/disadvantages of the COSMAC 1802 CPU over the Motorola 6502. (The COSMAC was pretty neat, by the way.) What use is that knowledge now? Nada. Whereas if I'd been a doctor, sure, I would've had to keep up on things--but for the most part, my established knowledge base _wouldn't_ have become worthless.
IIRC, there is a paragraph in Clifford Stoll's "Silicon Snake Oil" to the effect that if you learn to bake brownies, you know how to bake them for life. But if you learn the newest technology...
One final comment (because I realize this is getting rantish). However, back when I was an undergrad, the nroff/troff technologies were the cat's pyjamas in typesetting. You could write entire theses in them. The syntax was easy, though it did make for text that got broken up into short snippets, rather than more readable sentences. But that was minor, and easily adapted to.
Now, twenty years later, we have a plethora of markup languages, all supposed to make text markup "easier". And I can't see a single advantage that has been gained from all that work. In fact, I see distinct disadvantages. nroff/troff were (IIRC) semantically unambiguos. Because they relied on a very simple convention ("." at the start of a line signals a command) there was no confusion between markup and literals. (I don't remember how a literal . at the beginning of a line was indicated, but it was probably something like "..".) Now, try to write the literal "^" in scaladoc. And that's an important literal, it's used in regexes amongst other places!
Call me a dinosaur, but I just don't get how abandoning useful technologies, for other no more useful technologies, can possibly be a plus.
A caveat: In spite of my limited understanding of source code control systems, I realize there have been major advances in that area. I'm not criticizing all or even most areas of CS. I am saying that CS in general is all too willing to adopt the new and untried, rather than sticking with the tried and true. (Rather like stockpicking actually.)
Cheers,Ken

On Nov 1, 2010, at 5:06 PM, Naftoli Gugenheim wrote:

Right but I was just saying it might be simpler to delete the branch, have github automatically create and initialize it, and then go from there...

On Mon, Nov 1, 2010 at 5:56 PM, Derek Williams <derek@nebvin.ca> wrote:

More difficult than it should be (I think it is on github's todo list to make it simpler), especially since part of the problem Ken is having is git's steep learning curve.

On 2010-11-01 3:45 PM, "Naftoli Gugenheim" <naftoligug@gmail.com> wrote:
> It's probably not that hard to delete the branch though...
>
> On Mon, Nov 1, 2010 at 5:37 PM, Derek Williams <derek@nebvin.ca> wrote:
>
>> It is only there before you create a gh-pages branch as an alternative.
>>
>> The wiki that github offers is probably a better solution to the type of
>> documentation you want, but I can understand the desire to keep the docs
>> with the code. Scaladoc is a very good tool for API documentation but that
>> isn't what you want. A Github plugin for sbt that maintained API docs as
>> well as wiki documents might be useful.
>> On 2010-11-01 3:13 PM, "Kenneth McDonald" <
>> kenneth.m.mcdonald@sbcglobal.net> wrote:
>> > David,
>> >
>> > You have been incredibly helpful. What failed, effectively, was that I
>> ended up copying the entire docs tree (up to the git root dir) over git,
>> rather than just the docs tree itself. This is a result of my
>> misunderstanding, not yours. I need to get to know git, so I can understand
>> the implications of the various commands. But I really don't want to learn
>> git to the level needed, to accomplish such an apparently simple task.
>> Again, my bad, not yours.
>> >
>> > I'll also comment that it's something that's frustrated me about CS for
>> more than 20 years. Year in, year out, people are expected to learn the
>> latest comments and commands--with hardly any emphasis on simplicity. As a
>> counterexample to this general trend, I give you Apple--hardly my favorite
>> company, but one that has understood that people value simplicity.
>> Programmers are people. Does it not logically follow that programmers value
>> simplicity?
>> >
>> > Alas, I fear this is not the case. I've known too many programmers who
>> value the latest features over the greatest features. Many programmers seem
>> to have a (to me) unhealthy fascination for technology for technology's
>> sake. They are delighted when they can demonstrate their expertise of arcane
>> commands vs. other people. (Yes, I've seen this, over and over again.) Not
>> always, but too often, too much ego is tied up in esoteric knowledge, not
>> enough in simply getting the task done.
>> >
>> > NAFTOLI:
>> >
>> > By the way, you know that github has a button to generate a starter
>> github pages page?
>> >
>> > That's great. WHERE? I'm looking at my project page, and it's not obvious
>> to me.
>> >
>> > Thanks,
>> > Ken
>> >
>> > On Nov 1, 2010, at 3:43 PM, David Bernard wrote:
>> >
>> >> Kenneth,
>> >>
>> >> You are a tech writer, but are you a tech reader [1] ?
>> >> What failed with the instructions, I provided, to help you push site
>> >> on github gh-pages (with the response I could write a better
>> >> documentation) ?
>> >>
>> >> [1] http://maven.apache.org/plugins/maven-site-plugin/
>> >>
>> >> /davidB
>> >>
>> >> On Mon, Nov 1, 2010 at 21:27, Naftoli Gugenheim <naftoligug@gmail.com>
>> wrote:
>> >>> By the way, you know that github has a button to generate a starter
>> github
>> >>> pages page?
>> >>>
>> >>> On Mon, Nov 1, 2010 at 12:57 PM, Kenneth McDonald
>> >>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>
>> >>>> Tim,
>> >>>>
>> >>>> Thanks for the interest. I'll take a look at it if I get a chance, but
>> as
>> >>>> I've mentioned, I'm really not a programmer, I'm a tech writer with an
>> >>>> inclination towards programming. I would need to do a lot of coming up
>> to
>> >>>> speed to be able to do that, I suspect.
>> >>>>
>> >>>> Basically, I like doing rather small projects, and then giving them
>> the
>> >>>> docs they need to be useful. Twenty years ago, I would've been in
>> there
>> >>>> hacking with the best (or at least most enthusiastic), but my tastes
>> have
>> >>>> changed over time.
>> >>>>
>> >>>> Cheers,
>> >>>> Ken
>> >>>>
>> >>>>
>> >>>> On Oct 31, 2010, at 2:56 PM, Tim Perrett wrote:
>> >>>>
>> >>>>> Ken,
>> >>>>>
>> >>>>> Interesting discussion. Have you considered making some kind of SBT
>> >>>>> plugin to assist in this process? I mean, perhaps a gh-pages
>> >>>>> plugin... it could automate the setup of the steps your originally
>> >>>>> outlined. Just spitballing :-)
>> >>>>>
>> >>>>> Cheers, Tim
>> >>>>>
>> >>>>> On 31 October 2010 17:50, Kenneth McDonald
>> >>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>
>> >>>>>> On Oct 30, 2010, at 4:54 PM, Derek Williams wrote:
>> >>>>>>
>> >>>>>>> Are you talking about a complete build system / web hosting setup,
>> or
>> >>>>>>> using an existing build system and web host?
>> >>>>>>
>> >>>>>> The second. Bye the way thanks for all the help!
>> >>>>>>> As far as maven with
>> >>>>>>> github is concerned, the setup I did for you is quite simple. I
>> don't
>> >>>>>>> use maven at all, I use sbt for all my projects, so I am not that
>> >>>>>>> familiar with how maven works but setting you up only took about 10
>> >>>>>>> mins (I did it because I was mostly just curious to see if there
>> was
>> >>>>>>> something out there that would do it). The only problem I had with
>> it
>> >>>>>>> was that it did not automatically fall back to using my own git and
>> >>>>>>> ssh config, requiring a settings.xml file that defined where my ssh
>> >>>>>>> private key was.
>> >>>>>>
>> >>>>>> This may be minor to you. But it could be major to someone who just
>> >>>>>> wants to write, and document, good Scala code. I've configured ssh
>> in the
>> >>>>>> past, so at least knew what it was, but ssh, while simple to use
>> once you
>> >>>>>> are in the know, is not a trivial learning curve. To paraphrase a
>> quote from
>> >>>>>> I don't know where, "Things should be just simple enough, and no
>> simpler."
>> >>>>>> In my opinion, the successful documenter should need to know the
>> following:
>> >>>>>> 1) The source documentation of the scaladoc (in the build tree).
>> >>>>>> 2) The destination doc of the scaladoc (in the WWW).
>> >>>>>> No further knowledge should be necessary. If it is, it should be
>> >>>>>> prompted for during the installation process.
>> >>>>>>
>> >>>>>> I can remember the days when I used to love to catch the original
>> >>>>>> knowledge of bits and bytes. (Yep, kids, in those days, we really
>> were
>> >>>>>> learning bits and bytes. Why, I almost remember the knickname I had
>> for 6502
>> >>>>>> register...no, no, let's not go there. Bye the way, did you know the
>> 6502
>> >>>>>> was a simply awesome bit of computing. If I recall, it was the only
>> Asych
>> >>>>>> logic CPU on the market. Ah, how times move on.) But as people get
>> older,
>> >>>>>> other things assume more important roles. Wife, family, social life.
>> Time
>> >>>>>> becomes precious--too precious to be spent learning and relearning
>> bits of
>> >>>>>> hackery.
>> >>>>>>>
>> >>>>>>> I would like to have a plugin for sbt that would do the same thing,
>> >>>>>>> maybe it is out there, but again it wouldn't be something I'd want
>> to
>> >>>>>>> be there automatically with every project as not every project will
>> be
>> >>>>>>> using git and stored at github, so there would have to be some
>> amount
>> >>>>>>> of setup and config.
>> >>>>>>>
>> >>>>>>> Or do you mean something like Ruby gems where the code and
>> >>>>>>> documentation are rolled up into one easy-to-install package? The
>> >>>>>>> problem with that is maven repositories seem to be the standard way
>> of
>> >>>>>>> hosting dependencies for the jvm. For my own projects that would
>> mean
>> >>>>>>> any dependency not hosted in a maven friendly way would have to be
>> >>>>>>> manually included.
>> >>>>>>
>> >>>>>> I think the latter. I note the following of your implementation
>> >>>>>> (nothing to do with you)
>> >>>>>>
>> >>>>>> http://derekjw.github.com/rex/ does not exactly provide a clear
>> path to
>> >>>>>> the docs. People, docs are CRUCIAL. They shouldn't be buried a
>> couple of
>> >>>>>> links deep.
>> >>>>>>
>> >>>>>> I provided a __README__ class whose only function was to serve as
>> the
>> >>>>>> "central" document. Clicking on this produces an error. Not sure
>> why. Maybe
>> >>>>>> the pages were too large?
>> >>>>>>>
>> >>>>>>> On Sat, Oct 30, 2010 at 1:24 PM, Kenneth McDonald
>> >>>>>>> <kenneth.m.mcdonald@sbcglobal.net> wrote:
>> >>>>>>>> A little bit of background:
>> >>>>>>>> I have a site on github which promises to make regular expressions
>> >>>>>>>> easier to
>> >>>>>>>> use.
>> >>>>>>>> However, I'm not a programmer, I'm a tech writer by nature.
>> >>>>>>>> After reading about gh-pages, I decided it was too complex for the
>> >>>>>>>> likes of
>> >>>>>>>> me.
>> >>>>>>>>
>> >>>>>>>> Derek has very kindly offered the following:
>> >>>>>>>> I forked your repo and added changes to pom.xml to allow you to
>> use
>> >>>>>>>> wagon-gitsite to auto publish. Tested it and the results can be
>> seen
>> >>>>>>>> at: http://derekjw.github.com/rex
>> >>>>>>>>
>> >>>>>>>> Just make sure you have a settings.xml in your maven directory
>> >>>>>>>> (~/.m2/settings.xml in linux) that looks something like this:
>> >>>>>>>>
>> >>>>>>>> <settings>
>> >>>>>>>> <servers>
>> >>>>>>>> <server>
>> >>>>>>>> <id>rexsite</id>
>> >>>>>>>> <username>git</username>
>> >>>>>>>> <privateKey>/home/derek/.ssh/id_rsa</privateKey>
>> >>>>>>>> </server>
>> >>>>>>>> </servers>
>> >>>>>>>> </settings>
>> >>>>>>>>
>> >>>>>>>> But why should users be required to have settings in their Maven
>> >>>>>>>> directory?
>> >>>>>>>> Why should they even need to know what a Maven directory is? (I
>> >>>>>>>> certainly
>> >>>>>>>> didn't want to)
>> >>>>>>>>
>> >>>>>>>> I've been in the tech writing business for a while now, and it is
>> one
>> >>>>>>>> of the
>> >>>>>>>> most overlooked ways of getting attention to projects. People will
>> >>>>>>>> much more
>> >>>>>>>> readily read a well done document that explains the pluses and
>> >>>>>>>> minuses of
>> >>>>>>>> cases, than they will go to the trouble of dl'ing a distro,
>> compiling
>> >>>>>>>> it,
>> >>>>>>>> running with all the attendant errors, and finally deploying it.
>> >>>>>>>> Let's make
>> >>>>>>>> sense, which is more cost effective. A well-reasoned appeal to a
>> >>>>>>>> highly
>> >>>>>>>> intelligent, but discerning, audience, or a piece of (effectively)
>> >>>>>>>> raw code.
>> >>>>>>>> So here's the gauntlet I'm throwing down. Come up with a way that
>> >>>>>>>> distributes, IN TANDEM, the documentation that accompanies a piece
>> of
>> >>>>>>>> code,
>> >>>>>>>> an easy way of installing and reading that code, and one that
>> doesn't
>> >>>>>>>> require complex file setups, absurd config files, etc. etc.
>> Because I
>> >>>>>>>> guarantee you, if you can do that, you'll get a lot more eyeballs.
>> >>>>>>>> Now maybe this already exists and I just haven't seen it. But I've
>> >>>>>>>> been
>> >>>>>>>> looking for awhile...
>> >>>>>>>> Cheers,
>> >>>>>>>> Ken
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>
>> >>>>>>> --
>> >>>>>>> Derek
>> >>>>>>
>> >>>>>> Thanks,
>> >>>>>> Ken
>> >>>>>>
>> >>>>>>
>> >>>>
>> >>>
>> >>>
>> >
>>

--
http://erikengbrecht.blogspot.com/

On Nov 2, 2010, at 5:56 PM, Erik Engbrecht wrote:

I don't think knowledge of specific technologies really counts as computer science.  CS knowledge is extremely durable...it just often is very marketable by itself.
I believe Alan Kay calls the phenomenon you're describing "reinventing the flat tire," and yes the technology industry loves to do it.

The canonical example of this is the whole XML, XSLT, etc technology stack. Take the angle brackets, replace with parenthesis, and poof you have Lisp. The entire XML industry could have been done in 10 minutes if folks had had an ounce of understanding of CS and it's history. Ditto for Ruby and Python -- Smalltalk with slightly different syntax. etc, etc, etc.
The problem is that the IT industry isn't about CS, it's about selling stuff. The commercial aspects of it distort the simple CS and software engineering practice. The money involved probably makes this unavoidable.
graham

On Wed, Nov 3, 2010 at 1:56 AM, Erik Engbrecht wrote:
> But a lot of this is subjective.  For example, IMHO git is extremely
> complicated.  Too complicated for me to want to use.  But I think the
> complexity comes from the fact that it models the way large scale
> distributed version control really should work.  It fits it like a glove.
>  It's a complex solution to a complex problem.

Actually, it's not. It is the most simple and straight-forward
solution to this hard problem. It applies a tiny bit of OOP to the
basic mantra of immutable data and that's it. It's just that on top of
that simplistic solution a monster of a user interface grew which only
slowly converges to the point of a well-rounded, user-friendly system.
But perhaps that's what you said. Or you are just irritated by all
those git evangelists. I won't blame you on that one.

I think you're describing the same phenomena from a different observation point.  I don't see anything I disagree with, but you're certainly not using the words I would have selected.  The English language is a funny thing.
How's this: Using git made me a better Mercurial user.

git evangelists ceased annoying my quite a while ago.  But people who assume complex requirements when none are stated or even implied, and then either push solutions to them or advocate being concerned with them rather than addressing the problem at hand, annoy me quite a bit.


On Wed, Nov 3, 2010 at 4:17 AM, Johannes Rudolph <johannes.rudolph@googlemail.com> wrote:

On Wed, Nov 3, 2010 at 1:56 AM, Erik Engbrecht <erik.engbrecht@gmail.com> wrote:
> But a lot of this is subjective.  For example, IMHO git is extremely
> complicated.  Too complicated for me to want to use.  But I think the
> complexity comes from the fact that it models the way large scale
> distributed version control really should work.  It fits it like a glove.
>  It's a complex solution to a complex problem.

Actually, it's not. It is the most simple and straight-forward
solution to this hard problem. It applies a tiny bit of OOP to the
basic mantra of immutable data and that's it. It's just that on top of
that simplistic solution a monster of a user interface grew which only
slowly converges to the point of a well-rounded, user-friendly system.
But perhaps that's what you said. Or you are just irritated by all
those git  evangelists. I won't blame you on that one.

--
Johannes

-----------------------------------------------
Johannes Rudolph
http://virtual-void.net

--
http://erikengbrecht.blogspot.com/

If this wasn't a common problem then "Do The Simplest Thing That Could
Possibly Work" wouldn't be needed and we wouldn't need coaches to
remind us of it.

On Wed, Nov 3, 2010 at 6:40 AM, Erik Engbrecht wrote:
>
> But people who assume
> complex requirements when none are stated or even implied, and then either
> push solutions to them or advocate being concerned with them rather than
> addressing the problem at hand, annoy me quite a bit.