Enable Lucee community to improve docs

dev google-group-archive
1

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

2

Already with you there as an enhancement. A branch of the railodocs site allowed you to sign in with your GitHub account so that you could make suggestions for changes but I reverted that due to a bug and never re implemented it.

If I get time this week I shall get luceedocs up to date and allow people to submit gists (by id) that you can then run on trycfm for example.

There are some questions of the storage but that should be ok (it’s all driven by Json files)

Mark Drew> On 15 Feb 2015, at 10:56, Nando Breiter <@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

You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAGHrs%3D9HYRj4ykuwOv%3DdejcRZresFJSzcAHB46JAGxdoHhfxCw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

3

In my opinion a code example also need a description, so why not do this
in the wiki with a certain pattern and the doc looks in the wiki for
examples.
And in the wiki we link or include the doc …

I agree. Can I recommend that instead of having the RailoDocs mechanism
that derives the docs pages from some inner workings of the source code to
basically “automate” the docs pages, we simply use that process to populate
a wiki page once, but thereafter just run it as a wiki. I found
railodocs.org to be “better than nothing”, but not really that useful
because simply offering the syntax for a given construct is not the useful
part of documentation; the useful part is the narrative description of the
functionality, and the examples. This needs to be done by humans, not by
automation. However the automation is a good way to get the docs started in
the first place.

My suggestion is to borrow Mark’s talents to get the automated content in
to start with, and then come up with a template for the community to use to
backfill the rest, as and when someone feels like it.

I would have added a reasonable amount of content to the Railo docs if
there was a mechanism to do so. All that potential community input has now
been lost. I’m sure I’m not the only one here. It’s all well and good
saying that this is a community-driven project, but we must facilitate the
community actually being able to input.

One thing that is good in the PHP docs is the initial section is the
“official” doc entry, but then ppl can add comments with their own
examples. See PHP: json_decode - Manual for a
random example. I think some community members might not think they’re
worthy (they’re wrong, but hey: ppl are weird) to maintain the official
docs, but would be comfortable adding comments. Can the wiki cater for that?

Whatever is done, we should do v1.0 quickish. Once the content is there and
accessible, it can start being improved & added to. Down the track if we
come up with a better approach, or have different requirements, we can
extract the content from the v1.0 solution and import it into whatever
mechanism v2.0 needs. But not having at least a half decent community
driven public docs site is less good than it could be.

Thoughts?On Monday, 16 February 2015 02:21:24 UTC+13, Micha wrote:

–
Adam

4

That’s not a viable way for the community to maintain the docs. Editing an
XML file?

And isn’t that file actually used by Railo itself? So if someone does’t
edit it right…–
Adam

On 16 February 2015 at 10:16, Dominic Watson <@Dominic_Watson> wrote:

There are links in railodocs (I think) to the source where those
functions and tags are defined.

Ah yes, there are indeed, nice one. +1 For keeping those in and giving
them a clearer call to action. “Edit me on GitHub” or some such.

–
Pixl8 Interactive, 3 Tun Yard, Peardon Street, London
SW8 3HT, United Kingdom

T: +44 [0] 845 260 0726• W: www.pixl8.co.uk• E: info@pixl8.co.uk
Follow us on: Facebook http://www.facebook.com/pixl8 Twitter
http://www.twitter.com/pixl8 LinkedIn http://www.linkedin.com/pixl8CONFIDENTIAL
AND PRIVILEGED - This e-mail and any attachment is intended solely for the
addressee, is strictly confidential and may also be subject to legal,
professional or other privilege or may be protected by work product
immunity or other legal rules. If you are not the addressee please do not
read, print, re-transmit, store or act in reliance on it or any
attachments. Instead, please email it back to the sender and then
immediately permanently delete it. Pixl8 Interactive Ltd Registered in
England. Registered number: 04336501. Registered office: 8 Spur Road,
Cosham, Portsmouth, Hampshire, PO6 3EB

