Is the Atlassian decision to prevent comments on developer documentation Wiki a good one?

Sorin Sbarnea (Citrix)
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
November 21, 2012

Is the Atlassian decision to prevent comments on developer documentation Wiki a good one?

I was surprised to find out that Atlassian decided to drop comments on the documentation wiki. Instead they added a recommendation to use answers.atlassian.com for questions regarding the documentation.

I'm not aware about all reasons for which Atlassian made these decision but my humble opinion is that this is huge drawback for accessibility and usability, ability to properly inform the users and developers and finally the ability to improve the documentation.

Having comments at the right place is the optimum way of getting feedback, people can add missing information or ask for clarification, things that technical writers at Atlassian can solve, on the same page, and remove the comments after this.

Another important issue related to the documentation is the huge number of URLs which are keep changing based on which is the current version of the product:

  • The current documentation is on the beta releases - That's wrong, it should be only on *production* releases.
  • There is huge amount of incoming hyperlinks which do go to old versions. The web server should be configured to redirect these to current versions (that also helps teaching the search engines to give proper pagerank to the current pages, so you do not find obsolete pages when you are searching online).
  • Atlasisan should feel free to remove any comments that does not add value to the wiki page, something like "nice post for the about Confluence" is not needed, and if the number of comments that are not adding value is growing, it can be hard to read/distinguish the important ones.

Other questions related to accessibility:

  • Why to have so many atlassian websites, is there reason for not storing the developer documentation on the same site as normal documentation?
  • Is there a really good reason for not using http://stackoverflow.com for question regarding development on atlassian SDK, instead of http://answers.atlassian.com ? - from my experience in the last 6 months, I got better responses from SO, probably because the audience is also huge when compared to the one here. Many of the questions here could apply for other non-atlassian products so it would make sense to put the questions there.
  • Why we do not have SSO on atlassian websites, when we all know about Crowd, still I have tons of accounts on different websites, I don't even remember how many domains there are. If something like this exists, it's clearly not documented and there is no information about how to merge accounts.

Please share your view on this, I'm sure that Atlassian is interested in improving our experience as users or developers.

2 answers

1 accepted

Comments for this post are closed

Community moderators have prevented the ability to post new answers.

Post a new question

8 votes
Answer accepted
SimonS
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
December 4, 2012

We've debated this internally for awhile. In the end, we didn't want a bunch of silos or different places to post development questions. "Do I post this question on this development page where I have context, or do I post it on Answers where more people will see it?" Is a base question we're wrasslin' with.

For now, we aren't going to turn on comments for the developer docs. Instead, we're thinking of showing "related" Answers questions on the documentation pages. You can ask a question right on the page, so you have context, but the question will also show up in Answers so everyone can see it.

This idea is still in development, but we realize it is a problem for all the reasons you listed and we're working on a fix. Thanks for taking the time to articulate your concern - we're listening!

Let me tackle your other questions too, we have some good (I hope!) reasons for them.

Why to have so many atlassian websites, is there reason for not storing the developer documentation on the same site as normal documentation?

A couple reasons for this one.

  1. Our regular documentation site is huge. We don't want to make it bigger by adding all of the developer documentation
  2. The developer site is custom-skinned with a plugin, something we can't do on the regular doc site

Is there a really good reason for not usinghttp://stackoverflow.comfor question regarding development on atlassian SDK, instead ofhttp://answers.atlassian.com? - from my experience in the last 6 months, I got better responses from SO, probably because the audience is also huge when compared to the one here. Many of the questions here could apply for other non-atlassian products so it would make sense to put the questions there.

This is a very good question, and unfortunately the reasons aren't as easy (and a little political).

  1. Stack Overflow is co-founded by Joel Spolsky, who also creator a JIRA competitor FogBugz. I've read some of Joel's stuff and many of us here like and respect him, but it is unlikely that you would ever see an ad for JIRA on SO for example.
  2. Related, we don't have any control over SO. Over badges, karma gain and loss, moderation, announcements, things like we have in Answers.
  3. We mine the Answers database to see trends, how we could improve, etc. This would not be possible using SO.

If you dig deep enough, you'll see that a while ago I actually tried to create an "Atlassian" Stack Exchange site as part of the pilot program SO has. I've advocated for moving to SO for the reasons you stated. In the end, though, Jeremy convinced me that keeping it in-house will better serve you guys as well as us. *phew!*

Why we do not have SSO on atlassian websites, when we all know about Crowd, still I have tons of accounts on different websites, I don't even remember how many domains there are. If something like this exists, it's clearly not documented and there is no information about how to merge accounts.

You're right, and honestly it is embarassing for a company that sells a SSO product to force you all to create various accounts for all of our sites. This is a big priority for us and hopefully we can announce a merger of these accounts sooner than later.

In any case, thank you again for taking the time to articulate all this, Sorin. I wish I could tell you more, but we've heard concerns like this for a long time and we're starting to address them. We're also planning on providing a "meta-Answers" site where you guys in the community can post speculative questions like this and get a discussion going that has a greater impact than the simple "question/answer" format we have now. There is a sub-Reddit on Reddit.com that was started recently, but hasn't had much activity. http://www.reddit.com/r/atlassian. I'm hoping to get moderator status on there soon (it was created by someone outside Atlassian) and hopefully breate some life into that area.

Also sorry that no one has responded to this until now. Let me know your concerns though, anytime.

-Simon

2 votes
m
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
December 5, 2012

Sorin,

Thank you for posting about comments and why you like them. You said:

I'm not aware about all reasons for which Atlassian made these decision but my humble opinion is that this is huge drawback for accessibility and usability, ability to properly inform the users and developers and finally the ability to improve the documentation.

Having comments at the right place is the optimum way of getting feedback, people can add missing information or ask for clarification, things that technical writers at Atlassian can solve, on the same page, and remove the comments after this.

These are great points and exactly the arguments the writing team makes when wanting to turn on comments.

You can imagine that keeping up with all the programming documentation for the platform and then indivdiually for each product is a huge task. While many engineers, consultants, and writers contribute to the documentation, not everyone is tasked with maintaining docs or responding to comments. We have a team of 2 writers dedicated at present to creating new and maintaining existing documents. Unfortunately, that team is two small to incorporate or respond to all the comments that were on the DAC site. That is why we turned them off in favor of Answers.

We are investigating ways of producing good documentation with a small team. Currently, we are working through the SDK portion of the documentation. Our goal is to reduce the number of pages and increase the usability of what is there. So, as we add the new material, we are turning comments on for those new sections. Two new sections have comments turned on: Set Up the Atlassian Plugin SDK and Build a Project and Writing and Running Plugin Tests.

We also realize the new stuff could be faster so we are in the process of hiring writers for the San Fran office and Sydney office. Please feel free to recommend anyone to us you think would be great.

TAGS
AUG Leaders

Atlassian Community Events