--
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.
--
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 ...
--
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.
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.
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.
--
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.
|
|
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 |
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAEYvUxmUrS9m-MV3NMbsC5FV9%3D-__%3DMxoGQF3x%2BUB_2k41EB0Q%40mail.gmail.com.
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.
--
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.
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.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAFwR%2BKfoS7q0K_GxK3vXYBm9G-wvhbhcYYbxjwrvm1syBTiRDA%40mail.gmail.com.
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.
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,
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.
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.
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.
--
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.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/24769609-E077-40ED-A3D6-8BEAA4AF95F6%40web-meister.com.
--
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.
What might also be worth looking at is http://kapeli.com/dash. Offline documentation browsing and searching for Mac users.
Why doesn't someone who wants this format actually put their hand up and do something about it?
--
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, 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?
--
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.
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.
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.
--
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.
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.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.
--
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.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/CAG1WijVXHddkssCxa_izPxkNQ0zWQxP%3DN6kOBWJUW3WLFDZpxA%40mail.gmail.com.
Confluence is more a internal documentation tool, not really a public system if I understand.
--
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.
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.
--
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 view this discussion on the web visit https://groups.google.com/d/msgid/lucee/efa92ff3-b784-4a54-a556-8ddb9cdde05b%40googlegroups.com.
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