|
Finished rewrite with new images and activated page and images.
|
|
Changes were activated to the public instance.
|
|
Received following from Antti in E-mail received February 2, 2011 with subject Category Status/DOCU-108:
I would like you to take another stab at the Categorization article. Boris and I looked at it and feel it needs more depth.
You have a screenshot of catCloudWide paragraph in the base area (as a base element). There are two other cloud paragraphs in the module: catCloud and catCloudExtras. They can be added to the main area and extras area respectively. You need to configure the paragraphs to be available in these areas. Try first to find out yourself how this is configured. If you get stuck, I'll give you a hint. Describe the configuration procedure in the article.
Emphasize throughout that the module works as described in its default implementation but is much more versatile. Take a look at the module code. How could you use the same concept to categorize data items? What else could you categorize? Write examples, even if hypothetical, to get the reader's imagination going. There are developers reading this article so you can go into technical details.
The font size in the cloud comes from the CSS. It's not a direct derivative of the importance given by editor. Details like this should be explained so that we don't give the impression the module is too simplistic and restrictive. The more layers there are, the more freedom you have to apply the logic to other areas and configure it to suit your requirements. What you see out of the box is the STK implementation, not the whole truth.
Subcategories and parent categories automatically become related categories. Try creating some and see how the stkRelatedCategoriesLinkList displays them. Explain in article.
|
|
Received following from Antti in E-mail received February 2, 2011 with subject Category Status/DOCU-108:
One more thought. Where you discuss the Openmind module, the text sounds like our implementation is not as good. It sounds like we have not thought about category weights. Try to put a more positive spin on it. Explain that we consider category cloud an editorial feature rather than an automated one based on stats. We feel the cloud should be under the control of editors. They should be able to set weights to promote categories that are currently hot, being campaigned, have new content etc.
|
|
Received following from Antti in E-mail received March 17, 2011 with subject Category Status/DOCU-108:
Recent questions on the users mailing list that might work as examples/inspiration in the Categorization module article.
http://old.nabble.com/How-to-configure-Category-Cloud-once-and-available-for-all-news-articles%2C-news-overview-and-category-overview-page--td31154462.html
http://old.nabble.com/Category-cloud-with-image-td31154527.html
|
|
Feedback about revised article.
Installing
- "Categorization is an Enterprise Edition module (4.0 and higher)". Per release notes should be 4.1.
Usage
- "creating RSS feeds for categories". You don't create a feed for categories but for the content tagged with them. Also, this use case should come after the tagging examples, otherwise the feed won't have any content.
- "The procedures in this section are performed on the Data > Category page." This is not true for the RSS feed procedure which is performed on the website page.
Creating categories
- Redundant to say the same thing three times in a row: 1) "Creating categories", 2) "The module provides the ability to create categories.", 3) "To create a category:". Drop the middle one.
- Step 1. Image is too wide. Resize the dialog since long fields don't add any value for reader. Just grab from the bottom right corner and drag the dialog to meaningful size.
- Step 5. Selecting a related category with the Choose button is so simple that it doesn't need a separate procedure. What needs an explanation, however, is what related categories do and why you would want to select some. Shorten this step to "Select related categories" and move the sentence about related categories from below to the step. Also, don't use bulleted lists for procedural steps. Adhere to the Microsoft Manual of Style for Technical Publications conventions. Per MSTP, bulleted lists are used for "unordered series of concepts, items, or options rather than a sequence of events or steps". Look up "Lists".
- "The Importance selection..." This is a good paragraph. You explain what importance is and what impact it has. Move it to step 4. Don't bold the term unless you refer to the field itself, in which case it should be capitalized. When writing about the concept, normal weight lowercase.
- "Related categories are rendered in the right portion of a category's overview." -> "Related categories are displayed in the Related Categories Link List paragraph in the extras area on a Category Overview page." Mention also that their purpose is to help the user discover more interesting content.
- "Note". What is the purpose of this paragraph? The page that is displayed after clicking Choose is called linkBrowser. If you are explaining extension possibilities, shouldn't this information belong to some other procedure?
Organizing categories
- Explain in intro why editors want to organize categories. Is it just for grouping convenience? What impact does the hierarchy have for site visitors? The organizing itself is pretty trivial - you just move a node. The move command works the same way everywhere in AdminCentral and is already documented in the manual. Focus on explaining the benefits, motivation and consequence of organizing categories.
- Folders. What did Teresa say about folders vs. parent-child relationships?
- The subheadings "Tagging parent category" and "Tagging child category" are unclear. Please reword. You tag something (direct object) with something else (indirect object) such as "Tagging an article with a parent category".
Tagging items
- Tagging articles is the second most common procedure after creating categories. I would move it to the main page. Organize topics according to anticipated order of use. Extension options would come last.
- "Provided functionality" and "Potential expansion" sound a bit clunky. I understand what you mean - you want to contrast between what is available now and what can be extended. I suggest you move "Tagging articles with categories" to the main page and rename the current page "Tagging other items". On the page, explain "Tagging other pages with categories" and "Tagging other data types with categories". Keep the instructions simple. You don't need to write a procedure for copying the node again. Just say what to copy and where in order to extend the dialog.
- "Tagging module information". Procedure title and content don't match. Not tagging modules but contacts.
- "Apache installation directory". Apache alone usually refers to the Apache Web Server. Use Tomcat or Apache Tomcat instead.
Category clouds
- Same thing about provided functionality vs extension options
- "Clicking a category in a cloud will result in the Category Overview being displayed for that category." Technically correct but maybe try "Clicking a category in a cloud displays other articles the user might find interesting."
- Link to paragraph reference. There are also images you can reuse.
- Paragraph names in fixed width font.
- Start root with a forward slash.
- "Adding base element category clouds". Images fuzzy, list restarts.
Inheriting clouds
- "This section provides the procedure for adding the ability to inherit catCloudWide in the base element area as an example." Wordy. -> "To inherit catCloudWide:"
- Do procedural steps with numbers, not bullets. You can do a second level with numbers (##) but here the procedure is so simple you don't need more than one level. Split into three tasks like in the mailing list post.
- Are screenshots needed for simple steps like renaming a node? How about just one screenshot in the end that shows the resulting tree?
- Replace the fuzzy template script image with a code block. Examples
- Terminology: extend vs. expand
- "Adding category cloud images". Link to blog post instead.
- What use cases and examples did you come up with yourself? The examples in the article are the ones I gave in the ticket or mailing list.
Dependencies
- Terminology: dependency. There can be two kinds of dependencies: build-time (Maven) and run-time, see Dependencies in TG. There is a declared run-time dependency between the Categorization and Observation modules but no dependencies between Categorization and Scheduler, although both should probably be declared as optional dependencies. Try a more user-friendly heading like "Creating and applying categories automatically"
- Explain what the createCategories command actually does. What are some category names it creates? Where do the names comes from? Does the command tag any content with the categories? Is the default example usable as such or is customization needed to make it meaningful? What would you change to make it realistic?
- Observation. Fuzzy image.
|
|
The purpose of the note under Creating categories was to provide information related to creating categories that developers may find helpful. There was a missing word in the first sentence so I added that and as a result I think the first sentence is clearer. As for the second sentence, I've removed it.
With respect to the question about folders under Organizing categories, there is a bug and I created MGNLCAT-24 to cover it (Theresa is aware of this issue). Folders should not appear as related categories.
With respect to the suggestion to reference an image in a separate document under Category clouds, I'm hesitant to use an image in another document because that would increase the likelihood of a broken link. The image could get deleted without knowledge that it is used in another document.
With respect to the suggestion to add a code block under Inheriting clouds, adding the code block was problematic due to the list being restarted after the block and wanting to show checkbox since it can be hidden when that editor is rendered. Change was circled on the screenshot to help user to see where change was made.
Submitted changes for activation.
|
Generated at Mon Feb 12 01:05:59 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.