Discussion: how much guidance on local setup should README give?

[ckingbailey]

Carrying over discussion form PR #5

We've seen that it's not always safe to assume the contributor has NODE_ENV=development set in their environment variables. There is a brief note about this in the README. Should we offer more specific guidance on how to set this env var?

Some other related concerns I thought of are: should we point to some Webpack documentation for especially relevant configuration details, such as having different Webpack config files for different environments, or setting env vars in Webpack? Should we point to the docs for some of the React/Redux adds-on used here, such as Redux-Actions?

Regarding instructions on how to set NODE_ENV, there are many ways to do this and I don't think we should suggest a preference for any particular way. Also, how to do this is going to vary from system to system (on Mac/-nix vs. Windows, for example). One thought that I had is that we could link to a good tutorial on the subject. I found this blog post from Flavio Copes, but it doesn't really cover the options at all.

[plocket]

As far as guidance on setup goes, I think it depends on the audience, on how much guidance, and on how much time and energy you have. I see it this way:

Audience

If I want people to collaborate with me who are not familiar with these systems, I will have to spend more time on providing guidance well or on setting up the systems for them. I can explicitly say that this is one of many ways to do things.

If more experienced people don't like the guidance, they have enough experience that they'll do it whatever way they want. Maybe they can even come up with a better way to do it.

Amount of guidance

If one procedure will work on all (or most) systems, I'll tell people what that one way is. It doesn't really matter how many millions of other ways there are to do it.

If there is no single way that can work on all (or most) systems, then I have to spend time finding good documentation that is relevant to the specific step that I'm describing. The more inexperienced my audience, the more specific, relevant, and clear the documentation has to be. If there is no guidance like that out there, that's very sad. I dunno. I've often considered writing an article...

Bandwidth

The weakest link in my chain - if I don't have the time or energy, the documentation will be what it will be. I try to prioritize it, though, since I'd like to do a lot of collaborative work. Sometimes over writing code.

Anyway, as far as guidance on setting up this specific local environment goes, I'd understood that putting that variable in '.env' would work for any system. If it doesn't, then there isn't a point in telling people to do that. If we have a link to specific instructions for different systems instead, that could work. A link to general guides about environment variables probably won't be useful. If we want to give people pointers to learning materials in general, that can probably be in a different section.

Also, if neither of us has the bandwidth for any of that, then we just say that the people we're collaborating with will have to already understand this kind of system.

I think if we're looking for resources to link, though, we might want to look for something other than that linked article. The me of the past would have found it even more confusing. It seems to talk about setting a production environment, which means I should be in development already and shouldn't have to worry about this. Also, I'd wonder where the .bash_profile is that I should be editing? Also, I don't see where it discusses different systems.

I have a feeling you have a different take on this issue. To get at the nuances, it may be worth discussing in person and then documenting that discussion and its outcomes here.