Issue Details (XML | Word | Printable)

Key: CONF-10357
Type: Task Task
Status: Closed Closed
Resolution: Fixed
Priority: Major Major
Assignee: Sarah Maddox [Atlassian]
Reporter: Benjamin Naftzger [Atlassian]
Votes: 1
Watchers: 1
Operations

Add/Edit UI Mockup to this issue
If you were logged in you would be able to see more operations.
Confluence

Update the Confluence installation and setup documentation

Created: 02/Jan/08 10:49 PM   Updated: 16/Mar/08 08:18 PM
Component/s: Documentation
Affects Version/s: 2.7
Fix Version/s: None

Time Tracking:
Issue & Sub-Tasks
Issue Only
Not Specified

Issue Links:
Part
 
Reference

Participants: Benjamin Naftzger [Atlassian], Ivan Benko [Atlassian] and Sarah Maddox [Atlassian]
Since last comment: 37 weeks, 1 day ago
Resolution Date: 16/Mar/08 08:18 PM
Labels:

Sub-Tasks:   All   Open   
1.
 Clarify the old Documentation Home page Sub-task Closed Closed Sarah Maddox [Atlassian]  
2.
 Clarify old page Setting Up Confluence Sub-task Resolved Resolved Sarah Maddox [Atlassian]  
3.
 Please review updated Confluence EAR-WAR guide Sub-task Closed Closed Matt Ryall [Atlassian]  

 Description  « Hide
We need to dramatically improve the quality of our install and configuration documentation that is seen and used by our new customers.

We did a great job with improving the templates for our release notes and I would love to see us take a similar approach to our core 'getting started' documentation (install guides, admin guides, etc.).

