Read and comment on our documentation - open to everyone!

[Angamanga]

Intro 📖

We recently updated our developer documentation for the Ushahidi platform. Any help with reading through, comments and suggestions are very helpful!

Task ✏️

• Go to https://docs.ushahidi.com/platform-developer-documentation/
• Select a part of the documentation you want to read through
• Read through and write your comments and suggestions as a comment in this issue.

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

[HMuhammad]

Read this page: https://docs.ushahidi.com/platform-developer-documentation/

Currently reads: Ushahidi is an open source web application for information collection, visualization and interactive mapping. It helps you to collect info from: SMS, Twitter, RSS feeds, Email. It helps you to process that information, categorize it, geo-locate it and publish it on a map.

Suggest Change to: Ushahidi is an open source web application for information collection, visualization and interactive mapping. It helps you gather info from: SMS, Twitter, RSS feeds, Email. Then you can process that information, categorize it, geo-locate it and publish it on a map!

[Jenniline]

Currently reads: Before you start coding, read through the Development & Code section to get started and to get help setting up your environment!

Suggested change to: Before you begin coding, read through the Development & Code section to get started and to get help setting up your environment!

Explanation Here Start can be replaced with begin. Both words pertain to the commencement of an action. However, Begin in this context gives more meaning. It will give readers the idea that before coding you must have gone through and understood very well the Deployment & code. And not give them the impression that you must read the Deployment & code only before you are about to write code. Which is the impression that the word "Start" gives

[Jenniline]

Currently reads: If you are a designer and want to contribute to Ushahidi, please contact the Ushahidi design team at design@ushahidi.com or through the Join the Ushahidi community section of these docs. While you are waiting for us to reply, start reading through our Design-docs.

Suggested change to: The word "through" after the design@ushahidi@.com should be removed.

Explanation The statement is not clear from that point. It does not also give the statement a clear sense and in conclusion does not pass the message.

[Jenniline]

Hi @Angamanga I have the Ushahidi platform-client and the API up and running. I used the installation using XAMMP on Ubuntu Linux. But before that, I encountered a lot of problems but I was able to find a solution to them. I will like to know if there is a section of the Documentation where I can add Possible issues one might face while setting up their environment and also Possible solutions to the issues?

[blossom-babs]

Hello @Angamanga can I work on this too?

[IfyN]

Hello @Angamanga can I please work on this? I would love to contribute to this? I am also an outreachy applicant.

[rowasc]

Hey folks. Totally. This ticket is mainly about checking out the docs and reporting issues with it. Everyone can participate :tada: thanks! @IfyN @blossom-babs

[mariehposa]

Note:

1. Issues are written in bold only.
2. Suggestions are written in bold and italics.

Page: https://docs.ushahidi.com/platform-developer-documentation/code-of-conduct

Currently reads: Like Ushahidi's staff base, Ushahidi's community is incredibly diverse. Ushahidi is dedicated to creating an inclusive environment for everyone, regardless of race, ethnicity, religion, color, national origin, age, disability (physical or mental), sexual orientation, gender identity, parental status, marital status, and political affiliation as well as gender expression, mental illness, socioeconomic status or background, neuro(a)typicality, or physical appearance.

Suggest Change to: Like Ushahidi's staff base, Ushahidi's community is incredibly diverse. It is dedicated to creating an inclusive environment for everyone, regardless of race, ethnicity, religion, color, national origin, age, disability (physical or mental), sexual orientation, gender identity, parental status, marital status, and political affiliation as well as gender expression, mental illness, socioeconomic status or background, neuro(a)typicality, or physical appearance.

Page: https://docs.ushahidi.com/platform-developer-documentation/contributing-or-getting-involved

Currently reads: Ushahidi is open source software created for the benefit of a large global community improving the world for themselves and others, holding governments accountable, and raising their voices to be more powerful together. As we see the COVID-19 pandemic wreak havoc globally, we have also seen a large interest and use of our tools. Today, we are reaching out to technologists everywhere to ask for your help to make Ushahidi Platform better. Head over to our COVID-19 specific page to learn more on how you can support us helping our users.

Suggest Change to: Ushahidi is open source software created for the benefit of a large global community improving the world for themselves and others, holding governments accountable, and raising their voices to be more powerful together. As we see the COVID-19 pandemic wreak havoc globally, we have also seen a large interest in the use of our tools. Today, we are reaching out to technologists everywhere to ask for help in making the Ushahidi Platform better. Head over to our COVID-19 specific page to learn more about how you can support us in helping our users.

[IfyN]

Please Note:

• Issues are highlighted in bold .

• Suggestions are written in bold and italics .

  Page in which text is derived: https://docs.ushahidi.com/platform-developer-documentation/contributing-or-getting-involved

