Conversation
github-actions
bot
added
type: feature
|
when looking at the files, it's easiest to look at the file individually so that you can see the 'rich' format Or you can simply look at the files directly from the branch: https://github.com/openboxes/openboxes/tree/ft/readme-overhaul |
| The application has grown significantly since its conception, and is now used to help run warehouses and healthcare facilities at all scales, all over the world, including in Sierra Leone, Lesotho, Rwanda, the United States, and more! | ||
|
|
||
| ### Financial Contributors | ||
| See [our website](https://openboxes.com/features/) for a list of some of the primary features of the application or check out our [demo site](https://demo.openboxes.com/openboxes/auth/signup) to experiment with the application yourself! |
There was a problem hiding this comment.
It would be good to also update the content of this site https://openboxes.com/features/, looks like it still has some outdated screens (eg. initial version of stock movement)
There was a problem hiding this comment.
omg, yes. this is fairly involved but i would love some help getting screenshots and content for these. in fact, i think the usability of that page could be completely overhauled.
README.md
Outdated
| For more information and step-by-step instructions go to: | ||
| https://openboxes.atlassian.net/wiki/spaces/OBW/pages/1719435265/Push-button+deployment | ||
| ## 🚀 Quickstart Guide | ||
| The following instructions describe the minimum steps required to build and run the application on a Linux machine. For Mac users, or anyone looking to contribute to the project, please see our [in-depth setup instructions](https://openboxes.gitbook.io/contributor-guide/). |
There was a problem hiding this comment.
I was thinking of removing the instructions from Quickstart Guide section and intead simply link to https://openboxes.gitbook.io/contributor-guide/software-development/onboarding/running-openboxes-locally. It'd make the readme significantly shorter and would avoid having duplicate instructions.
Thoughts?
jmiranda
left a comment
jmiranda
left a comment
There was a problem hiding this comment.
I haven't gotten to the README yet, but wanted to get the current set of suggestions to you.
CONTRIBUTING.md
Outdated
| We do our active development out of the 'develop' branch, so make sure to branch from 'develop' when making your changes. | ||
|
|
||
| Yeah, reading documents like this takes a long time, but we feel that having a common understanding of the goals and expectations of contributions saves more time in miscommunication and recreation of pull requests than it costs up front. It's short, we promise! | ||
| ### Feature Development and Bug Fixing |
There was a problem hiding this comment.
If possible, I would break this into two sections. That way we can add more specific workflows under each (if/when necessary)
- Feature Requests
- Bug Fixes
Feature Requests
(two paragraphs about PIH-lead development can go here).
Bug Fixes
When fixing a bug, reference the related issue in your commit or PR (Fixes #123). Include steps to reproduce, affected components, and test coverage. Be sure to run the full test suite before submitting.
There was a problem hiding this comment.
Also we should have a section for Reporting Bugs in the non-developer section.
There was a problem hiding this comment.
Nevermind about Reporting Bugs. I see that you have that below.
There was a problem hiding this comment.
Replacing with something in the guide about how to pick up tasks and make bug fixes. Somelike that lives alongside: https://openboxes.gitbook.io/contributor-guide/software-development/onboarding/how-to-make-a-pull-request
CONTRIBUTING.md
Outdated
| We use [Crowdin](https://crowdin.com/) for handling all of our translations, so if you're interested in contributing new translations, please [join our Crowdin project](https://crowdin.com/project/openboxes). | ||
|
|
||
| # Getting started | ||
| ## Reporting Bugs |
There was a problem hiding this comment.
Add a separate section for Requesting Features
Requesting Features
If you’re proposing a new feature, open a GitHub issue with a clear problem statement, proposed implementation, and technical considerations (e.g. data model changes, API impact). Bonus points for wireframes or example payloads.
There was a problem hiding this comment.
Sorry I missed the section above.
There was a problem hiding this comment.
CONTRIBUTING.md
Outdated
| We encourage you to start a new [discussion topic](https://github.com/openboxes/openboxes/discussions/categories/ideas) that outlines the feature you would like to see, why you need it, and how it should work. | ||
|
|
||
| At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first :smile_cat: | ||
| ## Translating the App |
There was a problem hiding this comment.
This could be more generalizable (e.g. Improving Localization or Improving Internationalization) but let's leave it for now since those might need to be explained to users.
One suggestion, let's use one of the following
- Improving Translations
- Adding Translations
- Customizing Translations
There was a problem hiding this comment.
We should have a separate document somewhere to help describe this process, as well as troubleshooting tips for known issues (e.g. not being able if you don't have a crowdin account) and workarounds for less common cases (e.g. creating a separate messages_es_MX.properties with JUST the variances from messages_es.properties)
There was a problem hiding this comment.
Some of this work might require a separate ticket to add the content, so don't feel the need to do it yourself.
There was a problem hiding this comment.
CONTRIBUTING.md
Outdated
|
|
||
| Unsure where to begin contributing? If you've played around with OpenBoxes, you've no doubt come across a few places where the documentation is a little lacking. We often get so caught up in bug fixes and feature requests that the documentation can lag behind. Write a glossary, or an explanation of how the Stock Card works, or what the different options on the dashboard mean. Explain how to set up locations, parties, and users. Really, anything would be helpful! | ||
| ## Writing Documentation | ||
| We have multiple sources of documentation: |
There was a problem hiding this comment.
We don't have to make all of these changes. These are just some suggestions to make it more clear that we have different sources that have many purposes.
The link descriptions are a little confusing given that they describe the technology rather than what the documentation is for. I would add a description based on the intended audience or documentation classification rather than the technology. Also, include the base URL in the description just so it's clear where it goes (or create a table to include the base URL = docs.openboxes.com, openboxes.gitbook.io and technology used = Mkdocs, HelpScout, Confluence).
- Official Documentation (docs.openboxes.com) is the official documentation site for OpenBoxes. It provides user guides, developer documentation, admin setup instructions, API references, and release notes. Whether you're a new user, system administrator, or contributor, it's the best place to learn how to install, configure, use, and extend OpenBoxes.
- Knowledge Base (help.openboxes.com)
- Contributor Guide (openboxes.gitbook.io) Guide for anyone, technical or non-technical, wishing to contribute to the project
- Internal Project Documentation:
Contributor guide (technical and non-technical) & non-technical user guidethis is much more than what is described.
I feel like a lot of these could be expanded into their own bullets. For example, the official
- Installation Guide (docs.openboxes.com) - A technical guide for administrators aimed at providing instructions for installing, deploying, and configuring the application.
- Developer Guide (docs.openboxes.com) - A technical guide for developers that provides API docs, etc.
- etc
In addition, for the Confluence source, we could break it down into the different types of documentation. People aren't really going to say "oh cool you have a confluence, let me have access to it". But if we described each of the specific
- Roadmap
- Requirements
- Technical Designs
- Discoveries: An internal documentation source that includes a discovery, designs, contributor guide (technical and non-technical) & non-technical user guide, etc.
Oh shoot, I just realized you're talking about the OpenBoxes Confluence, not the PIH Confluence. So maybe disregard this recommendation.
The gitbook site might end up being more than the contributor guide but I'm fine that that just being called Contributor Guide.
There was a problem hiding this comment.
Replacing with other pages that live under: https://openboxes.gitbook.io/contributor-guide/writing-documentation
|
Some other general suggestions
|
jmiranda
left a comment
jmiranda
left a comment
There was a problem hiding this comment.
Initial comments on README (more to come after refactoring by @ewaterman).
README.md
Outdated
| <img src="/docs/assets/img/logo-background.png" alt="OpenBoxes logo" width="110"> | ||
| </a> | ||
| <h1 style="margin-top:0; padding-top:0">OpenBoxes</h1> | ||
| <h4>A lightweight and open-source inventory and supply chain management system.</h4> |
There was a problem hiding this comment.
We should stick with the original description. "Lightweight" is somewhat misleading. The rest is probably ok since we describe it as "inventory and supply chain management software" in other places. Eventually, I'd like to start angling towards "warehouse management system" but perhaps this isn't the right time.
There was a problem hiding this comment.
what descriptor would you replace it with? Feature-rich, performant (not really), accessible?
|
As discussed, I moved these changes to the .github repository so that they can be applied to all repositories of the openboxes org: openboxes/.github#1 Once that is merged, I'll update this PR to remove all of the files except the main readme. |
|
Let me know when this one is ready for final review. |
|
@jmiranda you can review the readme. Everything else will be removed once openboxes/.github#1 is merged |
github-actions
bot
added
the
domain: devops
3 participants
✨ Description of Change
Link to GitHub issue or Jira ticket: https://pihemr.atlassian.net/browse/OBPIH-7412
Description: See ticket for details. I'm looking for feedback on structure and content. I still need to revamp the GitBook with proper contributor docs but I'll do that in parallel to this change.