Enable Lucee community to improve docs

[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

[Mark Drew]

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

--
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+un...@googlegroups.com.
To post to this group, send email to lu...@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.

[Michael Offner]

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 ...

Micha

--

[Nando Breiter]

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.

[Nando Breiter]

@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: ariamedia

[Adam Cameron]

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 http://php.net/manual/en/function.json-decode.php 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

[Adam Cameron]

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: https://github.com/daccfml/cfmldocs

The subsequent CF docs are not CC, so we can't use those.

-- 

Adam

[Mark Drew]

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

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/5f0a56f3-4c7a-4028-8cab-d3bf4a1d0a1f%40googlegroups.com.

[Adam Cameron]

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 ;-)

 

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

[Dominic Watson]

+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.

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@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: in...@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

[Mark Drew]

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

Mark Drew

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAEYvUxmUrS9m-MV3NMbsC5FV9%3D-__%3DMxoGQF3x%2BUB_2k41EB0Q%40mail.gmail.com.

[Dominic Watson]

> 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.

[Adam Cameron]

On 16 February 2015 at 09:46, Dominic Watson <dominic...@pixl8.co.uk> wrote:

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.

-- 

Adam

[Adam Cameron]

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

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAEYvUx%3DptDaAj52MZDjHsH7vau%3Dny8zAt0agQ5NdDTJD7Q_eHw%40mail.gmail.com.

[Nando Breiter]

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.

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.

What about a simple custom application included with the docs website that uses that structure to a) provide a means to add and edit a description for each function and tag, key it to the function/tag name, and persist it? And then both the docs website and each individual copy of the docs that ships with the server would be modified to display that description under the method/ tag signature? 

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, knowing it would be retained into the future and easily accessible. We could also contribute working code samples as gists (to a central GitHub account) using the same application, and these would be displayed under the description, a community snippet repository.

That would keep everything together. Some aspects of the documentation will go stale at certain points in time. But if it's all packaged together, easily accessible, easily editable, then perhaps maintaining the docs would become part of our daily workflow, just like maintaining our own individual code snippets and bits of documentation, and folks would be updating it every day, all the time, because they use it every day, all the time.

I realize I'm only addressing the core documentation. It would be good to have another section that describes the language and how to develop applications in it, and for that, a wiki might be ideal.

[Mark Drew]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAFwR%2BKfoS7q0K_GxK3vXYBm9G-wvhbhcYYbxjwrvm1syBTiRDA%40mail.gmail.com.

[Adam Cameron]

On 16 February 2015 at 10:42, Nando Breiter <na...@aria-media.com> wrote:

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).

-- 

Adam

[Adam Cameron]

On 16 February 2015 at 10:53, Mark Drew <mark...@gmail.com> 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

 

[Tom King]

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

[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. 

[Michael van Leest]

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 <na...@aria-media.com>:

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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAGHrs%3D-K0SKhBR1V9nq9DcnMRXF%3DwBVQiU3Ju5NyvZ9ZeN0OuQ%40mail.gmail.com.

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

--

Michael van Leest

[Dan Skaggs]

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

--
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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/a3df604e-7795-4bdf-b5c4-2f5be12428b6%40googlegroups.com.

[Dominic Watson]

What might also be worth looking at is http://kapeli.com/dash. Offline documentation browsing and searching for Mac users. Compatibility with that system would be a bonus.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/24769609-E077-40ED-A3D6-8BEAA4AF95F6%40web-meister.com.

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

[Nando Breiter]

+ 1 on the Dash suggestion! In addition to making the Lucee docs conveniently accessible, it might also help introduce Lucee to a broad audience of developers.

[lu...@lesener.de]

Yes, support fort Dash would be awesome!

[Adam Cameron]

Let's focus on getting a main docs site of some description sorted out first.

Depending on how that is done, someone can run a side project to convert that to being Dash-ready. Having looked at scraping the CF9 docs from the Adobe site, it was structured well enough to just use CFHTTP and JSoup to extract the content into standardised JSON files, from which point it won't me very difficult to covert to Dash's format. So similar can be easily enough done from Lucee's docs when they're done. Or as a first step, someone could do what Mark's done with the Railo source in the past to generate the content for the Railo Docs site.

This does not have to be the business of The Lucee Association though (and shouldn't be).

Why doesn't someone who wants this format actually put their hand up and do something about it?

-- 

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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/276fd9bc-b257-4330-81d5-d81bf5acd592%40googlegroups.com.

[Adam Cameron]

On Tuesday, 17 February 2015 23:17:21 UTC+13, Dominic Watson wrote:

What might also be worth looking at is http://kapeli.com/dash. Offline documentation browsing and searching for Mac users. 

And Windows users: http://zealdocs.org/.

I use it, it's pretty handy.

-- 

Adam 

[lu...@lesener.de]

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.. :)

Point well taken. 

 

[Adam Cameron]

You worry about the docs... I'll worry about the rants. Deal?

;-)

