Developer documentation

[James Kilford]

I'm writing to canvass your opinions on the developer documentation for Railo Server.  

I'm just starting to write the documentation for Railo and I'd value your input on what should go into it (or be left out of it).  At this point, I'd like to sketch out the "table of contents", in its entirety, and then fill in the detail afterwards, rather than start writing haphazardly.

You can see my ideas for the documentation on Railo's github: 

https://github.com/getrailo/railo/wiki/Documentation-structure

Please let me know if you have any ideas or comments. 

The biggest section is likely to be "Developing applications with Railo Server"... and I'd really like to find out how you think this should go.  Are you interested in: 

* sample apps

* tutorials

* design patterns

* explanation of all Railo Server's language features

* enhancing Railo Server

* editors / IDEs

* integrating Railo Server with other products, e.g. search engines, message queues

* something else?

Let me know what else you'd like to see in this section... All opinions welcome!

On the other hand, perhaps you think it should be very lightweight and that people should use ACF documentation in general, with Railo Server documentation covering the Railo-Server-specific matters only.  

Many thanks, 

James

[Igal Sapir]

+2 for the initiative!

--
typos, misspels, and other weird words brought to you courtesy of my mobile device and its auto-(in)correct feature.

--
Need help right now? Why not have one of the Railo Team help you directly: http://www.getrailo.com/index.cfm/consulting/
---
You received this message because you are subscribed to the Google Groups "Railo" group.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Billy Cravens]

Go deep on the admin. I'd make it a stand alone chapter, as I think the subject is more than a subtopic under "Manage Railo Server apps". As a matter of fact, the very structure of the admin (Server/Web) speaks to the idea that there's app-specific admins, and server-wide. I think this is the biggest area of confusion for most developers coming from ACF.

Detailed section on various installation methods:

- local Express version

- installer

- WAR deployment

- JAR deployment

This needs some detailed explanation as you get some subtle differences in directory structure and behavior based on the method. As this is mostly a Java deployment concern, and not necessarily specific to Railo in many cases, maybe some some background on how Java deployment works would build a nice foundation for understanding. 

Tangential to installation is installation of external libraries (such as MongoDB or AWS SDK). Based on installation method, it can be a bit tricky identifying where specifically to place external JAR files.

I wouldn't tackle sample apps, design patterns, specific external integrations, etc. I think the surface area for that sort of thing is far too great.

The focus should be on ACF devs coming to Railo, rather than newbies to CFML. That seems the more likely scenario.

Billy Cravens
bdcr...@gmail.com

[Mark Drew]

I would disagree with just ACF -> railo. We have a lot of new users that I don't want to say "go look at ACF". 

Regards

Mark Drew

Sent from a mobile device

[James Kilford]

Thanks Billy, appreciate the feedback.  I've updated the ToC.  Couldn't agree more with the web / server admins.  That was an area that vexed me at first when I started using Railo Server.  

Like you, I thought that most people coming to Railo Server would be previous ACF users.  However, I understand that's not the case, so I'm thinking some of that stuff might be useful.  It would be great if we can let people know that Railo Server can do all the stuff that their [insert favourite language here] can do.  So, I've added a section for comparisons with other languages and CF servers.

As for the sample apps, perhaps I was over-egging the pudding there.  Maybe "exemplar code" would be a better way of helping people along -- templates / CFCs that are a reflection of the current best practices say?

Many thanks, 

James

[Cameron Childress]

On Fri, Mar 22, 2013 at 11:33 AM, James Kilford <nkil...@gmail.com> wrote:

Like you, I thought that most people coming to Railo Server would be previous ACF users.  However, I understand that's not the case

I would not point to the ACF docs in lieu of writing Railo documentation, but I do think that pointing out the differences between Railo and ACF (where they exist) is helpful and important. This could be done inline as a callout box, or all at once in a predictable location (foot of page?). This could be done within the context of version differences between Railo editions as well.

I assume this will be written as a Github Wiki in the long term? It would be fantastic to have the ability to edit/contribute to the docs as needed. One of the weak points of ACF's docs are that, even though it has a commenting mechanism, corrections made in the comments rarely make their way into the actual body of the documentation content.

-Cameron 

--
Cameron Childress
--
p:   678.637.5072

im: cameroncf

