Creating a Documentation Portal
Learn how Salesforce created portals for delivering documentation to end users. Along the way, discuss design practices, customer interactions, and learn how to use the open source version of our portal to deliver your content on the web.
Presenter: Steve Anderson, Salesforce
Time: 8:30 AM to 10:30 AM
About our presenter
Steve Anderson is an Information Architect at Salesforce. After many years of writing technical documentation, he moved into software development, focused on information delivery. He currently leads a small team that creates all the tools and processes for developing and delivering documentation for Salesforce.
In his spare time, he obsesses over football, snails that eat the vegetables in his garden, and his precocious 6-and-3/4s-year old daughter. He loves to camp, especially now that his daughter has learned how to make her own s’mores. His favorite camping trip is to the Turkey Creek hot springs in the Gila Wilderness of New Mexico, where once he fell twice on creek crossings and another time he got snowed out (in May no less).
Scribe: Kristen Toole
- Single page for a single product (bootstrap) related technologies (dev docs) single technology (java)
- Think seriously about committing to a portal. It is not trivial
- When defining requirements, keep them user focused
Member of tech docs at Salesforce, not embedded in IT. Focus on tools and processes
What is a Portal? Website with purpose of delivering docs for specific prods; defined by purpose, not by technology or functionality. By this definition, a wiki could be a portal, so long as doc is focus
What we looked at getbootstrap.com/getting-started
Why? Think seriously about whether you want to make this commit
Pros: Cannot serve up content using existing systems, current system is missing key function (i.e., search), current system isn’t available.
Discussion about whether we’re going to cover adaptive content by profile (through metadata? through a profile that they fill out at signup?)
Planning for your portal
- what is the problem you’re trying to solve?
- What is the minimal function you need for success?
- how many different page types do you need? i.e., search may require search results page
Quick digression topic: Core model design. Links to be provided for “Core + Paths: A Design Framework For Findability, Prioritization and Value” and “The Core Model Designing Inside Out for Better Results”
Pagetypes: start by assuming you need one page that contains content and then only prototype other pages as you discover needs (i.e., search page, landing page) or a page of a ton of old (archived) pdfs.
Prototyping: go low tech, low investment, put it in a sharable format/space. Don’t let it become a straight jacket. Iterate!
Red Sofa Documentation Portal (open source portal):
Written in Ruby with content stored in a nosql database. Hosted for free in cloud on Heroku. Available code in github.com. This portal is based on an early version of the Salesforce portal.
Demo. Took us through creating Heroku account & IBM cloudant account. Install and setup git. Install and setup Ruby. Ruby Install. Heroku toolbelt
Simply build out a profile with sample content stored in git and you can do that locally (avoiding Heroku if you want)