Plots2: Make Installation Instructions More Clear

[waqargithub]

Please describe the problem (or idea)

I find the information given across readme.md and readme.environment to be confusing and, at times, conflicting.

1. I am not sure if information in readme.environment is still current and whether this file is still to be used.

2. I think having one consolidated file with all installation related instructions would provide a clearer path to install and set up the environment.

What happened just before the problem occurred? Or what problem could this idea solve?

This idea could make installation instructions clearer for people trying to join this project.

What did you expect to see that you didn't?

I expected to see one file that would have installation instructions, and required revision numbers.

Please show us where to look

https://github.com/publiclab/plots2/blob/master/README.environment

https://github.com/publiclab/plots2/blob/master/README.md

What's your PublicLab.org username?

waqargithub

This can help us diagnose the issue:

Browser, version, and operating system

Many bugs are related to these -- please help us track it down and reproduce what you're seeing!

---

Thank you!

Your help makes Public Lab better! We deeply appreciate your helping refine and improve this site.

To learn how to write really great issues, which increases the chances they'll be resolved, see:

https://publiclab.org/wiki/developers#Contributing+for+non-coders

[waqargithub]

I am happy to work on this issue with someone from the project team.

[jywarren]

Hi, @waqargithub thank you! We'd love to come up with a list of things that could be improved. @publiclab/reviewers this kind of input is really valuable as we've seen the site and docs for long enough that we forget what it's like to see them with fresh eyes.

We used to have a very long README.md, but we heard from people that it was bewildering. So now we have most of our docs in /doc/.

https://github.com/publiclab/plots2/blob/master/README.environment is indeed VERY old. I think we should perhaps just point it to the main README.md and the /docs/ files?

[waqargithub]

Thanks for being open to the suggestion!

I am a user experience nut and will happily share my experience and thoughts. I have begun to jot down notes about where I ran into issues. I will ask questions and then add more info (rather than giving feedback about obsolete files).

a) I see multiple files in different locations, which has potential for confusion. Which files are obsolete, and which are are still in use? I see these files:

https://github.com/waqargithub/plots2/blob/master/README.environment
https://github.com/waqargithub/plots2/blob/master/README.md
https://github.com/publiclab/plots2/wiki/Simple-Installation-for-Cloud9

https://github.com/waqargithub/plots2/blob/master/doc/README_FOR_APP
https://github.com/waqargithub/plots2/blob/master/doc/PREREQUISITES.md
https://github.com/waqargithub/plots2/blob/master/doc/TESTING.md

Are there others I am missing?

b) Can the obsolete files be (in order of preference):

• Deleted altogether (to avoid people clicking on an obsolete file)?

or

• Moved to a folder named obsolete (so people don't see them or know immediately they are obsolete)?

or

• Clearly identified as obsolete at top of the file (and perhaps a pointer to where they should go for current information)?

c) It seems that README.md is still to be used (if not then the point about deletion applies to it) but people should first go to the docs folder. Someone new will begin to look for information at the top folder level and may not know to look in the doc folder, especially when they see the README files at the top level. I think a consolidated __Getting Started_ file (or some other intuitive name that would catch the eye of someone looking for information for how to get started) or a __Getting Started_ folder that it appears at top level and near beginning of the list of files and folders would help. Example content could be:

How You Can Help

...

When you have selected your first issue or are otherwise ready to contribute to the project:

1. Fork and clone the publicslabs/plots2 repository by following these steps.
2. Decide whether you will use a workspace on Cloud9 (a cloud-based programming environment), or whether you will work with the code on your own device. Need help deciding? Click here.

Instructions for Creating a Development Environment on Cloud 9

1. Request an invite by emailing __.
2. Click on invite link in the email you will then receive and create an account on Cloud9.
3. Create a new workspace and paste...

Instructions for Creating a Development Environment on Your Machine

1. Get the system prerequisites by following theses steps (<-linked)
2.

Instructions for Testing

This file could invite suggestions from new users and be updated and maintained via pull requests.

d) One way to avoid one file from getting too large or busy is to use links to other documents, or use dynamic html with headings that allow a user to expand and collapse sections. Perhaps that could be done as an html document hosted elsewhere (if it cannot be easily achieved here), and a file here could host a link to it.

It may sound like the work needed for this issue is adding up. I think the work that is needed could be done by people looking to contribute to open source projects. I know I would be open to helping with these issues.

Waqar

[siaw23]

i very much agree with @waqargithub, file organisation and instruction are a bit discouraging. i also feel we should remove unused README's, keep a current, brief one at the top level. i have seen this in the main README for example:

(optional, not recommended) Install solr engine rails generate sunspot_rails:install
(optional, not recommended) Start the solr server in foreground by using bundle exec rake sunspot:solr:start
(optional, not recommended) Index your search database in solr server using bundle exec rake sunspot:reindex

well, if it's optional and not recommended why do we need it to be in there? @jywarren

[icarito]

Agreed - thank you for your insight. We would like Plots2 to be generally useful but at the moment things like these need some work as they suit our deployment. We've deprecated using Solr so those are obsolete. Any further pointers to issues installing are very welcome.

[jywarren]

Let's make a checklist! Many of these could be completed as part of
first-timers-only issues. Removing Solr from the readme is a great example.
Same with unused readmes! This will be a continuing process but thanks so
much for listing these out -- let's start to chip away at them!

On Sun, Apr 29, 2018, 9:18 PM Sebastian Silva [e-mail]
wrote:

Agreed - thank you for your insight. We would like Plots2 to be generally
useful but at the moment things like these need some work as they suit our
deployment. We've deprecated using Solr so those are obsolete. Any further
pointers to issues installing are very welcome.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/publiclab/plots2/issues/2616#issuecomment-385297717,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABfJwpz2Bw3In2vmn5mztDhWjfZHZAbks5ttmZHgaJpZM4TVLJD
.

[jywarren]

And apologies for returning to this a bit late! @souravirus if you'd like
to use one of these as an opportunity to try making a first-timers-only
issue, I'd be happy to help review it. Thanks everyone!

On Tue, May 15, 2018, 1:10 PM Jeffrey Warren [e-mail] wrote:

Let's make a checklist! Many of these could be completed as part of
first-timers-only issues. Removing Solr from the readme is a great example.
Same with unused readmes! This will be a continuing process but thanks so
much for listing these out -- let's start to chip away at them!

On Sun, Apr 29, 2018, 9:18 PM Sebastian Silva [e-mail]
wrote:

Agreed - thank you for your insight. We would like Plots2 to be generally
useful but at the moment things like these need some work as they suit our
deployment. We've deprecated using Solr so those are obsolete. Any further
pointers to issues installing are very welcome.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/publiclab/plots2/issues/2616#issuecomment-385297717,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AABfJwpz2Bw3In2vmn5mztDhWjfZHZAbks5ttmZHgaJpZM4TVLJD
.

[Souravirus]

I would be happy to make my first first-timers-only issue. So, what should I start with? Is that making issue for removing Solr from the readme?

[Souravirus]

Hey @jywarren, I made the first-timers-only issue on removing of the obsolete code of README.md in #2729. Please check it out once.

[grvsachdeva]

Hi everyone, thanks for great suggestions. I think in a year, we have improved a lot and so closing this issue. But, you are always welcome to open a new issue, if you want to add on a new suggestion/ highlight an issue/bug.