facebook | twitter | google+

[Jean Moniatte]

Hello,

Nice, thanks for your efforts!

I think that it would be helpful to have generic "How Tos", for loops, http calls, ftp sessions etc... For example loops are much better in Railo yet it is difficult to find information about them. I am not sure how such articles would fit into your structure.

As well, a tag/function reference by category? I find it super useful in the ACF docs.

Thanks again,

Jean

--

Jean Moniatte

UGAL

je...@ugal.com

http://www.ugal.com

[Matt Quackenbush]

+1 to Cameron's thoughts.

Also, a HUGE THANK YOU for the initiative!

[Billy Cravens]

I didn't so much mean to point to ACF docs and punt on general usage, but rather, I'd focus on the unique aspects of Railo first. This makes the docs usable sooner rather than later, as I feel the mass majority of folks reading it would have little use for a general CFML tutorial. After you've finished the Railo specific pieces, then move on to general CFML. (in other words, I'm commenting more on the when than the what)

Billy Cravens
bdcr...@gmail.com

[Mark Drew]

ONe of the projects I like to use for a lot of the "what is this CFML language and how does it work" are from the CFML in a 100 minutes by Mike Henke:

https://github.com/mhenke/CFML-in-100-minutes

Then I think there are the CFML Koans if you want to look at best practice:

http://bittersweetryan.github.com/ColdFusion-Koans/

Both are under the Creative Commons attribution license, so we can get them into the documentation and modify as we see fit to get that area filled out. 

There is a bunch of herding of the existing documentation that can be done into this structure. The "differences of railo" to me, make no sense in a way. You should learn Railo and work with that. At least that is what I want the documentation to be. 

With regards of differences between Railo x.y and ACF x.y I think it's a fools errand and would help a few people for a short time compared to using James' time more wisely. 

So you know, we have hired James to do this work, hence I would prefer it to be a bit focused. 

Sincerely

Mark Drew

The Railo Company
Professional Open Source
skype: mark_railo ma...@getrailo.com
+44 7971 852296 http://www.getrailo.com

[Jean Moniatte]

+1 to the constant comparison with ACF. I agree that it should be avoided.

And thanks to Railo for putting resources behind the documentation project!

Jean

--

Jean Moniatte

UGAL

je...@ugal.com

http://www.ugal.com

[Billy Cravens]

The fact that he's writing the documentation for Railo, supporting the company's goals, certainly shifts perspective. I suppose it all depends on the goal of the docs. Is it to help those already using the language? Is it to provide an on-ramp for those choosing Railo vis-a-vis Python, Ruby, etc? Is it to provide a comprehensive source for those that write CFML apps in many engines? 

I know as I look at different languages or APIs or whatnot for projects, I quickly look for a "Documentation" link and whatever I find behind that link tells me a lot about the viability of the product. In many ways documentation becomes a marketing tool (even open source projects market themselves)

Billy Cravens
bdcr...@gmail.com

[Billy Cravens]

Wholehearted agreement on the kudos for Railo getting behind the documentation.

As to constant comparison to ACF, that sounds good, but when ACF 11's feature set is announced, let's see if none of those new features are implemented shortly in Railo. :-) Then there's the marketing materials ("Railo CFML is free, so you can spend your money on building your applications, not buying costly server licenses." "Railo has good compatibility with other CFML engines.") I think those comparisons are great, and correct, and appropriate. Certainly, while ACF isn't referenced by name, it's implicit. What was the last function or tag implemented uniquely by OpenBD that found it's way into Railo? Again, no problem, it makes sense to stay in lock step with ACF given market share in the CFML space. But let's not act as if that's not happening, or have a disconnect between the marketing and developer relations side of things.

That said, let me apologize: my intention wasn't to hijack the thread. I was simply trying to relate how I feel documentation would best serve developers needing it, and from my view (CF since 1999, CFUG manager (technically "sponsored" by Adobe,) and someone who develops in many languages) I see most developers that use Railo going ACF -> Railo.

Billy Cravens
bdcr...@gmail.com

[Mark Drew]

The fact that he's writing the documentation for Railo, supporting the company's goals, certainly shifts perspective.

How so? We are investing in someone to provide documentation for the project. 

I suppose it all depends on the goal of the docs.

