New documentation feedback

I've been looking at the new documentation and noticed a couple of areas that seem to be missing. I was hoping there was a way to access the old documentation to see if they were covered there but it seems that's not possible. I thought it might be useful to start a thread for people to provide feedback on the documentation. I've put this in the Suggestions and feedback forum but feel free to move it to the Nopcommerce.com website forum if you feel it's more appropriate (or maybe the documentation deserves its own forum).

Anyway the areas that don't seem to be covered very well are:

1. Adding Product Attributes to products
The documentation on Product Attributes covers creating the attributes themselves and adding predefined values but there's no coverage of actually adding the attributes to products. There's a link at the bottom of the page the Adding Products documentation but the section on this page about Attributes just links back to the main Product Attribute documentation. There's also a link to a video tutorial about managing product attributes but I think it still needs to be covered in the written documentation somewhere. This is potentially quite a complex area once you get into the different attribute control types, value adjustments, Associated to product attributes and bundle product creation so could really do with some good documentation to highlight all the possibilities it offers.

2. Adding Specification attributes to products
Similar to product attributes the current documentation on Specification attributes covers creating the attributes and adding attribute values but doesn't mention anything about mapping the attribute values to products. Again, there's a link at the bottom of the page to the Adding Products documentation but the section on this page about Attributes just links back to the main Specification Attribute documentation.

3. Customer account pages documentation
This isn't really a problem it's just a bit weird. Under the Configuring your store > Setting up Customers documentation there is a section called Customer account pages. All the documentation in this section actually relates to the customer account pages in the public store rather than the anything to do with the admin panel. I agree that it might be useful to have this documentation somewhere but I'm not sure it's related to store configuration as it's more likely to be customers that use these pages rather than store owners.

Please let me know if I've missed something obvious or if these first 2 really don't exist.

Thank you for your feedback, Pete! You’re right, we’ve missed info on the first 2 points, thank you for noticing. I’ve added the instruction on the Adding Products page.

Great thanks, but I think there's still some necessary information missing. For example the Adding Products documentation mentions:
"The Values field now displays a number of predefined values for this attribute. View/Edit values, if required."

Which is only true if the attribute has some predefined values configured but there's also no mention of what the various options on the value edit page mean, i.e. this screen in the admin GUI: http://admin-demo.nopcommerce.com/Admin/Product/ProductAttributeValueEditPopup/21.

Now most of the options are fairly self-explanatory but something like the difference between simple attributes and associated to product attributes really needs covering somewhere in the documentation as it's not going to be obvious to new users.

In general I think the documentation does a pretty good job of describing what each option in the admin panel does but there needs to be a bit more explanation of why a store owner might want to use them. As an example consider this forum question and my rather lengthy answer about how to set up a bundle product. Ideally the process of setting up a bundle product should be covered in the documentation so it would be possible to answer that question just by providing a link to the relevant page. Searching the nop documentation for bundle currently only returns a single result to do with CSS and JS bundling and minification and gives no indication that bundle products are even supported.

I think you could take some inspiration from the Magento documentation which does a very good job of presenting this kind of task based documentation along with the more functional documentation e.g. http://docs.magento.com/m1/ce/user_guide/catalog/product-bundle.html.

Another idea that I mentioned to you at the last nop conference was the idea of providing links from the documentation to the nop demo site (both public and admin). So in the documentation covering downloadable products, provide links to an example of a downloadable product on the nop demo site and it's relevant product setup page on the admin demo site. This would also help to highlight areas of functionality that are not covered on the demo site (e.g. there are currently no examples of products with conditional attributes of the demo site which would be useful to be able to link to when answering forum questions where conditional attributes might provide a solution).

Anyway I hope these comments/ideas are useful and I hope I don't come across as too critical, as a developer myself I'm well aware that writing documentation sucks (and I've never had to do it in second language).

petemitch wrote:

More detailed explanation for Tracking Inventory by Product Attributes is advisable

petemitch wrote:

+1

My 2 Cents:

1) I also recommended before to have a summary of the documentation: to have a list of all Nop features (a few months ago I mailed Andrei a detailed list of the features) with a short (one line) description of each one and links to examples in the shop/admin demos. That may require that the Nop demo is enhanced to encompass examples of all listed features
This could be a Quick Reference User Guide and has the advantage that it could easily be translated into other languages.

2) There are dozens of very valuable blogs, articles, speeches (from nopCommerce days), webinars  and videos generated by the Nop team and members of the Nop community. It would be very valuable to have them structured in a section like the Nop Marketplace, with the corresponding search engine, where anyone could upload contributions (subject to approval)information of their articles (name, short, category, and tags, etc.). In the article detail section a link will be provided to the site where it can be viewed/downloaded. This also has the advantages that it provides valuable SEO incoming links to the websites of the contributors.

petemitch wrote:

Hi Pete,
Thank you for having a thorough look at the new documentation and your active contribution!
As for the simple/product associated attribute description, we’ll add this for sure.

petemitch wrote:

We are planning to create a separate section in the documentation explaining rather complex cases done with nopCommerce out of the box configuration. So such example could definitely be described there. If you have some other examples in mind, please feel free to share (please, start a new forum topic in this case).

Thank you!

Tecnofin wrote:

Hi Eduardo,
Thank you for the idea! Took into consideration.


Tecnofin wrote:

We welcome blog posts and articles from our community members. Please, find more detailed information in our editorial guidelines. We'll make this document more visible soon so that the community and visitors will be well aware of it.