Test our documentation for production environments setups

[Angamanga]

Intro 📖

We are continuously working with our documentation to provide a good and smooth experience when setting up the platform. In this ticket, we are asking for help to improve our documentation for installation for production environments.

Task ✏️

• Go to https://docs.ushahidi.com/platform-developer-documentation/v/set-up-the-developer-environment-for-ushahidi/set-up-your-developer-environment/setting-up-the-api-with-docker
• Follow the instructions and try to install the platform
• Document and write comments about the installation-process as comments below, it could be for example:
  • Confusing instructions
  • Errors you get that is not mentioned in the documentation
  • Do you get stuck somewhere and don't manage to get past a point in the documentation? Where is that?
  • Do you have to do things that is not mentioned in the documentation to make it work? Where and what did you do?
  • Anything else that comes to mind, suggestions, comments etc when reading through the docs.

Thank you for your time and help 🎉 🙏 🙇‍♀

[Angamanga]

@dariatsvetkova @treasurechristain Thank you for your suggestions! It is very useful, we'll review shortly 🙏

[Bilalshaikh15]

@Angamanga the setting up the project doc link is incorrect. I think the correct link would be this
https://docs.ushahidi.com/platform-developer-documentation/v/set-up-the-developer-environment-for-ushahidi/

[Angamanga]

@Bilalshaikh15 Thank you for noticing! I have updated the link in the description :)

[Codegirlemem]

I have followed the link above and tried setting up the API with docker and I got stuck at the "Install Make command for the OS you use (parses Makefile)"step. I cannot move past it. Unlike the installation of Docker and repo forking step that had clear step by step description on how to go about it, this step has no clear description and is very ambiguous.

The link attached takes the user to a page with a lot of links with no recommendation on which link to download and how to set up Make nor the differences in installation for the different OS that users may use. Even after downloading a file there was no way to know what to do next in installing the Make command.

[tubapervaiz1508]

Hi @Angamanga
I wish to work on this issue. I have completed the installation process of the platform. Can you please grant me this work.

[shalini1008]

Subject: Feedback on Ushahidi Platform Setup Documentation

Hello Anna Iosif,

I hope this message finds you well. I'm Shalini, and I've been going through the documentation for setting up Ushahidi's platform. Overall, it's a valuable resource, but I wanted to share a couple of points where I found the information a bit confusing.

1.Point 3: Installing Make (Parsing Makefile)

Suggestion: Specify the recommended version for Make to download. I propose mentioning either the latest version or a version above 4.0. This would help users ensure compatibility during the installation process.

2.Point 6: Make Start Command

Suggestion: Clarify that the "make start" command will only function if the Makefile is downloaded or integrated into the user's window environment. Providing this information upfront would prevent potential confusion for users during the setup.
I believe these adjustments will enhance the clarity of the documentation and make the setup process smoother for users. Your attention to these details is highly appreciated, and I thank you for your dedication to improving the user experience.

Best regards,
Shalini

[anjalichaturvedi]

Hello, I am Anjali Chaturvedi and this is my take on the installation process:

Confusing instructions

1. The installation of the Make command is indicated; however, it would be more understandable if the OS platforms that this instruction relates to are specified. If the user is not familiar with Make or is running an operating system where Make is not easily accessible, they may encounter difficulties.

Errors not mentioned in the documentation

1. Installation or configuration issues with Docker may occur for users. For typical Docker problems, it would be helpful to include troubleshooting advice or connections to relevant resources.
2. When attempting to access the API, users may run into issues if they have other processes open on port 8080. It would be useful to have instructions on how to handle port conflicts.

Getting stuck
If users are unclear about the function of the.env file or experience permission issues when attempting to create or alter files, they may become stopped at the phase of copying text from.env.example into.env.

Additional steps not mentioned