Is it to help those already using the language? 

Of course

Is it to provide an on-ramp for those choosing Railo vis-a-vis Python, Ruby, etc? 

I think the goal is to get people using Railo effectively. Whether you have just started out or have some experience already. Our project is NOT the same as others and we need to document how it works, not simply how it differs. 

Is it to provide a comprehensive source for those that write CFML apps in many engines? 

Not sure why we would be writing this? how is this of benefit to Railo Server or The Railo Company? (I mean this from an amount of effort point of view) 

I know as I look at different languages or APIs or whatnot for projects, I quickly look for a "Documentation" link and whatever I find behind that link tells me a lot about the viability of the product. In many ways documentation becomes a marketing tool (even open source projects market themselves)

You are right and hence this has been a bug bear for a long time that I for one have spent a lot of my time on and now we are hopefully getting James on board to help us create better documentation for our project. 

In the end I would like the documentation to support Dan. Dan is a student that has just left Leeds University and wants to create the next awesome web site. He will learn the language, be able to deploy it, become a better developer even though he already knows some Java and some C++ from his courses. 

I want the documentation to help Halbert. He has been developing applications for years, day in, day out in Boring Co. and knows five tags but wants to stop "working for the man" and do his own thing, he wants to get better at his coding to make stuff work. 

I want it to be good for Sandra, who has AWESOME design skills uses LESS and SASS to make front ends that you would die for and knows that by using some languages that are similar to her own she can kick ass. She doesn't want to write her own damn server with node.js

I want it to be good for Delray. He is an über developer of glory at his company and wants his servers to fly. He is a coding GOD and the company has even hired a junior developer to JUST get Delray coffee. He knows his interfaces from his WSDL, he knows his extends and his MVC and makes Sean Corfield look like a nincompoop. But dammit, why are there two admins? 

Make sense?

MD 

P.S. all these people are fictional… and if they seem like people we know? They might not be at all. 

[Cameron Childress]

On Fri, Mar 22, 2013 at 12:42 PM, Mark Drew <ma...@getrailo.com> wrote:

With regards of differences between Railo x.y and ACF x.y I think it's a fools errand and would help a few people for a short time compared to using James' time more wisely. 

As someone who has clients on ACF 7, 9, and 10 as well as clients on Railo, I would find documentation of the differences to be extraordinarily valuable. However, I recognize that I may not represent all or even most of Railo's developer base.

If spending time on calling out such differences is not a high priority right now, that's fair. But people are likely to keep asking for it so perhaps these sorts of things would fall under "community responsibility" for the docs. Assuming these are going to be an editable Wiki format, it would be great for the Railo team to define a documentation framework for this sort of activity to be contained within in the docs. 

Call it "The Railo Documentation Manifesto" - a mission statement and clear roadmap for documentation contributors to follow. Map out what the Railo team is going to do themselves and give an A, B, C of what volunteers can do and how to do it so that the docs don't get messy.

While we're on ideas for special content callouts...  There is a pretty good bit of blog content out there around examples and usage of the CFML language and Railo. How about a section on each page (or a link to a companion page for each) that lists "related reading" or "supplemental reading". It may be a challenge to vet the links, but linking to Brian Kotek's ORM blog series or John Wish's ORM book would be FAN-FRACKING-TASTIC to find right there as a callout in the ORM section. You could pretty much index Ray Camden and Ben Nadel's blogs against the entire doc set too if they didn't mind, which they might...

Also - along with others - huge thanks for these efforts!

-Cameron 

[James Kilford]

Yes, I agree with you about looking at the "Documentation".  Going to JQuery or Knockout or whatever and looking at the documentation gives me an idea of where we could get to.  The problem, as Mark has demonstrated is that all developers -- new-to-CFML or crossover -- will have a different view of what the documentation must do.  

It's daunting to start when there's a blank page, but I'm hopeful that if we get the skeleton in place, and start filling it in, it will be easier for others to contribute.  If anyone has a spare half-hour to knock up a quick page about something that interests them, it all helps in the end.  

[Tom Miller]

I agree with Cameron,

 

The thing I need the most is the differences. For instance, I’m sure I heard somewhere that Railo now supports group on cfloop and nested cfloops. When I tried to look, it took me about 20 mins to find it, when really, a google search for “Railo cfloop” should have been all I needed to do.

 