Text currently reads: Ushahidi is open source software created for the benefit of a large global community improving the world for themselves and others, holding governments accountable, and raising their voices to be more powerful together. As we see the COVID-19 pandemic wreak havoc globally, we have also seen a large interest and use of our tools. Today, we are reaching out to technologists everywhere to ask for your help to make Ushahidi Platform better. Head over to our COVID-19 specific page to learn more on how you can support us helping our users.

Suggestion: Ushahidi is an open source software created for the benefit of a large global community improving the world for ourselves and others, holding governments accountable and raising our voices to be more powerful together. As we see the COVID-19 pandemic wreak havoc globally, we have also noticed a large interest in the use of our tools. Today, we are reaching out to technologists everywhere, asking for your help in making the Ushahidi Platform better. Head over to our COVID-19 specific page to learn more on how you can support us in helping our users.

[hyounes4560]

@rowasc @Angamanga Hi there, Please kindly review my contribution to The Ushahidi Platform Roadmap documentation page found here:

I made many changes and rewrote the complete sections to better reflect the Ushahidi platform. I proofread and checked the grammar and punctuation of my final draft. Also, used appended links under words to create a better-looking document. I hope this contribution will be helpful.

The Ushahidi Platform Roadmap Where to find our roadmap • We expand and modify Ushahidi's roadmap regularly based on the projects we have committed to working on, including various grant projects, customer requests, prioritized bugs, and features requested by the community. As we introduce more open roadmap planning strategies to our workflows, you will be able to access our upcoming roadmap shared on the public. • You can find features that we consider to add next to our roadmap using this tag consider for upcoming cycle • You can find the features we are currently working on by filtering using this tag

How a new item gets added to the roadmap • We evaluate new features' requests in collaboration with Engineering, Product, Design, Support, and other teams in the Ushahidi platform. • Ushahidi staff triage issues as they arrive. The following submission guidelines ensure that your feature requests and bug reports are appropriately described, well-understood and can be tackled: o Follow the issue submission guidelines. We have created some ready-to-use templates to report bugs and security vulnerabilities, or to request features, etc., which you can find here o You may receive follow-up questions from the team responsible for issue triage and prioritization. We accept you to respond to these questions as this will ensure the person triaging the issue can fully understand the scope of work and needs. o It helps to have a concise description, from a first-person point of view, of the problem you face and need to solve. • It's also worth noting that not all parts of the system are funded equally at any given point for feature development. This fact also influences when a feature will be prioritized and worked on by the Ushahidi staff. Funding for a specific goal (i.e. improve data triage process so that people can work more efficiently in an emergency) means our focus will generally be on a handful of improvements related to that goal.

How we decide to prioritize one issue over the other • For bugs, the decision is based on how critical the bug is, whether it is in a critical path to a specific function, and how common someone would run into this issue trying to execute this function. For example, triage issues are prioritized higher than problems in the webhook setup flows, since triage is a much more common action than webhook setup. Prioritization is also affected by the time necessary to fix an issue, the team available to fix it, and the required budget. • For features, we prioritize what we would like to see in the platform next with all of the Ushahidi team's help, their inputs as they interact with users, and user testing. • Alignment to Ushahidi platform goals, resources limits, and users' needs because it is essential to work on things that align closely with our mission. That means we will often have to say no to things that fall outside the product's scope or intent. For instance, while a calendar might sound like a great idea, it is not feasible to make a calendar from scratch since it is outside our product's scope and what we do best. Plus, we don't have the resources to maintain it. However, we may integrate an existing calendar if there was enough need for it. When you are requesting a new feature, we recommend that you clearly describe the problem you are trying to solve so that together we can figure out a solution that fits the Ushahidi Platform's scope.

Next steps We are working hard on improving how we prioritize issues and move them into our roadmap. The next steps start with internal discussions among Ushahidi staff on the rules of engagement on roadmap decisions and initial documentation about the new roadmap decision-making structure; then, we seek community comments. As we adjust our workflows to become more open and transparent for everyone, we want to hear from you and open up our process for comments shortly.

[kivuvarosekivuvan]

Hello @Angamanga as an Outreachy applicant 2024, I would love to work on this

[tubapervaiz1508]

Hello @Angamanga , I have completed the installation of the Ushahidi Platform. I would love you make meaningful contributions to the documentation. I request you to please grant me this work.

[Chiemezuo]

@Angamanga Here's my first comment. Sorry if it's bulky, but I tried to be thorough.

My review will be on my experience with the 'set up the developer environment' section of the document. For the workflow for adding code, most of my suggestions are grammar fixes and I would opt to do that in a different comment. In this particular comment, I'll focus more on setting up the API and the platform-client.

Setup Review

I'll be grouping this comment into the categories of:

