Enable Lucee community to improve docs


#41

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


#42

I guess that comes back to the question of what we want this to be, do we
want it to be a free-for-all or some more controlled and curated.
Confluence lends itself more to the controlled and curated side I think.

Kind regards,

Andrew
about.me http://about.me/andrew_dixon
mso http://www.mso.net - Lucee http://lucee.org - MemberOn 18 February 2015 at 07:04, Adam Cameron <@Adam_Cameron1> wrote:

On 18 February 2015 at 19:42, Michael van Leest <@Michael_van_Leest> wrote:

Confluence is more a internal documentation tool, not really a public
system if I understand.

Adobe uses it for their CF docs. Not tat that’s a recommendation of any
sort, but it’s a statement of fact. It’s OK, but rather quirky when it
comes to formatting stuff, sometimes.


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%2BKfm6eh1Z_6159PPy%3Dim7ZuZ1_KFTHjhx9VpTP-toj%3D4Qw%40mail.gmail.com
https://groups.google.com/d/msgid/lucee/CAFwR%2BKfm6eh1Z_6159PPy%3Dim7ZuZ1_KFTHjhx9VpTP-toj%3D4Qw%40mail.gmail.com?utm_medium=email&utm_source=footer
.

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


#43

Also, here is the dashdocs that Andy Jarrett and I did:
https://github.com/andyj/dash-docset-railo https://github.com/andyj/dash-docset-railo

regards
Mark Drew

develop • deploy • deliver
http://charliemikedelta.com ttp://charliemikedelta.com> On 18 Feb 2015, at 18:04, Mark Drew <@Mark_Drew> wrote:

Andy Jarett and I made a Dash docset ages ago for the RailoDocs. Not too hard to generate now from the the system, so I can have a look at that.

I have created the repo and put the first non-working cut of luceedocs.org on it: https://github.com/cybersonic/luceedocs

If you have ideas and stuff, it’s hard to follow on the mailing list (time differences, busyness) so just add a ticket and we can discuss it there.

MD

On Wednesday, February 18, 2015 at 11:49:50 AM UTC, Nando Breiter wrote:

My point of bringing up Dash is that, in these early stages, I think Lucee would do well to design a documentation system that is easily ported and built with different distributions in mind.