I’m probably just lazy, but it’s handy that a google search for a cf tag always brings the ACF documentation for that tag to the top of the google search results.

 

I’m sure with enough inbound links it’d get there eventually…

--

[James Kilford]

On 22 March 2013 18:03, Cameron Childress <came...@gmail.com> wrote:

On Fri, Mar 22, 2013 at 12:42 PM, Mark Drew <ma...@getrailo.com> wrote:

With regards of differences between Railo x.y and ACF x.y I think it's a fools errand and would help a few people for a short time compared to using James' time more wisely. 

As someone who has clients on ACF 7, 9, and 10 as well as clients on Railo, I would find documentation of the differences to be extraordinarily valuable. However, I recognize that I may not represent all or even most of Railo's developer base.

Yes, I'd like that sort of documentation too, not least because I think it would give people the confidence to turn to Railo Server and not look back.   

 

If spending time on calling out such differences is not a high priority right now, that's fair. But people are likely to keep asking for it so perhaps these sorts of things would fall under "community responsibility" for the docs. Assuming these are going to be an editable Wiki format, it would be great for the Railo team to define a documentation framework for this sort of activity to be contained within in the docs. 

Call it "The Railo Documentation Manifesto" - a mission statement and clear roadmap for documentation contributors to follow. Map out what the Railo team is going to do themselves and give an A, B, C of what volunteers can do and how to do it so that the docs don't get messy.

Yep, I think that, in documentation, structure is key.  I'm really keen to draw up the theoretical perfect documentation ToC and then attack it! 

 

While we're on ideas for special content callouts...  There is a pretty good bit of blog content out there around examples and usage of the CFML language and Railo. How about a section on each page (or a link to a companion page for each) that lists "related reading" or "supplemental reading". It may be a challenge to vet the links, but linking to Brian Kotek's ORM blog series or John Wish's ORM book would be FAN-FRACKING-TASTIC to find right there as a callout in the ORM section. You could pretty much index Ray Camden and Ben Nadel's blogs against the entire doc set too if they didn't mind, which they might...

I like this idea a lot.  I'd pencilled in "Useful resources and further reading", but of course in-line links would be terrific.  It wouldn't be too difficult to produce some sort of verification tool in the long term.  

James

[Igal @ getRailo.org]

so if you have a "personal" site (by personal I mean, a site that is yours and not a client's) an inbound link would be greatly appreciated ;)

[Tom Miller]

Happy to :)

 

Maybe a “powered by railo” widget people can just copy and paste in their footers would be good. I see there’s an “unofficial” logo here, but a code snippet would be nice too

http://www.getrailo.org/index.cfm/community/spread-the-word/

 

Tom.

 

 

 

From: ra...@googlegroups.com [mailto:ra...@googlegroups.com] On Behalf Of Igal @ getRailo.org
Sent: 22 March 2013 14:15
To: ra...@googlegroups.com
Subject: Re: [railo] Developer documentation

 

