It’s time for a big change! We invite everyone to participate in nopCommerce documentation improvement. Read below how to contribute and what bonuses you will get in return.
New documentation system in brief
Now the documentation will be stored on Github (https://github.com/nopSolutions/nopCommerce-Docs) and everyone can participate in its improvement. The texts with all the edits will be beautifully displayed at docs.nopcommerce.com.
We based our approach on how the documentation for ASP.NET Core is conducted since our platform is based on this framework.
What was wrong with the old system
Since nopCommerce documentation was led by nopCommerce team and the limited circle of users, it could not be updated very quickly because this is a rather time-consuming task. As a result, some articles turned out to be irrelevant in the process of time.
The second point is that the documentation might not contain some sections important for the practical developer’s work on a specific project. We believe there are community members who could help us with writing them.
Main areas of work
The primary task is to make an up-to-date and complete version of English documentation, and while we work with it only. After it is ready, in a few months according to our plans, we will launch a similar system for documentation translations.
You can make changes yourself or suggest which existing articles can be improved and which articles are missing now (for more details, see the “Contribution process” section below).
There still will be two main sections in documentation - Developers guide and User guide. The directions of work on them will differ a little bit.
User guide describes the functions of the administration panel, and thus the needed articles already exist. But we need to improve them:
- make an update for nopCommerce 4.20 (such as adding new fields, description for the new features, and screenshots updating);
- include more examples;
- adapt to the users' work scenarios. It means we need to shift the focus from a consistent description of the fields and sections in admin panel to the features they are responsible for.
For example, in the Gift cards section, we need to describe more clearly the scenario of using a gift card from the store owner and consumer side and to explain the difference between virtual and physical gift cards. In the current view, the users will probably understand it in the end but they will need to waste a lot of time on it.
In the Attributes section, we need to explain what different attributes are responsible for and how the user can manage products with their help. We are sure there are many more sections that might be improved.
The goal is to make the documentation more user-friendly and as clear as possible for a person who starts working with nopCommerce for the first time.
In Developers guide, besides the need to update articles for the latest version of nopCommerce, some topics might be missing. For example, a guide on installing nopCommerce on Linux and related issues (read further to know how to create new articles in the documentation).
Contributors' rewards: what you will get
- Mention as a contributor with the link to your Github profile on the documentation site.
- Documentation contributor icon shown on your nopCommerce profile. Assigned after 20 received significant pull-requests (read the details in the next section). After reaching this amount, send your candidature for consideration with the link to GitHub profile using out contacts form.
- MVP status for 3 community members who made the most valuable contribution to documentation.
- Six tickets to nopCommerce Days conference. Three of them will be given to new MVPs, and three more - to three other active contributors.
- Cool souvenirs from nopCommerce to active participants. We’ll hand them at the conference if you arrive, or send by mail if not.
The results will be summarized after the work on the English version of documentation is finished.
Formal requirements regarding the rules for structuring articles and storing pictures are described in the Contributing section. Here you will also find a guide on how to create new documentation articles.
We offer to work with documentation through the pull-request system. Select this option after making your edits. We will review it and after approval, the changes will be pulled to the documentation site.
If you have an idea about which articles are missing, or what large-scale changes can be made to the documentation, but you are not ready to implement it, you can post it in the Issues section.
All issues will be marked with the following labels, and it’s very important to pay attention to it:
- “developer-guide”/ “user-guide” - indicates which section in the documentation this issue should refer to;
- “editorial” - the changes in the existing article needed;
- “new-topic” - a new article creation needed;
- “discussion” - the need for the creation of a new article or making changes in the existing one is under discussion, and you can participate in it. Please do not start work on the issue until this label is removed.
For all the questions and suggestions: forum post
To edit the documentation: https://github.com/nopSolutions/nopCommerce-Docs
Contribution guide: https://github.com/nopSolutions/nopCommerce-Docs/blob/master/CONTRIBUTING.md
Documentation site: docs.nopcommerce.com/
We invite everyone to join us and participate in this large-scale upgrade.