On 3/13/15 2:53 AM, Adam Cameron wrote:
...
> This just strikes me as a case of "if your only tool is a hammer, then
> everything looks like a nail". Except in your case your hammer is
> "code". It's also indicative of lack of requirements analysis and any
> sort of project management. The latter is the fault of the Lucee
> Association, I think, for at no point - that I can recall - putting
> their oar in and giving us some direction.
Well, we are coders. :)
I don't find it surprising that we make the right tools for the job.
Hammers would be cool tho-- can't wait until we can 3D print with metal
easier!
> The requirement is for a docs site. That's it. There is, currently, no
> requirement for it to be exportable in multiple formats. There is also
> no real requirement for the docs to be in sync with the source code...
> the docs simply /don't change often enough/ for this to be a necessity:
> 90% (at least) of the docs that were written for CF5 are still
> completely valid for CF11. Changes can be done by hand on the very rare
> occasions changes need to be made.
There's a book that's pretty old now, but is still solid gold, called
"The Pragmatic Programmer". It deals with a lot of the stuff you talk
about.
The docs and the source code relate, as the docs are about the source
code (thus they have to be linked somehow, if not directly, by version
number, etc.), and of course there's a requirement for them to be
exportable in multiple formats. I'd love to see other languages, even.
Lucee is way more active than Adobe, so there are different concerns,
especially regarding documentation. Lots of people are talking about
neat stuff like deprecation. I think that relates here as well.
> And the requirement is a reasonably urgent one. I don't see how Lucee
> can really be taken that seriously by anyone outside this little
> community who have just accepted if they need to look something up about
> CFML, they need to use Adobe's docs.
>
> Now I know that playing with code is far more fun than populating a wiki
> or a CMSed site or something, but it's also just a barrier to getting
> the job done.
Why do the job once, when you can do it a hundred times. =)
> All that other crap can be done down the track, if ever the requirement
> actually arises. And done by whoever it is that has that requirement.
>
> I think doing an initial import of the method/function/tag signatures
> into [something] would have been a great first step. Had this been into
> wiki or a CMSed site, we could have been /well/ on the road to loading
> in descriptive narrative (a lot of which could have come form the CF9
> docs) and code examples. Instead, we're still wringing our hands and
> playing with automation scripts, and the most we've got to show is the
>
luceedocs.org site which is, I'm sorry to say, only a little more useful
> as a chocolate teapot.
We've been down that road before, a couple times. Professing the idea
that this time it would have solved the problem is indicative of a lack
of requirement and resource analysis. Not that I'm some kind of paragon
of project management, mind you, I'm just say'n. ;)
I'm giving a golf clap for the chocolate teapot line though. =]
-Den