so if you have a "personal" site (by personal I mean, a site that is yours and not a client's) an inbound link would be greatly appreciated ;)

On 3/22/2013 11:10 AM, Tom Miller wrote:

I’m sure with enough inbound links it’d get there eventually…

 

--

[Igal @ getRailo.org]

+1

we should definitely update these "buttons" (especially the ones that have 3.1 in them).

[Cameron Childress]

On Fri, Mar 22, 2013 at 2:14 PM, James Kilford <nkil...@gmail.com> wrote:

I like this idea a lot.  I'd pencilled in "Useful resources and further reading", but of course in-line links would be terrific.  It wouldn't be too difficult to produce some sort of verification tool in the long term.  

Validating that the link returns 200 is a good start, but I think the bigger challenge will be validating the the content in the blog post is accurate and worth linking to, especially since the link would be coming from the "Official Railo Documentation".

So, while I don't think this responsibility belongs directly in the lap of the official documentation team, it's worth defining a mechanism to prevent junk links to bad info.

-Cameron

 

[Denny]

On 3/22/13 12:31 PM, Cameron Childress wrote:
...

> So, while I don't think this responsibility belongs directly in the lap of
> the official documentation team, it's worth defining a mechanism to prevent
> junk links to bad info.

We should probably follow the StackOverflow model, and pull the relevant
content in.

As for the "engine differences" docs, I'm planning on putting something
like that on cfmlprojects.org, which is for community CFML stuff vs.
Railo specific stuff.

The compatibility matrix can be pulled from the CFML dictionary files,
which kills a couple birds with one stone-- they're also used by the
project builder to flag incompatibilities when you change the target
engine (or engine version). Not saying anybody shouldn't do whatever
they'd like -- document away! -- just that there's a place for things
that are outside the scope of Railo-centric docs.

:Denny

--
Railo Technologies: getrailo.com Professional Open Source
Skype: valliantster (505)510.1336 de...@getrailo.com
GnuPG-FP: DDEB 16E1 EF43 DCFD 0AEE 5CD0 964B B7B0 1C22 CB62

[AJ Mercer]

I agree with Mark on this.

You don't have to write everything your self; I have see quite a few Wikis will have links to other resources, like blog posts. So maybe put out an invite to people that have come from other areas to Blog their experiences and thoughts and compile a list of those. This way you don't fill up the documentation that is only relevant to a small percentage of readers.

I like the structure you have so far. Thanks for getting behind this project.

AJ Mercer
<webonix:net strength="Industrial" /> | <webonix:org community="Open" />
http://twitter.com/webonix

Railo Community Manager

[Nick Kwiatkowski]

I've been moving most of our CF8 and CF9 servers at my office to Railo.

The biggest things we ran into were installation related.  Detailed instructions on how to install for use with IIS, How to get SSL to work, how to get BlazeDS to work, how to get multi-domains to work on a single site (and multi-site in general).  Most of these tasks are pretty easy if you know where to look (and are used to Tomcat).  

Also, having better documentation for those converting applications FROM ACF to Railo would be a huge plus.  I knew that CFAUTHENTICATE was a no-go, but things like not having support for SFTP tripped me up.  Also, better documentation on some of the features that work different/better than ACF like the S3 support, caching support, etc.  Most of the search engine results / blog posts about how to do those things go to the old wiki -- so they are broken links.  

-Nick

[Mark Drew]

I really think that documentation about moving from X to Railo should be done by the community. 

You guys are having the experience and should document that and add it to the wiki. 

—
Sent from Mailbox for iPhone

--

[Risto]

I just want to chime in on a "differences between ACF and Railo" being most valuable to me too.  I'm not getting rid of ACF anytime soon
since many clients I do work for already have it in place.  So why is that important if I want to develop an app on Railo? It probably isn't, but
if I'm creating a CMS or other software I would be a fool not to try and make it compatible with both engines, and a nice guide of the differences would be golden.

[Mark Drew]

Then share your knowledge in the wiki. 

The funding we are putting forward is to produce documentation for our product. As has been asked. Conversion guides would be from the community. 

—
Sent from Mailbox for iPhone

[Risto]

Of course we will have to if that's our only option, but it's also important for the Railo team to understand that your user base does think that a "differences between ACF and Railo" is important.

[Mark Drew]

We understand this but you are a vocal

minority. 

Look, go have a look at the framework one documentation. It has information on what it does and how you do it. It doesn't have information on how to use fw/1 if you use model glue. 

There are political and practical implications to that kind of documentation. I am paying someone to write documentation. I want to get the basics covered. 

I am sure all switchers will contribute to any documentation and advice on using railo anyway. 

Regards

Mark Drew

Sent from a mobile device

On 24 Mar 2013, at 16:33, Risto <ck.web...@gmail.com> wrote:

Of course we will have to if that's our only option, but it's also important for the Railo team to understand that your user base does think that a "differences between ACF and Railo" is important.

[Christian Ready]

Let me chirp in here and say that Railo doesn't exist to help users migrate away from ACF, nor does it seek to (another company positioned their product to help business migrate from CF to .NET - oddly enough they weren't warmly embraced by the CF community).

True, both are CFML language runtime compilers and yes, each vendor has an interest in maintaining compatibility with the other to a large extent. But it's also true that they have their own reasons for doing certain things a little differently.

To frame the request another way, should Adobe provide the public with documentation on the differences between ACF and Railo? They could and they certainly have the financial resources to do so, but I personally don't think they have any obligation to do so, and if they chose to take on such an endeavor, they would probably spend a lot of time and money keeping their documentation current and accurate.