• What my setup was already like before Ushahidi.
• What I liked about the docs.
• Errors I encountered and how I navigated past them.
• What could be worked on.
• Nice-to-haves (but not entirely necessary).

My already-existing setup

• Windows 11.
• Docker version 24.0.6 with WSL 2 enabled.
• Visual Studio Code.
• Git version 2.43.0 With autocrlf set to true (This caused some issues I'll discuss).
• GNU Make 4.4.
• Google Chrome 122.0.6261.94
• Node v21.2.0

What I liked

• Right away, I liked the simplicity of documentation.
• The easy navigation to other segments and the search option.
• The links to external resources.
• The success message to look for and call to action.

Errors I encountered

I faced a lot of errors which led to more errors.

• make start failed a lot initially for no seemingly identifiable reason. I got to realize it was because on my local machine it was saved using the CRLF EOL type. I converted appropriately.
• It still failed, because of the EOL types from artisan and docker-php-ext-enable were of the CRLF EOL type. I had to modify this.
• make start failed again because at some point in time, the platform service stopped running. I tried restarting the service several times, but it kept stopping. On going through the logs, I realized it was because of some errors in the scripts in the docker directory.
• Again, I noticed it was because of the EOL types, so I wrote a script to fix that problem. I did a cd docker, then ran find . -type f -exec sed -i 's/\r$//' {} \; to fix it, then I ran cd .. back to the parent directory, rebuilt and then ran the command again.
• It failed again some minutes after, but on confirming everything was running well, I realized it might have been because of a network fluctuation.
• At some other point in time, the services were not running for reasons I couldn't pinpoint. I retried a number of times and installed Php on my computer because it wasn't installed prior that.I did this, and somehow, it worked some time after(although I'm not sure if it was entirely because of that).

• On proceeding to the next stage: "setting up platform-client", I followed the guide and got an error when running npm run web:serve. It failed with a listen EACCES: permission denied ::1:4200 error. It wasn't because of the EOL this time around, and neither was it due to a faulty installation. Thankfully, I tried something I saw on Stackoverflow. I opened my Powershell, then ran the commands one after the other:

  net stop winnat
  
  net start winnat

• It was successful. I opened the http://localhost:4200/ on my browser and tried logging in with the default email of "admin@example.com" and password of "admin", but it failed. The password on the documentation is incorrect, as it has a minimum character requirement of 8. I tried using "admin123" as the password, and that worked. I took a screenshot of my setup and shared to the Discord server.

What could be worked on

• The document didn't account for potential errors that people would face. This could be worked on.
• I believe (but have not fully tested) that recommending autocrlf be switched to false would have resolved most of my errors, because bash files and conf files are often very senstive to line endings. A potential fix might be running git config core.autocrlf false in the folder the project was cloned into.
• Changing the section of the docs that says the default password is "admin" to "admin123".
• An FAQ section might also have been helpful, so that people wouldn't have to ask questions that have already been asked in the past.
• I noticed there wasn't a reference documentation, but I read that it's still being worked on.

Nice-to-haves

• A video tutorial.
• Modify step 5 here to enclose ".env.example" and ".env" in backticks (``) for inline code.

TL;DR

The instructions were clean, but they lacked guidelines on how to fix potential installation errors.

[kivenalaric]

Here's what i would like to comment about the documentation, on the part of about "What does Ushahidi Do" not like there was aproblem there, but if there was maybe a video or a link to a video that explains better i think it would be better because from my own experience visual explanations are better.

Setting Up the Project Normally following the steps found on the documentation, i didn't face any problems setting the project up but realised others in the discord channel had some errors which could be used to better the documentation by including possible errors and how to solve them, so one wont have to necessarily visit sites like Stackoverflow for solutions.

[MugoBrian]

Hello @kivuvarosekivuvan and @tubapervaiz1508 , the issue is open to everyone as stated in the updated title.

[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

[pragya-p-github]

Comments:

Values: The outlined values of being considerate, respectful, inclusive, collaborative, transparent, mindful of people's privacy, and committed to self-improvement are crucial for fostering a positive and inclusive community. It's commendable that Ushahidi places emphasis on these values and encourages community members to uphold them.

Unacceptable Behaviors: The document does a good job of clearly defining unacceptable behaviors such as discrimination, harassment, exclusionary language, false claims, and posting inappropriate content. It also encourages reporting of such behaviors and outlines the actions that may be taken in response to violations, ensuring accountability and maintaining a safe environment for everyone.

Suggestion:

Where does the Code of Conduct apply: Clearly define the spaces, both physical and online, where the Code of Conduct applies. Provide examples of specific platforms or events covered by the Code of Conduct.

[lillian-busingye]

@Angamanga summarised everything that I personally went through from when I joined the community and I couldn't explain it any further than they did. Thank you