1.
Creating a Documentation Portal
Steve Anderson
Information Architect
sanderson@salesforce.com
@SteveLAnderson

2.
Who am I?
BS in Technical Communication, with a minor in CS
20 years of experience writing
10 years of experience programming
A member of the technical documentation team at Salesforce

3.
Agenda
 What
 Why
 Planning
 Doing
 Ongoing

4.
What is a documentation portal?

5.
It is defined by purpose, not technology or functionality
“A documentation portal is a
website with the purpose of
delivering documentation for
specific projects or systems.”

6.
Examples of documentation portals
• Doc portals
• Single product – Bootstrap
• Single technology – Java
• Multiple technologies – devdocs
• Not Doc Portals
• New(sy) – Gizmodo
• Info repository - Wikipedia
 Search – Google

7.
Questions about what a
documentation portal is?

8.
Why create a documentation portal?

9.
You don’t create it and forget it.
Having a portal is a commitment of your time
“Only create a documentation
portal if you must have one.”

10.
Some reasons to create a documentation portal
 You have a new product that cannot be served using existing systems
 You have a current system that is missing required functionality
 Your current system is no longer available
 For fun

11.
Examples
• A new project - database.com
• Missing functionality – Salesforce1
• Unavailable system – www.salesforce.com/docs

12.
Questions about what and why?

13.
Questions for you
• Do you want to create a documentation portal?
• Are you sure you can’t use existing resources?
• Have you written down the problems you are trying to solve?
• Have you written down the functional requirements?

14.
Planning for a documentation portal
• What is the problem you are trying to solve?
• What is the minimum set of functionality you need to be successful?
• How many different page types will you need?
• What functionality does each page type provide?
• Prototypes

15.
Problem statement
A good problem statement is
• Concrete
• Specific
• Based on observations of the users
• Short
• Contains no solutions

16.
Functional requirements
Good functional requirements are:
• Concrete
• Specific
• Are not prototypes
• Driven by business and user requests
• A solution to the issues raised in the problem statement

17.
Quick digression
Core Model
• Core+Paths: A Design Framework for Findability, Prioritization and Value
• The Core Model: Designing Inside Out for Better Results
• This is a great concrete style for defining your problems and functional requirements
• Addresses both business needs and user goals
• Helps you figure out how many different kinds of pages you need

18.
Page types required
• How many different kinds of pages do you need?
• Start by assuming you need one page type
• Add more as requirements dictate
• Examples
• Documentation content with links to other related documents
• A landing page that lists the deliverables
• A search results page

19.
Prototypes
• Don’t spend too much time on them
• Make sure everyone can see them, always
• Don’t change them without everyone knowing about the change
• Don’t allow the prototype to be a strait jacket

20.
Prototype Example

21.
Questions about planning?

22.
Ready to start?
Let’s put the work into workshop!

23.
Create a portal from an open source project

24.
Red Sofa Documentation Portal
• Early version of salesforce.com documentation portals
• Open source
• Written in Ruby, with content stored in a NoSQL database (CouchDB)
• Hosted, for free, in the cloud on Heroku
• Red Sofa project page - https://github.com/forcedotcom/doc-portal

25.
Steps
1. Create heroku account
2. Create cloudant account
3. Set up your computer environment
4. Clone the project from github.com
5. Upload HTML content to the database
6. Push the app to Heroku
7. Review and iterate

26.
Sign up for Heroku
https://signup.heroku.com

27.
Sign up for Cloudant
https://cloudant.com/sign-up/

28.
Set up your computer
1. Install and set up git
2. Install and setup ruby
• Mac or Linux: Use RVM - https://rvm.io
• Windows: http://rubyinstaller.org
Install the Heroku toolbelt - https://toolbelt.heroku.com

29.
Local project from Heroku
• If you’ve deployed it using the “Deploy to Heroku”, at the command-line, type
heroku git clone –a myapp
cd myapp
git remote add origin https://github.com/forcedotcom/doc-portal.git
heroku config:add RACK_ENV=production
heroku config -s > .env

30.
Local project from github
• If you have not deployed using Heroku, at the command-line, type
git clone https://github.com/forcedotcom/doc-portal.git
rake initialize_heroku[myapp]
heroku config:set CLOUDANT_URL=http://<cloudant-host>.cloudant.com
heroku config -s > .env
git push heroku master

31.
Upload the HTML to the database
• At the command-line, type
rake update_remote_db

32.
Review
• At the command-line, type
heroku open

33.
Running it locally
• Install couchdb - http://wiki.apache.org/couchdb/Installation
• Add lucene to couchdb - https://github.com/rnewson/couchdb-lucene
• Set the CLOUDANT_URL environment variable
• For a local database, do something like this: export CLOUDANT_URL=http://admin:admin@localhost:5984
• Create a file named .env.development and add your CLOUDANT_URL export command to it
• export CLOUDANT_URL=http://admin:admin@localhost:5984
• At the command-line, type
rake update_local_db
rake start_local_db
Point your web browser at - http://localhost:5000/

34.
Questions about the process?

35.
Next steps
• Simple application configuration
• Updating content
• Updating metadata
• Customizing the look and feel
• Usability testing

36.
Simple application configuration
• To change app configuration, edit
config/app.yaml
• YAML – Yet Another Markup Language
• Simple key:value format
# Max number of search results to show on a page
:SEARCH_RESULTS_PER_PAGE: 25
:MAX_SEARCH_RESULTS: 200
# Number of characters in the search results snippet
:SNIPPET_LENGTH: 250

37.
Updating content
• Replace the sample files with your own HTML
• Update the table of contents file for your project
• Upload the content

38.
Updating metadata
• The default topic, locale, and other functionality for each deliverable is controlled by a metadata file
• To change the metadata, edit
content/<lang-locale>/<deliverable>/deliverable_metadata.json

39.
Customizing the UI
• The UI uses Twitter Bootstrap, version 2.3.2
• Fonts, colors, spacing, etc. are configured in less, not CSS
• Less is a CSS pre-processor; see http://lesscss.org/
• To update, you need to install lessc and uglifyjs
• To customize, edit portal2_customizations.less then, from the command-line, type
rake bootstrap:init
rake bootstrap:make
git add .
git commit –m “Updating styles”
git push heroku master

40.
Usability testing
• Usability testing is vital to improving your portal
• It can be done after an initial version is available
• Don’t wait too long!

41.
Thank you