-- 

Adam 

[Andrew Dixon]

Adam, I wonder if it is because people don't want to be duplicating effort. As far as I can tell from what I have read here Mark Drew is already working on a docs site and therefore it would seem silly to me (if I was thinking of doing it) to do it as Mark is already (as far as I know) doing it. If that is not the case then fine, Mark doesn't have an obligation to do it of course, but we still need some way of organising who is doing it don't we, or am I missing some sort of unwritten open source project protocol?

Kind regards,

Andrew

http://about.me/andrew_dixon

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/6498b2e2-5b0f-49ce-92b9-e86ecbf8f548%40googlegroups.com.

[Adam Cameron]

On 18 February 2015 at 08:12, Andrew Dixon <andrew...@gmail.com> wrote:

Adam, I wonder if it is because people don't want to be duplicating effort. As far as I can tell from what I have read here Mark Drew is already working on a docs site and therefore it would seem silly to me (if I was thinking of doing it) to do it as Mark is already (as far as I know) doing it. If that is not the case then fine, Mark doesn't have an obligation to do it of course, but we still need some way of organising who is doing it don't we, or am I missing some sort of unwritten open source project protocol?

My point was more that we need ppl to go "I will do this..." rather than "I want someone else to do this...".

In this case a person could put their hand up and say "right, best I talk to Mark", or simply "OK... I'm gonna get this done... where should I start?"

-- 

Adam

 

[Mark Drew]

I won't have a chance to look at the docs site stuff till next week. I can share what I have so far with someone tomorrow ( need to add it to a repo)

Mark Drew

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/254f05e5-f721-4eaf-a498-40631ec4abeb%40googlegroups.com.

[ADK]

I don't work with many OS projects directly, but I do so with non-profits and what is standard is for goals/objectives to be set (e.g. documentation, website, marketing, etc.) and then for certain people to chair those ideas and form committees to fulfill them.

In that way, there is an understood vision, top-down, of what the goup is tryin gto do with "docs" and people who are interested in helping with documentation know who to go to to help out and that chair will likely have a punch-list of items that need doing. This also allows for curation - which is definitely important for something like documentation in the form of proper editing, especially with people from all over the planet contributing.

While I agree with Adam saying he is looking for someone to say "I will do this" it's a bit of a free-for-all right now. People have different capabilities and time constraints, having a bit more organization may help those willing to do "something" - but not sure what to do - grab some of the low hanging fruit tickets and contribute. The more they do that, the more likely they'll get comfortable tackling more tickets or more advanced tickets.

There's definitely a sense of Wild, Wild West at the moment so it's hard to jump in and commit without understanding scope...

[Risto]

> And Windows users: http://zealdocs.org/.

Didn't know about that and Linux users too - thanks Adam!

[Risto]

