I wouldn’t mind helping out with doc contributions. I just need to be
steered in the right direction and where to contribute.
As an aside, one thing I’d really like us to do is to provide examples with
their actual result! As a trivial example for left()
string = ‘Dan is cool’;
left(string, 3); //>> ‘Dan’
I really appreciate the way Ruby’s docs show the result in the sample
usage. CF’s docs are all snippets of text (usually with some sort of form),
that I would need to copy, put it in a random CFM run the snippet to see
exactly what the output is. It drives me nuts, all I want to see is what
the result is after the function call.On Sunday, February 15, 2015 at 4:56:51 AM UTC-6, Nando Breiter wrote:
The Lucee docs lack code examples. Sometimes these aren’t needed, just the
method or tag signature is enough to work it out. But especially for
newbies, code examples would be very helpful.As developers, we are all pressed for time, and I think we tend to value
using our time efficiently to maximum effect, we don’t like squandering it.As an open source project, Lucee needs us to step up and contribute. One
area where we all can help is documentation. The question is how can we
make this simple and efficient for Lucee devs?So here’s a suggestion.
On the Lucee docs site, for each method or tag there would be a link to
contribute a code example. Clicking on it opens a textarea field to paste a
code example, a gist. Over time, a variety of code examples would
accumulate. None of them would need to show how to use every feature of the
method or tag. All that would be asked is that the gist show a working
example.Contributing devs would not need to set aside dedicated time to develop
examples. Leave a browser tab open to the docs site, and in the flow of
your daily work, copy and paste a real working code example, especially if
it is one that you would normally save to a snippet to remind yourself of
the syntax.These gists would all be keyed to the function or tag name, and stored in
such a way that both the website docs and docs installed on each server
could pull them in and display them.The key concepts here are 1) make it very quick and easy to contribute
examples, so Lucee devs would not need to interrupt the flow of their daily
work, and 2) store the examples keyed to the function or tag name so they
can be used across versions so the examples are preserved across version
releases.The examples could also have some meta data as to the version, for
example, but I would not introduce that in such a way that it would slow
contributors down. Maybe the assumption could be that a contribution is
made against the current stable version, as the default, and allow the
contributor to change it.I think Mark Drew is developing a docs website for Lucee. If he hasn’t
thought of this already, I’m suggesting it as an enhancement.Aria Media Sagl
Via Rompada 40
6987 Caslano
Switzerland+41 (0)91 600 9601
+41 (0)76 303 4477 cell
skype: ariamedia
