This tutorial will teach you how to contribute with content to the public Documentation KB.
Different types of content inside Documentation KB
- content which has been curated by the Knowledge Team
- this content lives here: https://success.outsystems.com/Documentation/
- anyone can search and find this content
- only the Knowledge Team create / edit this content
- content produced and updated by the Customer Success Team
- this content lives under this page:
- only the Customer Success Team can find this content
- content can be shared with customers in the context of expert services
- explicitly changing the article permissions and sharing a direct link to the content
- both the Customer Success Team and Knowledge Team can create / edit this content
Responsibilities regarding content
- the Knowledge Team is responsible for:
- updating and fixing issues in the the public content
- maintaining the KB content guidelines document
- when a new major version of the platform is released iterate over all articles that pertain the the previous platform version and work with other teams to identify what contents need to be updated
- when a new patch is released go over the change log; grab the internal Defect Id; find related KB articles that discuss it and update it with:
"This issue was fixed on Platform Server - version XPTO"
- the Customer Success Team is responsible for:
- using both public and unlisted content while in the context of CSPs / answering customer questions
- identifying technical errors, corrections, missing information with the public content
- create Drafts with the necessary content improvements
- mark Drafts for review by the Knowledge Team
- creating new unlisted content directly in this area:
- using both public and unlisted content while in the context of CSPs / answering customer questions
Processes around content
Add new unlisted content
Improve public content
Search public and unlisted content
The unlisted KB lives under the same hierarchy as the public KB:
- the public KB lives under /Documentation
- the private KB lives under /Documentation/Unlisted/Customer_Success_Team
- a scoped search by /Documentation will return both public and unlisted results
- meaning 1 less search on a distinct system
- articles can be seamlessly migrated from the unlisted to the public KB
- no impact on the way an Customer Success Team member searches for them (i.e. articles don't vanish when they are promoted to the public KB)
In-browser search shortcuts
Configure this URL has a search keyword: https://success.outsystems.com/Special:Search?path=Documentation&search=%s
Install http://www.instantfox.net/InstantFox and then configure this URL has a search keyword: https://success.outsystems.com/Special:Search?path=Documentation&search=%q
Anyone using IE?
Search articles you know exist / instant search
In Confluence there is a nifty shortcut that let you quickly find articles (you know by heart) using partial words:
While we don't have instant search on the MindTouch UI YET... you can use the wildcard * character to apply get partial matches:
Search in MindTouch - Support KB example
Today the Support KB includes 3 search boxes:
The first and second search boxes will only show public information, with OutSystems-wide (1) and Support KB (2) scopes respectively:
To search unlisted and public inside the various MindTouch KBs (not just the Support KB!) you need to be authenticated and use the third search box, the one that shows up in the MindTouch black-background menu:
The resulting search results page includes a refinement capability that you can use to scope your search results:
The image above is already outdated. Here are the correct ones::
- Evaluation Guide - this is the OutSystems Evaluation Knowledge Base.
It will include answers to the TOP 50 evaluation questions that hit the Pre-Sales team
- Documentation - the public learning area.
The Customer Success Team KB lives here under /Unlisted.
- Getting Help - this is the Support KB.
Applying this filter/refinement is the same as using the in-browser shortcuts
Configure your author account
MindTouch has SSO integration with OutSystems so you should have read access to most of the existing content.
To create new content your user needs to be properly set up inside MindTouch. If you can't create content contact the CX Team (firstname.lastname@example.org) to help you out.
Create unlisted content
Everything is an article. Article types are really not that important. But we'll use specific types for specific purposes.
Topics vs documents
- Break content into topics. Each topic lives as an article.
- Users will not read an entire guide sequentially. Topics must be able to live independently.
- Topics must be self-contained. A user that lands at the article must be able to have sufficient context to understand it. This includes the title.
- Use links to navigate to appropriate related topics/content, internal or external.
Grouping articles into guides
- Parent topic
- Title should be an action, e.g "Designing your OutSystems Factory Infrastructure"
- Introduction with Why and What, to clearly show the value of the guide.
- Acts as an index with links to child topics. Use the "Guide listings" widget when you are editing the topic.
Always classify as type "Guide" to render a widget that visually groups child topics as chapters of the guide.
- Child topic
- Should cover concepts, recommendations, facts, lists, procedures (how-to), and examples.
- Always classify as "Article" or "How-to" to be visible inside the "Guide" widget.
- Don't forget to include the Page Summary. It works both for SEO (when is it public) and as the short description that is displayed in the "Guide Listings" widget.
- The treeview will not be visible if you share the article with a customer.
- The vanilla look&feel and functionality of the unlisted area will be improved in time.
- All articles that belong to the same guide will automatically display related topics for full context and improved navigation.
a) Navigate to the page where you want to create the new page
For Unlisted content this is always below: https://success.outsystems.com/Documentation/Unlisted/Customer_Success_Team/
A common mistake is creating pages under existing pages - don't do that. :)
b) Click the "New" button on the top of the page
c) Select an available template and select the "Create live" radio button.
d) Edit and save content
Edit Unlisted content
If you want to edit an existing page, you just need to open that page and in the top menu click the "Edit Page" button.
The page will load the WYSIWYG editor and you can submit your changes.
You can set tags for a [already saved] article by expanding the "Page Settings" widget and adding them there. Changes are immediately reflected (you don't have to click anywhere to save).
Share a unlisted article with a customer
Some of the content in the unlisted area of the KB will be improved by the Customer Success Team to the point where it can start being shared with external parties (e.g. customers and partners).
By default, articles in this area are created with the lowest access permission possible which is "Private".
You can check the permission for a given article below its title:
In order to share an article with non-OutSystems users you have to update the article permissions so that it becomes accessible to anyone with the link. To do this follow the steps below.
Access the page permissions screen:
On this screen select Semi-Private (NOT Semi-Public) and click "Save Permissions Settings".
You will be sent back to the page with the correct permission in place:
Now you can share the URL to the link and the external party should be able to read it.
Turn unlisted content into public content
Each MindTouch article has a Stage classification that the Knowledge Team uses to track an article maturity as its content evolves.
From the available values, the Knowledge Team uses Stub, Draft, Review and Final.
Here's the meaning for each Stage Classification:
- Stub: the topic is still just a placeholder for the content and is still missing any valuable content
- Draft: someone has started working on the the topic but it's still a work-in-progress
- Review: the Customer Success team members working on the topic have classified it as final and it's ready to review by the Knowledge Team
- Final: someone has reviewed the content and it's ready to be become public content in the live Support KB
To mark content from the unlisted area as ready for being moved to the public area you just have to change it's Stage Classification, as seen below:
The Knowledge Team will then be able to see the article on their "Articles for review" dashboard.
Creating in-content comments which are visible only by OutSystems staff
Sometimes it's useful to enrich articles that are already accessible by external parties with internal/OutSystems-only notes and comments.
To do this you can take advantage of a small "widget" we created exactly for this purpose:
This is how the block looks like:
Suggest improvements on public content
For content which is already in the public area of the Documentation KB we do not want changes to be done directly over the version that prospects and customers are consuming.
To ensure this while still enabling OutSystems staff to contribute with corrections or improvement suggestions we have disabled live editing of those articles. Instead, fixes and suggestions should be done using a "draft":
Here are the steps for getting your suggestions in:
- go to the article page for the public article you want to improve;
- click "Create draft" as seen above;
- perform whatever changes you think improve the article;
- save the draft with your changes;
- change the article "Article Type" classification to the "Review" value (see Turn unlisted content into public content for details)
This final step is enough to get your changes in the radar of the Knowledge Team (for validation and actual publishing).
Can't find articles (I know exist) while searching
Only logged in users using the default MindTouch search can find articles from the unlisted area. Check that you are logged in and using the right search.
I created an article in the right category but it doesn't show up there
There is a to-be-replicated bug where articles are created with the wrong "Article Type" classification. If you have recently created the article, hit back on the browser until you get to the article and manually change its default Article Type classification:
- Expand the "Page Settings" panel near the breadcrumb
- change "Article type" to "Topic"
That is enough to have the article appear as expected.
You're now ready to get started!
Pick one of the articles below and help out by:
- adding information
- linking to other public sources
- applying the content guidelines