–
You received this message because you are subscribed to the Google Groups
“Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/lucee/CAEYvUx%3DptDaAj52MZDjHsH7vau%3Dny8zAt0agQ5NdDTJD7Q_eHw%40mail.gmail.com
https://groups.google.com/d/msgid/lucee/CAEYvUx%3DptDaAj52MZDjHsH7vau%3Dny8zAt0agQ5NdDTJD7Q_eHw%40mail.gmail.com?utm_medium=email&utm_source=footer
.
For more options, visit https://groups.google.com/d/optout.

5

Yeah. It’s all happened before.

I can write something to create wiki pages no problem but what you need is some kind of versioning. Once Lucee 5 or 6.3.4.7 is out someone is always going to be asking for Lucee 4.3.5.3 docs. Happens.

I have pages and pages of emails with regards to the docs. So I am open to anything. I think the wiki is the best place as we can then export it to whatever. But as with previous wikis I see very little effort in updating, collating, and maintaining. Just a lot of ideas on how someone could do it.

I even added (to the Railo mailing list) a footer suggesting if an answer helped you, you should add it to the wiki. The technology here is not the problem.

Mark Drew> On 15 Feb 2015, at 18:22, Adam Cameron <@Adam_Cameron1> wrote:

On Monday, 16 February 2015 02:21:24 UTC+13, Micha wrote:
In my opinion a code example also need a description, so why not do this in the wiki with a certain pattern and the doc looks in the wiki for examples.
And in the wiki we link or include the doc …

I agree. Can I recommend that instead of having the RailoDocs mechanism that derives the docs pages from some inner workings of the source code to basically “automate” the docs pages, we simply use that process to populate a wiki page once, but thereafter just run it as a wiki. I found railodocs.org to be “better than nothing”, but not really that useful because simply offering the syntax for a given construct is not the useful part of documentation; the useful part is the narrative description of the functionality, and the examples. This needs to be done by humans, not by automation. However the automation is a good way to get the docs started in the first place.

My suggestion is to borrow Mark’s talents to get the automated content in to start with, and then come up with a template for the community to use to backfill the rest, as and when someone feels like it.

I would have added a reasonable amount of content to the Railo docs if there was a mechanism to do so. All that potential community input has now been lost. I’m sure I’m not the only one here. It’s all well and good saying that this is a community-driven project, but we must facilitate the community actually being able to input.

One thing that is good in the PHP docs is the initial section is the “official” doc entry, but then ppl can add comments with their own examples. See PHP: json_decode - Manual for a random example. I think some community members might not think they’re worthy (they’re wrong, but hey: ppl are weird) to maintain the official docs, but would be comfortable adding comments. Can the wiki cater for that?

Whatever is done, we should do v1.0 quickish. Once the content is there and accessible, it can start being improved & added to. Down the track if we come up with a better approach, or have different requirements, we can extract the content from the v1.0 solution and import it into whatever mechanism v2.0 needs. But not having at least a half decent community driven public docs site is less good than it could be.

Thoughts?

–
Adam

You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/5f0a56f3-4c7a-4028-8cab-d3bf4a1d0a1f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

6

Even if they edit it wrong, it would have to be submitted as a pull
request so hopefully someone would test it before it breaks a future
release of Lucee.

That’s a pain in the arse simply to tweak some docs. It’s gotta be
something like Wikimedia where someone can just edit the page.

There is the problem really. You want people’s modifications (typo fixes,
clarifications, grammar, etc) to make it into the engine as easily as
possible.

This is where we diverge. The docs don’t need to get into the engine at
all. Docs are docs. The engine is the engine. There’s no need to conflate
the two. I think this is where we’re (collectively) making a rod for our
own back here. The two things don’t need to be coupled. And, TBH, I don’t
really see much of a gain from doing so.

Everything else you say sounds bang-on.On 16 February 2015 at 10:53, Mark Drew <@Mark_Drew> wrote:

–
Adam

7

