An issue was raised through JIRA to add comments to the documentation website: [LD-33] - Lucee
This is something that I had considered doing previously but hesitated over. My feelings are that comments can become a maintenance burden and are not the proper way to enhance the documentation (raising issues, submitting pull requests and talking in the forums is preferred).
On the flip side, comments can be an easy way for people to get involved.
Would appreciate anyone elses views on the matter.
I’d avoid comments in favour encouraging a direct contribution to the docs themselves, and continuing efforts to make the process easier.
For example, GRAV push a link for the specific page to edit on GitHub.
We should link to Bitbucket to encourage an in promptu update through the web interface for casual changes. And a link to the specific contribution docs for things like tags/functions that need a little more explanation.
Both Bitbucket and Github will handle in promptu updates automatically by cloning, and creating a pull request (only to be shut down by the contrib bot for not signing the CLA; ha!).
Note; the more we hit up against the limitations of the Bitbucket API the more I think we should just weather the shake-up of a move to GitHub.
I agree with @modius. I have disabled comments from all box docs. People tend to abuse them and actually end up asking for support on them. I think encouraging for them to actually contribute and handle the issues at the mailing list level.
This was my thinking exactly. Provide clear links on every page on how to provide feedback and/or contribute directly.
I think this is preempting a problem that won’t exist for a very long time. How many comments are you expecting? I think it’s a legitimate theoretical concern, but probably not so much of a real-world one.
Take a look at the PHP docs. It’s all code examples, gotchas and tricks related to the element the page is relevant to. And it’s a goldmine of information.
However it’s not really the sort of thing that is “appropriate” for the main body of the docs, which would all ideally conform to a predictable standard, approach exampling in a uniform way, etc. Also the official section of the docs should not be expected to example every single variation of functionality usage, whereas this sort of thing can grown organically over time.
Obviously it requires curating, and there are a lot more people doing that job on the PHP project than are available on the Lucee one. But, at the same time, far fewer people are going to be attempting to contribute, so this will even out.
Considerations:
Yup. And - seriously - this should be a very significant consideration if you actively want participation from the hoi polloi of the CFML community, who - on the whole - are a curious over-entitled sensing bunch, who need more facilitation to pitch in than most.
I think @modius & @lmajano observations - where they differ from yours - are also theoretically legit, but being real-world addressed in an unhelpful way.
–
Adam
Another thing to perhaps think about here is to position the community input as “annotations” or “appendices” rather than “comments”. Both in your minds, as well as in how they would be presented in the docs. That’d probably mitigate a lot of the misuse of the system to make support requests or complaints.
I probably should have worded my initial Jira ticket better, so as to reflect that concept.
–
Adam
I have to side with Adam on this one in principle. I know I’ve often found help in the ACF doc comments where the main documentation body has fallen short, and for many contributing may just seem daunting. Is it not worth opening up to comments just so long as, should they just be grossly abused / take far too long to seperate the value from the rubbish, they are able to be disabled or removed ( as appropriate )
It’s not a healthy comparison. It’s impossible to update the Adobe docs. It’s not impossible to update the Lucee docs.
For every helpful comment there’s any number that are unhelpful. How do we version the comment list indicating those things that have been addressed without even more complexity.
Writing documentation is hard. Keeping it up to date is hard. I think comments make that process harder still, not easier.
Lets get a decent reference in place. Get a manageable workflow behind it to keep them up to date. And only then should we tackle whether or not comments add value.
But frankly, if @lmajano (the undisputed king of documentation) says comments don’t work, I’d be hard pressed to disagree with him.
What are you talking about? The Adobe docs are a wiki: of course one can edit 'em. One does need to sign-up to do so, but I edit them all the time (well: that’s overstating things. I update 'em whenever the need arises, but I made an update last week).
But what does happen is that people can’t be bothered going through the sign-up process, so they add a comment. From there one of the content editors deals with it.
And, I hasten to add, whilst far (far) from perfect, they’re a helluva lot easier to edit that what you guys have done.
This is even a reasonable orange flag for your community approach, perhaps. If people can’t even be bothered to create an account and simply press “edit” to make changes, they’re less likely to jump through SCM hoops I think. That said… the Lucee community is slightly more “let’s participate” than ColdFusion’s, I think. So let’s see.
Speaking for myself - and I like helping with documentation (Adobe, Wikipedia) - unless I can just press “edit” and do the edit, I’m not going to. I don’t like maintaining other people’s documentation that much. I’m not gonna say this is the way it works for everyone, but when I’ve observed to very capable and participatory people in the CFML community before that they could help out, and the only barrier is a sign-up, they’ve gone “nah, can’t be arsed”. But they will take the time to quickly jot something down in an inline note to advise someone else needs to do the work for them.
Dunno. That’d be something to be discussed and planned. It’s not the basis for not considering the idea as a whole.
I don’t think that makes a great deal of sense. IE: I don’t see the correlation between writing docs and allowing the community to easily annotate them.
I also am not sure that Lucee changes sufficiently frequently for there to be much of an update burden once the initial - monstrous! - job to put them in place is done. I actually think it’ll be a fairly lightweight job after the initial content load and kinks (which will likely need to come from the community) are ironed out.
No-one said “do it now”, Geoff. TBH, most of what you say above is a bit specious (and/or straw-man-ish) to boot. Can you please try to keep input here factually-based, and without relying on fictitious predictions of problems.
This is just a plea to authority. Just because Luis has been noted to write a lot (and “a lot” does not at all equate to “good”, btw) doesn’t mean he has any particular insight into how to community-based annotations & additions might work. And what he says kinda bears-out that perhaps he didn’t.
It’s worth saying again: can you please keep your input on-track and on-target, and actually offer points rather that rhetoric. It’s not helpful to the discussion.
–
Adam
My bad. I was referring to the old Adobe docs – ie. with only comments.
No, this is an observation by someone who has a lot of documentation projects where comments have not worked.
I will defer to your extensive experience in this area.
I’m going to put this on hold for now.
I totally agree that the engagement of the community needs to be improved and that comments directly in the page could help with this. However, at this particular point in time, while we are scrambling to get things up to scratch, we need to focus the resource that we have on getting to a stable point.
This is a really good article from an Atlassian technical writer: Should we allow comments on documentation pages | ffeathers.
The point she and others make is: yes, comments are messy - but handling communities and customers is messy, are you a customer focused organisation or not?
I think the answer to that has to be “we absolutely want to be” so let’s keep this in the plan but implement it when we have resource to deal with the comments and when there’s enough of a baseline documentation.
Let’s revisit when there is a stronger organisation behind the documentation (hopefully backed by multiple volunteers).
This topic is now opened. New replies are allowed. Apologies for the over hasty closing of the topic. I’d urge all participants to keep on topic and to refrain from repeating points that have already been raised.
technically speaking, what is involved with allowing comments? Is it just adding disqus? Why not allow comments for now and regroup if it becomes an issue? Give several people in the community the ability to moderate and clear guidelines of what is and isn’t expected - the problems will take care of themselves.
Technically not a problem at all. Just whether or not people really want them (I think we’re pretty clear on the merits and shortcomings of them).
I don’t care one way or the other about comments. I care about good documentation. Having a way to send typo, technical, or other types of corrections / additions to someone responsible is the important part. If that is a pull request I am fine with that.