Bug #6687
closed
[Documentation] Improve flow of manual installation guide
Added by Brett Smith about 9 years ago.
Updated about 9 years ago.
Assigned To:
Radhika Chippada
Description
Functional requirements:
- Every installation page is self-contained. Read top to bottom, it tells you how to go from a typical base distribution install to running the desired service.
- The installation guide flows linearly. If you follow it in order, when you get to the page where you install service X, you have already installed all the services that service X requires to function correctly.
Implementation:
- Get rid of the "Software prerequisites" section.
- For common components like RVM, Ruby, PostgreSQL, and nginx with Phusion Passenger, prepare Textile includes to describe how to install each one. Use these includes on the installation page for each service that requires them.
- For services, move them to the "Manual installation" section.
- Order the "Manual installation" pages as follows:
- Prerequisites
- SSO server
- API server
- Create standard objects
- Git server (arv-git-httpd)
- Keepstore
- Keepproxy
- Crunch dispatcher
- Compute node
- Shell server
- Workbench
- Cheat sheet
A note about scope: because you're making big changes to a lot of pages, you'll be tempted to fix every issue on those pages. Don't do it! Fixing every bug in the documentation is emphatically out of scope—we have plenty of other stories to address those.
- Description updated (diff)
- Assigned To set to Peter Amstutz
- Assigned To deleted (
Peter Amstutz)
- Assigned To set to Radhika Chippada
- Status changed from New to In Progress
51a7226a1cf217fe4ea41f6d1b111b55d396485d
- Updated the page order as listed in config.yml file
- The description lists "Create standard objects" in wrong place. I placed it after "Shell server"
- Converted ruby and rvm instructions, and postgres instructions into includes and included them at the required places
- Moved the postgres "If you intend to use specific versions of these packages ..." note from API install page into postgres include and removed nginx16 from it.
- Moved nginx pieces from api server and workbench pages into separate include files. There were quite a few differences between these two and even though there were a few paragraphs repeated, I felt it is probably easier maintain / update the whole api or whole workbench sections. I can break these into several reusable segments if so desired.
- Not sure what is meant by "For services, move them to the 'Manual installation' section." Didn't do anything about this.
Radhika Chippada wrote:
- Updated the page order as listed in config.yml file
- The description lists "Create standard objects" in wrong place. I placed it after "Shell server"
+1 to this, as we discussed.
- Moved nginx pieces from api server and workbench pages into separate include files. There were quite a few differences between these two and even though there were a few paragraphs repeated, I felt it is probably easier maintain / update the whole api or whole workbench sections. I can break these into several reusable segments if so desired.
I would actually suggest going the other way: if there's not enough in common between them to make a single template, let's revert the change and have this instructions directly in each relevant page. No point having the indirection of an include if we're only going to use it once.
- Not sure what is meant by "For services, move them to the 'Manual installation' section." Didn't do anything about this.
This was referring to moving the SSO server page into the main installation flow. So, you did what was required. I understand why this was vague, but in the future, I think it could help avoid heartache if you ask for clarification about points like these before starting a branch. That's the best way to make sure you don't end up doing work that doesn't get used. I'm trying to get better about writing well-specified stories, but I'm still learning and I'm not perfect. Mistakes like this happen.
Just a few small comments from here on 51a7226:
- The proper name of the software is PostgreSQL. In headers that refer to the software, let's call it that, instead of just "Postgres."
- Both the API server and Workbench pages have a "Build tools" section with an unordered list under it. This list made more sense when the page started with an overview of all the prerequisites to install. Now that each prerequisite has its own section like Ruby and PostgreSQL, this list isn't so useful: it just describes the packages that are going to be installed in the lines below. I think we should remove this list on both pages.
- In the API server's "Build tools" section, some of the packages listed to install here are redundant with the "Install Postgres" section above. To avoid this, please remove libpq-dev and postgresql from the apt-get line, and postgresql-server and postgresql-devel from the yum line.
Thanks.
Incorporated all the above suggestions. Thanks.
- Status changed from In Progress to Resolved
Applied in changeset arvados|commit:90071ec94bdc8bcbbfe6e5b2b2012863f27cd451.
Also available in: Atom
PDF