ChiliProject is not maintained anymore. Please be advised that there will be no more updates.

We do not recommend that you setup new ChiliProject instances and we urge all existing users to migrate their data to a maintained system, e.g. Redmine. We will provide a migration script later. In the meantime, you can use the instructions by Christian Daehn.

Update/Improvement of Install Docs (Task #1221)

Added by Chris Dähn at 2013-02-02 02:35 am. Updated at 2013-03-08 07:30 pm.

Status:In Progress Start date:2013-02-02
Priority:Normal Due date:2013-02-28
Assignee:Chris Dähn % Done:

0%
Category:Documentation
Target version:-
Remote issue URL:

Description

Currently the docs for the installation are for CP 2.x

Open points:*

Content

  • update mentioned version numbers (3.x missing)
  • prerequisites: Apache missing, Debian: bad path /srv/www/ => /var/www/
  • select ONE install variant (move other to "expert options" section)
  • put all "aptitude" and "mkdir" commands together
  • deliver default apache config by script / as download
  • group all steps to a BIG LIST which can be simply worked through
    => explanations below the list (users just want to get things up fastly, for questions scrolling down to the docs is ok) ;-)
    => e.g. like ownCloud )
  • dont jump to often between different install pages (Linux -> Debian -> Admin Install Guide -> Bundler Install -> Admin Install Guide ...)
  • provide MySQL init script or run it by script *

Note:
I tried to use Vagrant, but Proxmox and comparable envs have problems with VirtualBox... so it would be nice to use existing Linux+Win installs with the convenience of Vagrant.
=> the Chef cookbook way is great - sadly I couldn't integrate that into existing environments :-(

Style

  • improve title font size/decoration for better readability
  • add more vertical spaces between paragraphs
  • increase font size
  • rounded corners for all boxes (to match theme layout in menus etc.)

History

#1
Updated by Chris Dähn at 2013-02-26 10:42 am

Fixing / overhauling of the Wiki editing (Liquid syntax) docs https://www.chiliproject.org/projects/chiliproject/wiki/Liquid_for_Editors based on the wiki page and the offical docs https://github.com/Shopify/liquid/wiki.

#2
Updated by Holger Just at 2013-02-27 12:55 pm

Thanks for striving to improve our documentation. This is in fact one of the areas where we can get much better. I have some comments for your ideas/goals

  • Install docs I'd keep it up to have only one authoritative install document for ChiliProject and keep that one the main document. In fact, about all of the OS-specific guides, or at least those written by me, explain how to install some dependencies (Ruby, RubyGems, Compiler, header files for certain gems) and then defer to the OS-neutral guide. I'm with you that we should probably skip the different Ruby variants and stick to one. Im just unsure which one is the best. While currently, all halfway-recent OSs ship recent-enough Rubies (i.e. some 1.8.7 variant), this might not be sufficient soon as we strive to deprecate 1.8.7 support soon. Also, I just haven't found a great way to keep the OS-specific guides up-to-date. But generally, I would try to reduce their number (i.e. at most one for each OS, not one for every version). These documents need constant maintenance. Reducing this (manual) maintenance effort should be one of the more-important goals here.
  • The "one big script, explanations below" idea" To me, this looks like is a rather sure way to a support nightmare as people will simply not understand what they are doing and will change/adapt things without knowing what a specific step does. I really would like to keep our current format of step with explanation. But as you said, I think we can improve the formatting and some of the copywriting.
  • Chef cookbook Vagrant isn't a requirement for Chef. In fact, the vagrant setup we provide is mainly intended to be used as a preview/quickstart. For production use, it is recommended, to use a "real" environment (with server-virtualization if required) and install Chef there.

And finally for the liquid documentation: Is much better than most of the rest of the system, mostly because it is rather new and I try to document as many of the things I touch as possible nowadays...

(Also, I pulled this out of 3.8.0 as this is not a blocker for the next release)

  • Target version deleted (3.8.0)

#3
Updated by Chris Dähn at 2013-02-27 11:04 pm

There are some more points to discuss - because CP is not the first project facing the "expert install install" and "where are the docs?" problems - e.g. with Trac we (my colleagues and I) faced the same probs... very well described by the C't magazine ;-)

I would like to discuss some ideas maybe in our native language (germanski) ;-) via irc / skype / phone etc - if you like. This makes it much easier to grow motivation (I'm currently facing a hughe mountain of works for docs etc.) and to understand our different views much better (and faster) :-)

Viele Grüße aus dem Hohen Norden!

#4
Updated by Candy Desriyanti at 2013-03-08 04:59 am

  • Assignee changed from Chris Dähn to Andrew Smith

#5
Updated by Holger Just at 2013-03-08 07:30 pm

  • Assignee changed from Andrew Smith to Chris Dähn

Also available in: Atom PDF