My $0.02

--

Christian Ready

The Railo Company, Ltd

Professional Open Source

skype: christianready chri...@getrailo.com

+1 410 382 8070 http://www.getrailo.com

[Matt Quackenbush]

I've really tried hard to (mostly) stay out of this thread because I don't want to stir up any pot. But I just can't stay quiet any longer.

First off, Christian has hit the ball out of the park with his reply. Kudos to him for framing the biggest issues with the whole "differences between X and Y" thought process so well.

Secondly, as an open source author (and contributor, but especially as an author), I could not possibly care less if my *open source* project runs on a closed source, commercial engine. When I made the decision to switch from the engine I had been using since ~1995, I did so for many, many reasons, but chief amongst those reasons was FREEDOM. Part of that freedom is not caring about the differences between Railo and anything else. I believe in and support Railo, and all I care about is: How does Railo work?

Lastly, when Railo first began, it was likely important to discuss differences between it and other engines. However, the days of Railo being a start-up, infantile, fledgling product attempting to find its footing are long gone. Railo has been the driving force behind the development of the language for 2-3 years now. It is - in my opinion - way, way, way, way past time for Railo to care about differences. Railo is Railo. Other engines are other engines. Railo's market (from my perspective) is not the same as that of the other engines' authors, and time spent on the other engine's markets is completely wasted.

Long Live Railo!

[Mark Drew]

Sure. I get it. 

So write it already. 

—
Sent from Mailbox for iPhone

On Sun, Mar 24, 2013 at 4:33 PM, Risto <ck.web...@gmail.com> wrote:

Of course we will have to if that's our only option, but it's also important for the Railo team to understand that your user base does think that a "differences between ACF and Railo" is important.

[Adam Cameron]

On Monday, 25 March 2013 09:02:22 UTC+13, Mark Drew wrote:

We understand this but you are a vocal

minority. 

Really? From a position of not having any stats to demonstrate anything one way or another, this really surprises me. I would have thought the bulk of Railo users would be people migrating from ColdFusion, not people entirely new to CFML. I'm not disagreeing with you, Mark, but that you suggesting otherwise really surprises me.

 

Look, go have a look at the framework one documentation. It has information on what it does and how you do it. It doesn't have information on how to use fw/1 if you use model glue. 

From my understanding and from what I see in the community, this is not a like-for-like comparison. Everyone I know who uses Railo is coming from ColdFusion, and so "differences between ~" docs would be the most important. At the end of the day, all the "same as ~" docs are already written by Adobe, so at least until you get funding (or volunteers donating time) to document everything, the initial best quick win would seem to be to cover the differences.

 

There are political and practical implications to that kind of documentation.

Are there? Ones that are really significant in the bigger scheme of things? And more important than getting Railo documented in the most useful (for the community) fashion?

 

I am paying someone to write documentation. I want to get the basics covered. 

You should be targeting what's going to be most beneficial to most people. I'm not saying you're not doing that. But that's the approach you should have.

--
Adam

[Risto]

Wow, maybe I missed the whole point of the thread. I applaud everyone who has ever contributed to any Railo documentation. I also agree that you should get the basics covered if you are paying. I also think some missed my point. The Railo team knows what and who it wants to focus on, and that's great too. No, ACF doesn't publish a guide on the differences between ACF and Railo, and I wouldn't if I was ACF. My point is if there was a "differences guide" it would ease newcomers doubt switching from ACF to Railo because they could look up tags and functions they are concerned about.

I thought converting ACF users to Railo was really important. If so, then a "differences guide" would be most helpful. I don't care what other projects write or document, my opinion was focused
on Railo. You've already made your point clear, the community needs to write it.

[Justin Carter]

Like it or not, there are politics involved. Anyone in the community can publish a "differences" guide, but Railo don't necessarily want to publish a "here's how to migrate away from ACF" guide because it could be taken the wrong way. 

Like Mark says, it's community developers who will have the most experience doing this anyway. And from my experience, following a "guide" won't help you find all the edge cases in your code - you basically need to test your code on Railo and see what breaks, then fix it. No amount of reading compatibility tables or guide can do this part for you unfortunately.