1. Depending on their particular deployment scenario, users might need to configure extra options in the.env file (e.g., database credentials, API keys). It would be beneficial to provide a template or example.env file with placeholders for these settings.
2. No instructions are provided on how to manage or stop the Docker container once it is operating. Providing guidance on the termination of the container would obviate the need for users to look for this information elsewhere.

Suggestions and comments

1. Users who face problems during installation would find it easier to use and less frustrating if there included a troubleshooting area with frequent faults and answers.

[Tanyadw]

Feedback and Suggestions for Improving the Installation Process Documentation

Hello , I'm Tanya Dwivedi
I went through the provided documentation to set up the development environment on my Windows system. While the documentation was helpful overall, I encountered some issues and areas where clarity could be improved. Here are my observations and suggestions for enhancement:

Confusing instructions:

• The installation of the Make command is indicated; however, those who are not familiar with Make can encounter issues while installing it. Users might be confused about which version is needed to be downloaded. To address this confusion, I explored alternative methods and found that Make can be installed more simply using Chocolatey.

• The provided link doesn't offer clear guidance on which Make command to download or how to proceed with the installation. Providing specific recommendations and instructions for downloading and installing Make for different operating systems would help clear this ambiguity.

For Windows Users:
Open PowerShell in administrative mode.
Run the following commands:

1. Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
2. choco install make

For Linux Users:
On Linux distributions, Make is typically pre-installed. However, if it's not available, you can install it using your distribution's package manager. For example, on Ubuntu or Debian-based systems, you can install Make using apt:

1. sudo apt update
2. sudo apt install make

For macOS Users:

Make is often included in the Xcode Command Line Tools package. we can install it by running the following command in the Terminal:

1. xcode-select --install
   After this we can verify Make installation by running: make -v

Errors not mentioned in the documentation:
Users may encounter issues with Docker configuration, especially regarding enabling the WSL 2 based engine. Providing instructions and guidance on configuring Docker properly will help users avoid setup problems.

1. In Docker, make sure to tick the use the WSL 2 based engine (windows home can only run the wsl 2 backend) if not tick by default then apply and restart to setup docker within WSL.
2. Users may encounter issues with Docker configuration, especially regarding enabling the WSL 2 based engine. Providing instructions and guidance on configuring Docker properly will help users avoid setup problems.

Points of Getting Stuck:

1. Users might get stuck at the step of enabling Windows Subsystem for Linux (WSL) if they're unable to locate the option within the Control Panel or if they encounter errors during the process. Providing detailed instructions or screenshots for navigating the Control Panel and troubleshooting common WSL setup issues would be helpful.
2. Unclear Function of .env File:
   Users may become stuck at the phase of copying text from .env.example into .env if they are unclear about the function of the .env file. The purpose of the .env file, typically used for configuring environment variables, may not be clear to all users. Providing additional explanations or comments within the documentation regarding the significance of the .env file and how it impacts the application's configuration could help users understand its importance and proceed with confidence.
3. some users might be confused while installing ubuntu ,here I have provided simple steps to install ubuntu.

• Go to the Microsoft store and download the Ubuntu app
• Launch the Ubuntu app. After downloading the app and launching it will require you to create a password
  These steps are straightforward, but users might encounter difficulties if they're not familiar with the Microsoft Store or Ubuntu app installation process.

Unmentioned Steps for Making it Work:

Additional configuration steps, such as setting up environment variables or configuring Docker settings, are essential for the proper functioning of the development environment but are not explicitly mentioned in the documentation. Providing a comprehensive list of prerequisites and additional setup instructions would prevent users from encountering issues due to missing steps.

Suggestions for Improvement:

1. Including troubleshooting steps and references for further guidance.
2. Including alternative installation methods or workarounds for common issues to accommodate users with varying setups and environments.
3. Providing video tutorials for an easy setup process could also be beneficial.

Thank you for considering my feedback. I believe implementing these suggestions will significantly improve the clarity and effectiveness of the installation process documentation.