search

phusion / passenger_library

Phusion Passenger documentation
https://www.phusionpassenger.com/docs
Other
48 stars 113 forks source link

Improve documentation on environment variables #6

Open FooBarWidget opened 9 years ago

FooBarWidget commented 9 years ago

See the discussion at https://github.com/phusion/passenger/issues/1612

serkandurusoy commented 9 years ago

Two main questions:

1) How to contribute to the library if one can improve the content related to, say, nginx, but not its apache counterpart even though it requires similar improvement?

2) Would we want something like this to make the search more visible/approachable

FooBarWidget commented 9 years ago

1) All content are generated from template using parameters. There are <% if %> statements inside the templates that check whether the current context is Apache or Nginx, and output different content based on that. For example, https://github.com/phusion/passenger_library/blob/af3a814d2f7e7de63eb7ac87f7decf5938786154/source/config/tuning_sse_and_websockets/tuning_sse_and_websockets.md.erb#L12-L24

2) I don't know how to apply that without making the whole experience annoying.

serkandurusoy commented 9 years ago

Quick note on 2) You do have a point there which I agree, but please also check the original issue out for context.

Now the main point. To clarify my original question with a pseudo-example;

<% if integration_mode_type == :nginx %>
  You should change foo to bar to get nginx to work with baz.
<% else %>
  -- I know apache can work with baz just like nginx does, but I don't know how to configure it!!
<% end %>

I'd like to contribute, but my experience is around Meteor and specifically with the nginx integration mode.

So I have some pointers and explanations that I can add to the documentation, but I can only do that in the meteor related sections of the nginx integration mode documents, but I am not able to provide the same information as it should apply to either standalone or apache mode.

And I believe this is a valid concern for anyone who'd like to contribute to the library.

If we don't pay attention to keeping counterpart sections as alligned as possible, in time, some parts of the documentation will grow while other parts stagnate.

What is your proposed workflow to mitigate this?

FooBarWidget commented 9 years ago

Just contribute the Nginx-specific parts and mark the rest as TODO. We'll see wether we can fill in the blanks.

serkandurusoy commented 9 years ago

Great! Will do!