Stupid question of course, but Dash/Zeal already have Coldfusion docs. Couldn't that be duped and then remove stuff Lucee doesn't support and add additional stuff Lucee does support?
Seems like a quicker way to get a nice documentation set for Dash/Zeal.

[Adam Cameron]

On 18 February 2015 at 09:02, ADK <and...@leftbower.com> wrote:

While I agree with Adam saying he is looking for someone to say "I will do this" it's a bit of a free-for-all right now. People have different capabilities and time constraints, having a bit more organization may help those willing to do "something" - but not sure what to do - grab some of the low hanging fruit tickets and contribute. The more they do that, the more likely they'll get comfortable tackling more tickets or more advanced tickets.

Very true. I was more trying to encourage a mindshift in the community wherein as well as suggesting stuff, ppl can do stuff too.

People are clearly wanting to help with the docs, and I think there are a bunch of volunteers waiting. What's kinda letting us down currently is the steering from The Association. TBH. To victimise Mark slightly (sorry mate) to demonstrate a point, I'd prefer if he didn't jump ahead and start his docs project before there's a decision that that's the way things should go, and I think that decision should come from the (unhelpfully quiet) Lucee Association. They don't leave the decisions on how the language is implemented to just anyone, they have Micha et al to steer it. They ought to be taking the same approach with other stuff like the solution for the docs, the solution for the website, etc. They don't need to do the actual work, they just need to marshal it. Then the community can get the work done.

-- 

Adam

[Adam Cameron]

On 18 February 2015 at 09:34, Risto <ck.web...@gmail.com> wrote:

Stupid question of course, but Dash/Zeal already have Coldfusion docs. Couldn't that be duped and then remove stuff Lucee doesn't support and add additional stuff Lucee does support?
Seems like a quicker way to get a nice documentation set for Dash/Zeal.

And could possibly become the basis for the content on the full docs website too.

(although there's push back as to whether this should be automated (to save developer time), or done by hand (to be actually useful)).

-- 

Adam

 

[Dominic Watson]

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.

--
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+un...@googlegroups.com.
To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAFwR%2BKchH4BxGciv_0JX%3DXukNGdTp7THXkYSSoMCzRRJCr--Og%40mail.gmail.com.

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

[Jim Priest]

Agree with Adam and Dominic. Seems some research and discussion (started here) would be beneficial before jumping into a solution.

If it's easy to update I believe more people will.  Wiki edits are easy - for example FW/1.  Click. Edit. Save. Done. 

If I have to pull code, edit, submit a merge request etc. that unfortunately probably is not going to happen.

Not sure why we have to reinvent the wheel here - what are other languages doing for docs??

Never heard of Dash/Zeal before but that looks incredibly useful!! 

Jim

[Adam Cameron]

On 18 February 2015 at 10:49, Dominic Watson <dominic...@pixl8.co.uk> 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

[Andrew Dixon]

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
mso - Lucee - Member

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@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.

[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
mso - Lucee - Member

[Michael van Leest]

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

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAG1WijVXHddkssCxa_izPxkNQ0zWQxP%3DN6kOBWJUW3WLFDZpxA%40mail.gmail.com.

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

--

Michael van Leest

[Adam Cameron]

On 18 February 2015 at 19:42, Michael van Leest <mvan...@gmail.com> 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.

[Andrew Dixon]

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
mso - Lucee - Member

--

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+un...@googlegroups.com.
To post to this group, send email to lu...@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.

[Nando Breiter]

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 :-)

[Mark Drew]

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 

[Mark Drew]

Also, here is the dashdocs that Andy Jarrett and I did:

https://github.com/andyj/dash-docset-railo

regards

Mark Drew


develop • deploy • deliver
http://charliemikedelta.com

--
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.
To unsubscribe from this group and all its topics, send an email to lucee+un...@googlegroups.com.

To post to this group, send email to lu...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/efa92ff3-b784-4a54-a556-8ddb9cdde05b%40googlegroups.com.

[Dan Kraus]

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