I could be mistaken regarding the current ACF11 docset, but I remember that the Dash developer had noted that the ACF documentation was difficult and time consuming to import into Dash. If he can’t automate the process, then I would assume that the imported docset would go stale (in our case, perhaps rather quickly, since we’ll all soon be continuously improving the Lucee docs :slight_smile:


You received this message because you are subscribed to a topic in the Google Groups “Lucee” group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/lucee/F2CO3U2hA3w/unsubscribe https://groups.google.com/d/topic/lucee/F2CO3U2hA3w/unsubscribe.
To unsubscribe from this group and all its topics, 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/efa92ff3-b784-4a54-a556-8ddb9cdde05b%40googlegroups.com https://groups.google.com/d/msgid/lucee/efa92ff3-b784-4a54-a556-8ddb9cdde05b%40googlegroups.com?utm_medium=email&utm_source=footer.
For more options, visit https://groups.google.com/d/optout https://groups.google.com/d/optout.


#44

Confluence is more a internal documentation tool, not really a public
system if I understand.2015-02-18 0:58 GMT+01:00 Andrew Dixon <@Andrew_Dixon>:

Sorry, maybe need to add a little more to that, you can have custom page
templates (as Adam’s suggests - very good idea), integrates with JIRA, has
a Q&A plugin (Stackoverflow style), different spaces for different types of
documents, e.g. Installation guides, language syntax, etc… Also there is
a ton of access controls, etc… as well so it could be highly customised
towards the communities requirements.

Kind regards,

Andrew
about.me http://about.me/andrew_dixon
mso http://www.mso.net - Lucee http://lucee.org - Member

On 17 February 2015 at 23:53, Andrew Dixon <@Andrew_Dixon> wrote:

As we are using BitBucket and JIRA is coming along (soon I believe) can I
put forward the suggestion of using Confluence (
https://www.atlassian.com/software/confluence/) which as an open source
project we can get for free (
https://www.atlassian.com/software/confluence/pricing) and Atlassian
will even host it for us on their “cloud” solution.

Kind regards,

Andrew
about.me http://about.me/andrew_dixon
mso http://www.mso.net - Lucee http://lucee.org - Member

On 17 February 2015 at 23:41, Adam Cameron <@Adam_Cameron1> wrote:

On 18 February 2015 at 10:49, Dominic Watson <@Dominic_Watson wrote:

Point well made re Association steer. I’ll push to bring documentation
up in the next association meeting (which are regular). By then, the chief
concern (the website) should be well under way or in an acceptable place.

My point of bringing up Dash is that, in these early stages, I think
Lucee would do well to design a documentation system that is easily ported
and built with different distributions in mind. JSON endpoint for the
reference docs for example? Hell yeah. Let people build whatever plugins
they need for whatever tooling they are using and do it without duplication
of effort and computing power. Make editing the source of this
documentation easy. If on BitBucket, there are inline editing tools, give
people sufficient instructions on how to make a pull request. Not quite as
easy as direct inline editing of a wiki page, but far more powerful and
useful.

Keep the ideas and links coming at this point I say, while influence
can still be had. Getting the docs “right” will be a huge win.

Nice one Dom.

If you’ll just let me push for human-written (as opposed to automated)
docs some more.

If “we” were to come up with a decent template for a function / tag doc
wiki page, then we can facilitate humans maintaining the content (big win)
and make it reasonably easy to then reduce that back to a JSON treatment
which is publicly exposed for other people to generate their Dash docs,
Sublime Text plug-ins, docs shipped in Lucee Admin etc.

Speaking for myself: I’ll fix docs provided I can click a button and
type the fix in and submit it. I won’t edit an XML or a JSON file. And I
sure as shit won’t fork stuff, do pull reqs etc simply to help someone with
their docs. Quite simply because this is the 21stC, and computers are
supposed to serve the humans, not the other way around. The UI for data
entry should suit the “U” in “UI”, and that is a person.


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%2BKd_tx3ZZquUs4y04nE_uM7m8oRM2ozVHo7J9icH%2BzysyA%40mail.gmail.com
https://groups.google.com/d/msgid/lucee/CAFwR%2BKd_tx3ZZquUs4y04nE_uM7m8oRM2ozVHo7J9icH%2BzysyA%40mail.gmail.com?utm_medium=email&utm_source=footer
.

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/CAG1WijVXHddkssCxa_izPxkNQ0zWQxP%3DN6kOBWJUW3WLFDZpxA%40mail.gmail.com
https://groups.google.com/d/msgid/lucee/CAG1WijVXHddkssCxa_izPxkNQ0zWQxP%3DN6kOBWJUW3WLFDZpxA%40mail.gmail.com?utm_medium=email&utm_source=footer
.

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


Michael van Leest


#45

Confluence is more a internal documentation tool, not really a public
system if I understand.

Adobe uses it for their CF docs. Not tat that’s a recommendation of any
sort, but it’s a statement of fact. It’s OK, but rather quirky when it
comes to formatting stuff, sometimes.On 18 February 2015 at 19:42, Michael van Leest <@Michael_van_Leest> wrote:


#46

My point of bringing up Dash is that, in these early stages, I think Lucee
would do well to design a documentation system that is easily ported and
built with different distributions in mind.

I could be mistaken regarding the current ACF11 docset, but I remember that
the Dash developer had noted that the ACF documentation was difficult and
time consuming to import into Dash. If he can’t automate the process, then
I would assume that the imported docset would go stale (in our case,
perhaps rather quickly, since we’ll all soon be continuously improving the
Lucee docs :slight_smile:


#47

A post was split to a new topic: How is the planning for code examples?