Guidelines for the improvements are:

  • the pages need to be much more readable. They are currently laborious to read;
  • remove the comments (and factor of the useful ones in )
  • create easy to follow sections (numbered sections perhaps?)
  • create clear buttons to proceed to next phases of the documentation (look at the poor quality of the next links on the Confluence Installation Guide below the Standalone and EAR/WAR tables
  • encourage users to evaluate using the standalone version until they are satisfied with the product functionality
  • direct users to commonly performed tasks
    • setting the application as a service
    • setting up LDAP integration
  • we should consider having two install guides (one for simple evaluations, and another for production ready evaluations)
  • the setup and install guides should most likely be combined
  • moving to the next logical part of the documentation versus moving to a potentially related area (as denoted by the Other Topics and Related Topics headings) should be represented as clearly different types of paths
  • the Security Warning seems over the top and serves to cause confusion and hassle more than any practical value (http://confluence.atlassian.com/display/DOC/Confluence+Setup+Guide)
  • use more screenshots and visuals, especially when discussing retrieving license keys
  • the process to retrieve evaluation keys has changed, this needs to be updated on relevant pages e.g. http://confluence.atlassian.com/display/DOC/Standard+Installation
  • some pages seem to be very short. It would perhaps be wiser to have longer pages that require less page loading and clicking e.g. http://confluence.atlassian.com/display/DOC/Standard+Installation

 All   Comments   Work Log   Change History      Sort Order: Ascending order - Click to sort in descending order
[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 07/Jan/08 04:44 PM
Can we change the title to refer to Confluence only? The JIRA documents are separate, and have their own JAC project.

[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 07/Jan/08 11:03 PM - edited
Requires changes to at least the following pages:

Requirements:
http://confluence.atlassian.com/display/DOC/Confluence+Installation+Guide
http://confluence.atlassian.com/display/DOC/Server+Hardware+Requirements+Guide
http://confluence.atlassian.com/display/DOC/Supported+Platforms+FAQ
http://confluence.atlassian.com/display/DOC/List+Of+Supported+Application+Servers

Configuration:
http://confluence.atlassian.com/display/DOC/Configuration+Guide
http://confluence.atlassian.com/display/DOC/Start+Confluence+automatically+on+system+startup
http://confluence.atlassian.com/display/DOC/Application+Server+Configuration

Installation:
http://confluence.atlassian.com/display/DOC/Confluence+Installation+Guide
http://confluence.atlassian.com/display/DOC/Installing+Confluence+Standalone
http://confluence.atlassian.com/display/DOC/Set+JAVA_HOME+variable+in+Windows
http://confluence.atlassian.com/display/DOC/Change+listen+port+for+Confluence+Standalone
http://confluence.atlassian.com/display/DOC/Installing+the+Confluence+EAR-WAR+edition

Licensing:
http://confluence.atlassian.com/display/DOC/Get+A+Confluence+Licence

Setup wizard:


[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 22/Jan/08 08:24 PM
List of links to the docs from Confluence:
http://extranet.atlassian.com/display/TECHWRITING/Confluence+help+links


[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 11/Feb/08 03:01 PM
Have requested some pretty numbers for installation/setup steps — see https://extranet.atlassian.com/jira/browse/UI-330

[ Permlink | « Hide ]
Ivan Benko [Atlassian] added a comment - 26/Feb/08 02:37 PM
as per https://support.atlassian.com/browse/CSP-16050?focusedCommentId=213173#action_213173

Sure.

I think the biggest problems that I had were a lack of information and the lack of order in the documentation. I had to skip around a lot, and do a lot of Google searches and follow other's directions. The standalone is easier, but the initial install didn't work because I didn't have the MySql drivers installed, which I didn't see that I needed. Once I installed them, I was fine. Maybe that could be included in the installation? I don't know the licensing.

I am a Mac user most of the time, and get frustrated easily if I have to go through everything again. I think that installs should be simple. Running a shell script is fine with me. Installing Webmin is simple and I would like to see something like that. Another example is Web Help Desk, http://www.webhelpdesk.com where they have a installer that installs all the components and starts the server. It's developed in WebObjects and runs under Tomcat. No manual text file configuration. That's the kind of installation that makes me happy.

Maybe if you had a full step-by-step installation guide to print out. Don't miss anything (as much as possible).


[ Permlink | « Hide ]
Benjamin Naftzger [Atlassian] added a comment - 26/Feb/08 03:22 PM
Ivan,

Great feedback.

Can you please create a separate ticket to investigate the inclusion
of the MySQL drivers in JIRA & Confluence?

B


[ Permlink | « Hide ]
Benjamin Naftzger [Atlassian] added a comment - 26/Feb/08 05:44 PM
Ahh ok. Thanks mate.

B


[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 10/Mar/08 11:39 PM
I have updated the Confluence Setup guides — see this page.

Everything is now on one page, with table of contents at top plus good demarcation of sections.

I have had to leave the child pages in place, because they are referred to from external sources i.e. from the Confluence Setup application itself. Solution is that the content from the child pages is included in the main Setup Guide via exerpt-include macro.

The Installation guides will follow — they are affected by the new Confluence 2.8 installer for the Standalone edition.


[ Permlink | « Hide ]
Benjamin Naftzger [Atlassian] added a comment - 10/Mar/08 11:51 PM
Hi Sarah,

Looks great. Nice improvements.

One small suggestion. We should be a little stronger about the fact
that HSQL is for evaluation purposes and should not be used in
production (in section 3. Option 1). We need to make this message
stronger within the product too. I had specific feedback on this point
from a customer at SD West last week actually that they hadn't picked
this fact up after a year of running on HSQL. Perhaps rather than
hints and recommendations, we should say "NOTE: HSQL is suitable for
evaluation purposes only. Do not use HSQL in production environments"
Something just a little stronger.

B


[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 11/Mar/08 12:06 AM
Done

[ Permlink | « Hide ]
Benjamin Naftzger [Atlassian] added a comment - 11/Mar/08 12:13 AM
Thanks!

B



[ Permlink | « Hide ]
Benjamin Naftzger [Atlassian] added a comment - 12/Mar/08 12:21 AM
Excellent work Sarah!

B


[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 12/Mar/08 12:26 AM
EAR-WAR guide substantially rewritten.
Sent to developer for review — http://jira.atlassian.com/browse/CONF-11050

[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 16/Mar/08 08:15 PM
EAR-WAR guide is complete and published.


[ Permlink | « Hide ]
Sarah Maddox [Atlassian] added a comment - 16/Mar/08 08:18 PM
I'm closing this issue now, and handing its completion over to the Confluence 2.8 tracking. See parent issue http://jira.atlassian.com/browse/CONF-9506 plus its subtasks.


Powered by Atlassian JIRA the Professional Issue Tracker. (Enterprise Edition, Version: 3.13.2-#335) - Bug/feature request - Atlassian news - Contact Administrators