In my opinion a code example also need a description, so why not do this in
the wiki with a certain pattern and the doc looks in the wiki for examples.
And in the wiki we link or include the doc …

MichaAm Sonntag, 15. Februar 2015 schrieb Nando Breiter :

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

–
You received this message because you are subscribed to the Google Groups
“Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to lucee+unsubscribe@googlegroups.com
<javascript:_e(%7B%7D,‘cvml’,‘lucee%2Bunsubscribe@googlegroups.com’);>.
To post to this group, send email to lucee@googlegroups.com
<javascript:_e(%7B%7D,‘cvml’,‘lucee@googlegroups.com’);>.
To view this discussion on the web visit
https://groups.google.com/d/msgid/lucee/CAGHrs%3D9HYRj4ykuwOv%3DdejcRZresFJSzcAHB46JAGxdoHhfxCw%40mail.gmail.com
https://groups.google.com/d/msgid/lucee/CAGHrs%3D9HYRj4ykuwOv%3DdejcRZresFJSzcAHB46JAGxdoHhfxCw%40mail.gmail.com?utm_medium=email&utm_source=footer
.
For more options, visit https://groups.google.com/d/optout.

8

Mark, great to hear you are working on this.

Whatever the architecture, what I’m looking for is a very easy and
efficient user experience to submit code samples, so that the interruption
to our workflow, and “cognitive state”, is minimized. The easier we make
it, the more likely developers will submit them as they are working.
Something like:

  1. locate the function or tag in the docs
  2. click a Contribute code sample link
  3. copy and paste
  4. write an optional description, or a few explanatory comments in the code
  5. save
  6. go back to what you were doing

Mark, is that the workflow you have in mind?

By the way, the inspiration for this idea came from looking at the Lucee
docs for queryExecute(). The method signature alone gave me no clue how
query params should be structured.

So I looked at the CF11 docs and found a set of lame code examples that
someone who certainly does not use CFML professionally dreamed up. They
weren’t of any real help at all, and started to think “The Lucee community
can do far better than this … how can we best enable community
contributions???”

Folks are saying CFML’s reputation is holding uptake back. Any time I look
at a new technology, the better the docs, the more likely I am to adopt it.
In my mind, good documentation goes a long way toward forming a good
reputation. And it certainly would make development easier for all of us as
Lucee begins to diverge more and more from ACF’s implementation.

1 Like
9

There are links in railodocs (I think) to the source where those
functions and tags are defined.

Ah yes, there are indeed, nice one. +1 For keeping those in and giving them
a clearer call to action. “Edit me on GitHub” or some such.–
Pixl8 Interactive, 3 Tun Yard, Peardon Street, London
SW8 3HT, United Kingdom

T: +44 [0] 845 260 0726• W: www.pixl8.co.uk• E: info@pixl8.co.uk
Follow us on: Facebook http://www.facebook.com/pixl8 Twitter
http://www.twitter.com/pixl8 LinkedIn
http://www.linkedin.com/pixl8CONFIDENTIAL
AND PRIVILEGED - This e-mail and any attachment is intended solely for the
addressee, is strictly confidential and may also be subject to legal,
professional or other privilege or may be protected by work product
immunity or other legal rules. If you are not the addressee please do not
read, print, re-transmit, store or act in reliance on it or any
attachments. Instead, please email it back to the sender and then
immediately permanently delete it. Pixl8 Interactive Ltd Registered in
England. Registered number: 04336501. Registered office: 8 Spur Road,
Cosham, Portsmouth, Hampshire, PO6 3EB

10

