This goes back to my earlier position that trying to automate the docs,
and base them from the metadata in the source code is a fool’s errand
Entirely automating them on meta-data from the source code may be wishful
thinking, but automating them from some structured data (especially the
reference material), is a must IMO, and perfectly achievable. I’ve been
playing with some ideas with Mark to improve this situation and make this
work. Docs should contain more than just the reference material, have cross
references and be exportable to multiple formats. They should also be easy
to contribute to. Hopefully we’ll have something that meets all these
requirements soon so that we can move on with that in one direction.On 11 March 2015 at 10:37, Adam Cameron <@Adam_Cameron1> wrote:
On Wednesday, 11 March 2015 10:27:52 UTC, Jeroen Knoef wrote:
I think having really good documentation is far more important in terms
of the impression that Lucee makes on newcomers, on everyone in fact. Good
docs will draw folks in much more effectively than any anti-stigma
“strategy” we can come up with. It may not look like it, but to me, good
documentation is our real challenge.True…! And some code examples, like node.js’s on the homepage. Snippets
that make people say ‘hey this is nice, it does what I need in 3 lines. And
I can start in 5 minutes’.Yeah. The function/method/tag signatures that Mark’s automated docs
provide are a key part of docs, but for docs to be useful, they also
need (in order of importance, IMO):
- explanatory narrative
- examples
- community feedback & notes
I think the signatures would fit into second spot on that list.
This goes back to my earlier position that trying to automate the docs,
and base them from the metadata in the source code is a fool’s errand. It’s
handy for an initial import into [a larger body of work], but is not really
that useful as a end unto itself.For me, the Railo docs were never particularly useful, other than as
something to be served up from a URL to make it seem like Railo had docs.
If ever I needed to know how something in CFML worked, I needed to use the
Adobe docs. I guess the automated docs were useful to make clear where
Railo did / did not implement something which differed from ColdFusion. But
from there if one didn’t understand how the functionality worked, it really
relied on googling for stuff on blogs or Stack Overflow questions, and
Railo itself was very under represented there. Basically if whatever it was
one was looking at differed from ColdFusion, one was pretty much sunk,
short of asking a question on the mailing list.–
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/74083180-f689-4832-b6d3-a065fde70c70%40googlegroups.com
https://groups.google.com/d/msgid/lucee/74083180-f689-4832-b6d3-a065fde70c70%40googlegroups.com?utm_medium=email&utm_source=footer
.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 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