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-rphTv4pjVZMJGwgDXS7ZQA@public.gmane.org> 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-rphTv4pjVZMJGwgDXS7ZQA@public.gmane.org> 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
>>
>>
RSS Feed