cfwheels has a ‘versioned’ function reference,
i.e http://cfwheels.org/docs/1-3/function so you can see in the URL pretty
quickly which version you’re looking at, which I find useful.
The main functions are done by the core team (via jsdoc style comments in
the source), and then there’s the user guides (i.e stuff like
http://cfwheels.org/docs/1-3/chapter/conventions ) which we’re in the
process on converting to markdown which live in the main repo.

Once we’ve got all that done (not a small job!) we should be able to
autogenerate from the .md files, and anyone can contribute.

The version-ing is an issue there though - i.e, if you’re specifically
referring to a function by URL, it’s very easily to put the version number
in rather than the ‘non-versioned’ canonical link.

Generally speaking I’m all for the API functions to be versioned, and the
userguides/examples to be more flexible, as they can still be written in a
‘since version 1.2, you can do x’ way.
TOn Sunday, 15 February 2015 22:12:42 UTC, Adam Cameron wrote:

On 16 February 2015 at 10:53, Mark Drew <mark...@gmail.com <javascript:>> wrote:

Even if they edit it wrong, it would have to be submitted as a pull
request so hopefully someone would test it before it breaks a future
release of Lucee.

That’s a pain in the arse simply to tweak some docs. It’s gotta be
something like Wikimedia where someone can just edit the page.

There is the problem really. You want people’s modifications (typo fixes,
clarifications, grammar, etc) to make it into the engine as easily as
possible.

This is where we diverge. The docs don’t need to get into the engine at
all. Docs are docs. The engine is the engine. There’s no need to conflate
the two. I think this is where we’re (collectively) making a rod for our
own back here. The two things don’t need to be coupled. And, TBH, I
don’t really see much of a gain from doing so.

Everything else you say sounds bang-on.

–
Adam

11

I don’t think a wiki is appropriate for reference documentation. I believe
that reference documentation should be generated from source - easier to
version along with the code and inherently tied to each version.

In theory, sure. In practice, the stuff that can be autogenerated from the
source is close to useless for most purposes. Accurate and versioned is one
thing. But if what is accurate and versioned isn’t actually much use for
the task at hand: what’s the point?

If that stuff could be autogenerated and then embedded in a bespoke page
that has actual useful content, then sure. However I think the benefits
the autogenerated stuff - basically tag / function signatures - is minimal.

Still: whatever. As long as the end result is something that’s useful and
community-maintainable, it’s no odds really.On 16 February 2015 at 09:46, Dominic Watson <@Dominic_Watson> wrote:

–
Adam

12

I even added (to the Railo mailing list) a footer suggesting if an answer
helped you, you should add it to the wiki. The technology here is not the
problem.

I added some stuff to the Railo wiki, responding to that request. The
sense I had was I was adding it to a pile of suggestions and comments, and
that held me back somewhat. It’s easy to set up a wiki, but I think the
medium’s unstructured nature makes it less than ideal for documentation.

I’m only really familiar with Wikimedia and Confluence, but aren’t wikis
only unstructured if one neglects to apply structure to them? Everything on
Wikipedia is categorised and cross referenced etc as appropriate, after all.

That the documents themselves are not arranged in a structured sense is
neither here nor there, provided the UI provides the categorisation and
other navigational structure.

What I like about the current Lucee docs included with the server, or the
Railo docs before that, is that the structure for tags and functions is
clear and it’s quick to navigate. I assume is that it is auto-generated
with each point release to keep up with the small, detailed changes that
occur to the language. That’s valuable to retain, but I don’t think the
description and code examples needs a new version for each point release.

Nope. It’s not useless information, but equally it’s not really the sort of
thing I generally need to know when I’m doing a docs look-up. I am after an
understanding of how the functionality works. Adobe’s docs’ “History”
section (which is maintained by hand) is entire adequate for this.

The thing is… task automation is for commonly-run tasks when manual
maintenance is not viable. Lucee’s CFML simply doesn’t change often enough
for it to be automated.

If we wanted to dedupe the work, then take the documentation material out
of the source code, and have it centrally based in [wherever]. Lucee does
not need attribute hints for it to actually work, so it’s not really the
best place for that stuff in the first place. Especially as it will end up
being the developers (ie: Micha and Igal) writing those docs, and they’ve
got better things to do than that.

Keeping up with version changes to individual tags or functions could be
done simply in text, such as “version 5.5 added a new attribute *xyz which
does abc” *rather than thinking that we need to have a separate doc set
for each point release. If in the course of our work, we notice the
description misses a detail, we could correct it,

Precisely. Docs are kind of like Schrodinger’s Cat. It only matters if
they’re right or wrong when ppl come to look at them. Stuff that gets
looked at a lot will also keep itself up to date (provided the community
pitches in, and we facilitate an easy way of doing this).On 16 February 2015 at 10:42, Nando Breiter <@Nando_Breiter> wrote:

–
Adam

13

There are links in railodocs (I think) to the source where those functions and tags are defined.

Mark Drew> On 15 Feb 2015, at 20:46, Dominic Watson <@Dominic_Watson> wrote:

+1 for code examples via Gists attached to the reference, especially if we can then open them up on trycf or some other mechanism that isn’t so strongly linked with ColdFusion. That would be uber.

I don’t think a wiki is appropriate for reference documentation. I believe that reference documentation should be generated from source - easier to version along with the code and inherently tied to each version.

To make it easier for folk to contribute with improvements to the reference documentation, links to the source file in source control would be great. https://readthedocs.org/ do a good job of this with their default documentation theme (they give you an “Edit on GitHub” link on each documentation page, e.g. ). Editorial approval can then be done through pull requests.

On 15 February 2015 at 19:45, Adam Cameron <@Adam_Cameron1> wrote:

I can write something to create wiki pages no problem but what you need is some kind of versioning. Once Lucee 5 or 6.3.4.7 is out someone is always going to be asking for Lucee 4.3.5.3 docs. Happens.

You’re inventing a barrier here. Firstly, we don’t need to deal with that yet, secondly most version-to-version changes are trivial, and can be maintained by hand.

There is not so much change as for the community to not be able to just DIY as and when.

It’s getting the current corpus loaded somewhere to start with that’s the hard bit.

Is it possible - version to version - to publish a document detailing syntax changes? EG: new args, changed behaviour, new functions, etc? I presume if you’re automating the current Railo docs, then the info exists somewhere? Getting a manifest of changes each revision would help volunteer documenters know what needs to be updated.

Just a lot of ideas on how someone could do it.

Simple. Don’t give people your email address, or just ignore those emails. And respond to forum posts with “go work it out and then update the docs: this is a community project”. Or just don’t respond to the forum posts either. If you’re finding yourself on the spot with ppl clamouring or documentation updates, that’s only because you’re putting yourself on the spot. Just don’t.

Anyway, this is all perhaps a side effect of the previous systems not being easily user-editable anyhow. I for one am happy to answer a person’s docs question by first updating the docs (if necessary) and then say “I’ve updated the docs… now go RTFM”.

And we can goad the other Usual Suspects here to likewise help out too :wink:

I even added (to the Railo mailing list) a footer suggesting if an answer helped you, you should add it to the wiki. The technology here is not the problem.

Well it has been in the past. I’ve not been able to update the docs. So saying it’s not a problem isn’t really accurate. It doesn’t need to be a problem, but it has been.

–
Adam

You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAFwR%2BKeHeBY__TYtw2ah%3D1YAJpoDp75%2BvBfbEFXNhx%3DLg0CqfQ%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

–
Pixl8 Interactive, 3 Tun Yard, Peardon Street, London
SW8 3HT, United Kingdom
T: +44 [0] 845 260 0726• W: www.pixl8.co.uk• E: info@pixl8.co.uk
Follow us on: Facebook Twitter LinkedIn
CONFIDENTIAL AND PRIVILEGED - This e-mail and any attachment is intended solely for the addressee, is strictly confidential and may also be subject to legal, professional or other privilege or may be protected by work product immunity or other legal rules. If you are not the addressee please do not read, print, re-transmit, store or act in reliance on it or any attachments. Instead, please email it back to the sender and then immediately permanently delete it. Pixl8 Interactive Ltd Registered in England. Registered number: 04336501. Registered office: 8 Spur Road, Cosham, Portsmouth, Hampshire, PO6 3EB

You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAEYvUxmUrS9m-MV3NMbsC5FV9%3D-__%3DMxoGQF3x%2BUB_2k41EB0Q%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

14

Oh it’s probably worth reminding people that the ColdFusion 9 documentation
is creative commons licensed, so it’s fine to use some of the content there
as a basis for Lucee docs. In a lot of situations the CF and Lucee
functionality is identical, or not very different so the CF docs would do
the first 80% of the work. It’s then just down to us to augment where
necessary. The requirement then is to offer the Lucee docs as CC, which I
don’t see as being a problem?

FWIW, I have already converted the CF9 docs to a standardised JSON format
for ppl to use: GitHub - adamcameron/cfmldocs: A project to centralise CFML documentation so that if the vendors mess with the live version of the docs, there's still a public repository of them

The subsequent CF docs are not CC, so we can’t use those.–
Adam

On Monday, 16 February 2015 07:22:40 UTC+13, Adam Cameron wrote:

On Monday, 16 February 2015 02:21:24 UTC+13, Micha wrote:

In my opinion a code example also need a description, so why not do this
in the wiki with a certain pattern and the doc looks in the wiki for
examples.
And in the wiki we link or include the doc …

I agree. Can I recommend that instead of having the RailoDocs mechanism
that derives the docs pages from some inner workings of the source code to
basically “automate” the docs pages, we simply use that process to populate
a wiki page once, but thereafter just run it as a wiki. I found
railodocs.org to be “better than nothing”, but not really that useful
because simply offering the syntax for a given construct is not the useful
part of documentation; the useful part is the narrative description of the
functionality, and the examples. This needs to be done by humans, not by
automation. However the automation is a good way to get the docs started in
the first place.

My suggestion is to borrow Mark’s talents to get the automated content in
to start with, and then come up with a template for the community to use to
backfill the rest, as and when someone feels like it.

I would have added a reasonable amount of content to the Railo docs if
there was a mechanism to do so. All that potential community input has now
been lost. I’m sure I’m not the only one here. It’s all well and good
saying that this is a community-driven project, but we must facilitate the
community actually being able to input.

One thing that is good in the PHP docs is the initial section is the
“official” doc entry, but then ppl can add comments with their own
examples. See PHP: json_decode - Manual for a
random example. I think some community members might not think they’re
worthy (they’re wrong, but hey: ppl are weird) to maintain the official
docs, but would be comfortable adding comments. Can the wiki cater for that?

Whatever is done, we should do v1.0 quickish. Once the content is there
and accessible, it can start being improved & added to. Down the track if
we come up with a better approach, or have different requirements, we can
extract the content from the v1.0 solution and import it into whatever
mechanism v2.0 needs. But not having at least a half decent community
driven public docs site is less good than it could be.

Thoughts?

–
Adam

1 Like
15

There is the problem really. You want people’s modifications (typo fixes,
clarifications, grammar, etc) to make it into the engine as easily as
possible.

I wasn’t at all suggesting that community contributions are persisted to
Lucee source code, if that’s what you understood. I was merely suggesting
to use the function or tag name as a common key (function names must all be
unique, same with tag names), and store community contributed descriptions
and gists elsewhere.

16

Even if they edit it wrong, it would have to be submitted as a pull request so hopefully someone would test it before it breaks a future release of Lucee.

There is the problem really. You want people’s modifications (typo fixes, clarifications, grammar, etc) to make it into the engine as easily as possible. And that is, currently, by editing those files. Other language aspects such parsing are all in Java files and I don’t know much of that side.

We could generate wiki pages with either commenting or editing allowed. And we have done so in the past but any edits to, for example, a tag’s description need (or rather, should) then go back into he actual definition, I think.

So. I have been forking railodocs which is in essence a publicly viewable version of the docs that are supplied with each version of Lucee. If that is not enough, as it isn’t really for full documentation I would suggest to integrate more complex docs from the wiki (markdown) and “curate” their structure.

Code examples for tag and functions can be added as gist id’s with community moderation kind of built in the gist system

Commenting via Disqus on every page.

The editing of the taglib and funclib would be via forking the project in bitbucket

So, those are my suggestions.

Mark Drew> On 15 Feb 2015, at 21:37, Adam Cameron <@Adam_Cameron1> wrote:

That’s not a viable way for the community to maintain the docs. Editing an XML file?

And isn’t that file actually used by Railo itself? So if someone does’t edit it right…

–
Adam

On 16 February 2015 at 10:16, Dominic Watson <@Dominic_Watson> wrote:

There are links in railodocs (I think) to the source where those functions and tags are defined.

Ah yes, there are indeed, nice one. +1 For keeping those in and giving them a clearer call to action. “Edit me on GitHub” or some such.

–
Pixl8 Interactive, 3 Tun Yard, Peardon Street, London
SW8 3HT, United Kingdom
T: +44 [0] 845 260 0726• W: www.pixl8.co.uk• E: info@pixl8.co.uk
Follow us on: Facebook Twitter LinkedIn
CONFIDENTIAL AND PRIVILEGED - This e-mail and any attachment is intended solely for the addressee, is strictly confidential and may also be subject to legal, professional or other privilege or may be protected by work product immunity or other legal rules. If you are not the addressee please do not read, print, re-transmit, store or act in reliance on it or any attachments. Instead, please email it back to the sender and then immediately permanently delete it. Pixl8 Interactive Ltd Registered in England. Registered number: 04336501. Registered office: 8 Spur Road, Cosham, Portsmouth, Hampshire, PO6 3EB

You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAEYvUx%3DptDaAj52MZDjHsH7vau%3Dny8zAt0agQ5NdDTJD7Q_eHw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

–
You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAFwR%2BKfoS7q0K_GxK3vXYBm9G-wvhbhcYYbxjwrvm1syBTiRDA%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

17

@Mark Would it be possible to create a GitHub account for Lucee doc gists,
so that storage was centralized in one account and accessible to more than
one person? I work alone, so I’m not very familiar with how folks working
in teams do this, but it occurred to me that if gists were stored in
multiple accounts, we might soon run into problems with accessibility, to
correct or update code samples as the language evolves for instance. That
said, you’ve almost certainly thought of this as well …

Aria Media Sagl
Via Rompada 40
6987 Caslano
Switzerland

+41 (0)91 600 9601
+41 (0)76 303 4477 cell
skype: ariamediaOn Sun, Feb 15, 2015 at 3:49 PM, Nando Breiter <@Nando_Breiter> wrote:

Mark, great to hear you are working on this.

Whatever the architecture, what I’m looking for is a very easy and
efficient user experience to submit code samples, so that the interruption
to our workflow, and “cognitive state”, is minimized. The easier we make
it, the more likely developers will submit them as they are working.
Something like:

  1. locate the function or tag in the docs
  2. click a Contribute code sample link
  3. copy and paste
  4. write an optional description, or a few explanatory comments in the code
  5. save
  6. go back to what you were doing

Mark, is that the workflow you have in mind?

By the way, the inspiration for this idea came from looking at the Lucee
docs for queryExecute(). The method signature alone gave me no clue how
query params should be structured.

So I looked at the CF11 docs and found a set of lame code examples that
someone who certainly does not use CFML professionally dreamed up. They
weren’t of any real help at all, and started to think “The Lucee community
can do far better than this … how can we best enable community
contributions???”

Folks are saying CFML’s reputation is holding uptake back. Any time I look
at a new technology, the better the docs, the more likely I am to adopt it.
In my mind, good documentation goes a long way toward forming a good
reputation. And it certainly would make development easier for all of us as
Lucee begins to diverge more and more from ACF’s implementation.

18

I was going to suggest that someone look at the Taffy.io docs. Adam has a separate set of docs for each version (admittedly the volume of docs for Taffy are not what Lucee would need). If memory serves his source files are stored in Markdown and then HTML is auto generated from those.

Dan> On Feb 15, 2015, at 5:33 PM, Tom King <@Tom_King> wrote:

cfwheels has a ‘versioned’ function reference, i.e http://cfwheels.org/docs/1-3/function so you can see in the URL pretty quickly which version you’re looking at, which I find useful.
The main functions are done by the core team (via jsdoc style comments in the source), and then there’s the user guides (i.e stuff like http://cfwheels.org/docs/1-3/chapter/conventions ) which we’re in the process on converting to markdown which live in the main repo.

Once we’ve got all that done (not a small job!) we should be able to autogenerate from the .md files, and anyone can contribute.

The version-ing is an issue there though - i.e, if you’re specifically referring to a function by URL, it’s very easily to put the version number in rather than the ‘non-versioned’ canonical link.

Generally speaking I’m all for the API functions to be versioned, and the userguides/examples to be more flexible, as they can still be written in a ‘since version 1.2, you can do x’ way.
T

On Sunday, 15 February 2015 22:12:42 UTC, Adam Cameron wrote:

On 16 February 2015 at 10:53, Mark Drew <mark...@gmail.com <javascript:>> wrote:
Even if they edit it wrong, it would have to be submitted as a pull request so hopefully someone would test it before it breaks a future release of Lucee.

That’s a pain in the arse simply to tweak some docs. It’s gotta be something like Wikimedia where someone can just edit the page.

There is the problem really. You want people’s modifications (typo fixes, clarifications, grammar, etc) to make it into the engine as easily as possible.

This is where we diverge. The docs don’t need to get into the engine at all. Docs are docs. The engine is the engine. There’s no need to conflate the two. I think this is where we’re (collectively) making a rod for our own back here. The two things don’t need to be coupled. And, TBH, I don’t really see much of a gain from doing so.

Everything else you say sounds bang-on.

–
Adam

–
You received this message because you are subscribed to the Google Groups “Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an email to lucee+unsubscribe@googlegroups.com mailto:lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com mailto:lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/a3df604e-7795-4bdf-b5c4-2f5be12428b6%40googlegroups.com https://groups.google.com/d/msgid/lucee/a3df604e-7795-4bdf-b5c4-2f5be12428b6%40googlegroups.com?utm_medium=email&utm_source=footer.
For more options, visit https://groups.google.com/d/optout https://groups.google.com/d/optout.

19

I was looking at this for myself the other day, it might be something
interesting for Lucee docs?

http://readme.io (and free for open source).2015-02-15 23:33 GMT+01:00 Nando Breiter <@Nando_Breiter>:

There is the problem really. You want people’s modifications (typo
fixes, clarifications, grammar, etc) to make it into the engine as easily
as possible.

I wasn’t at all suggesting that community contributions are persisted to
Lucee source code, if that’s what you understood. I was merely suggesting
to use the function or tag name as a common key (function names must all be
unique, same with tag names), and store community contributed descriptions
and gists elsewhere.

–
You received this message because you are subscribed to the Google Groups
“Lucee” group.
To unsubscribe from this group and stop receiving emails from it, send an
email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/lucee/CAGHrs%3D-K0SKhBR1V9nq9DcnMRXF%3DwBVQiU3Ju5NyvZ9ZeN0OuQ%40mail.gmail.com
https://groups.google.com/d/msgid/lucee/CAGHrs%3D-K0SKhBR1V9nq9DcnMRXF%3DwBVQiU3Ju5NyvZ9ZeN0OuQ%40mail.gmail.com?utm_medium=email&utm_source=footer
.

For more options, visit https://groups.google.com/d/optout.

–
Michael van Leest

20

Why doesn’t someone who wants this format actually put their hand up and *do

something about it*?

Well, partly because I would miss your rants about this… :slight_smile:
Point well taken.

You worry about the docs… I’ll worry about the rants. Deal?

;-)On Wednesday, 18 February 2015 07:31:35 UTC+13, lu...@lesener.de wrote:

–
Adam