Page MenuHomePhabricator

Add doc type categories to Cloud VPS user docs
Closed, ResolvedPublic

Description

As part of T341364, I created some Documentation subcategories on Wikitech to help with navigation, search, and aligning the content to standard templates.

I wasn't able to review and apply categories to all the Cloud VPS docs, so I'm filing this task for anyone who wants to pick it up.

Suggested work is:

  1. Review each of the pages linked in the Cloud VPS navigation menu.
  2. Try to identify if the page aligns with a standard doc type, as defined here. For example, if it is primarily a how-to guide, add that category to the page. (Here are instructions for how to add categories to pages).

It's very likely that these pages are a mix of different types of content, and don't align clearly with one doc type or another. This is still useful information. You can tag docs as more than one doc type, and that will help people know that the page probably needs some work to clarify its purpose and make sure it achieves its goals.

Event Timeline

TBurmeister triaged this task as Low priority.

@Frostly Removing task assignee as this open task has been assigned for more than two years - See the email sent to task assignee on 2025-11-25.
Please assign this task to yourself again if you still realistically [plan to] work on this task - it would be welcome! :)
If this task has been resolved in the meantime, or should not be worked on by anybody ("declined"), please update its task status via "Add Action… 🡒 Change Status".
Also see https://www.mediawiki.org/wiki/Bug_management/Assignee_cleanup for tips how to best manage your individual work in Phabricator. Thanks!

Here are the categories I'm thinking would make the most sense for each page.

Template itemRecommended categoryStatus
Cloud VPSPortalsDONE
Cloud services overviewOverviewDONE
Cloud VPS user docsLanding pageDONE
Horizon web interfaceN/A (external web link)DONE
Horizon web interface (help)Landing pageDONE
About Cloud VPS projectsOverview, How-to guide, Landing pageDONE
Cloud VPS user roles and rightsOverviewDONE
List of Cloud VPS projectsN/A (external web link)DONE
Access Cloud VPS instancesHow-to guideDONE
Add disk space to instancesHow-to guideDONE
Server groupsHow-to guideDONE
Sudo policiesHow-to guideDONE
Unmanaged instancesOverview, How-to guideDONE
Security groups and firewall settingsHow-to guideDONE
Floating IP addressesOverview, How-to guideDONE
Web proxies for exposing Cloud VPS services to the internetHow-to guideDONE
Sending outbound emailHow-to guideDONE
Cloud VPS IP spaceOverviewDONE
Puppet on Cloud VPSOverviews, How-to guideDONE
Project puppetserverOverviews, How-to guideDONE
Database instancesOverviews, How-to guideDONE
Object storageHow-to guideDONE
Help and communicationLanding PageDONE
Recommendations for moving to productionNo relevant categories foundDONE
OpenStack APIsHow-to guideDONE
OpenTofuHow-to guideDONE
Cloud VPS infrastructureOverviews, Tool documentation [NOT CREATED]DONE
Administrator documentationLanding pageDONE
Administrator runbooksOverviews, How-to guideDONE

For "Recommendations for moving to production", I'd recommend creating some kind of "Best Practices" or "Recommendations" category to fit it under. It doesn't really fit the category of an overview or a how-to guide - it's moreso a page recommending the best way to do something, without going into detail on how to do it.
The "Sending outbound email" page would fit in this category as well, since it covers best practices.

I think "Cloud VPS user roles and rights" and "Cloud VPS IP space" would better fit underneath a "Reference Documentation" category than "Overview" - but Overview seemed to be the closest category currently-available.

As a follow-up to this ticket, it might not be a bad idea to specify recommended categories for the templates in the documentation toolkit here: https://www.mediawiki.org/wiki/Documentation/Toolkit#Use_templates_to_create_documentation

So for example, if someone's creating a how-to guide using the template - it would make sense for the template to specify they should apply the "How-to guide" Category to the article.

I've reviewed the pages in this ticket and assigned the closest categories I could figure out to their contents. I listed out the categories I think are the best fit in a previous comment.

Happy to fix any of the categories if any of them look incorrect or if another should be added. Marking this as resolved since it should be finished now to my knowledge.

Thanks for working on this, @Junkyard1625! Re: your suggestion that the documentation toolkit should refer to the doc type categories: unfortunately those categories aren't consistently created (nor used) across all the wikis and other places where Wikimedia technical documentation is published, but that documentation toolkit does seek to provide guidance relevant for all those places. So, referring to categories that are only on Wikitech would be too specific for the Toolkit. It's definitely something we can work towards though (having more consistent doc type categories across wikis and other places where tech docs live). Thanks again for all your work on this!