creating a documentation portal
TRANSCRIPT
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
Agenda
What
Why
Planning
Doing
Ongoing
What is a documentation portal?
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.”
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
Questions about what a documentation portal is?
Why create a documentation portal?
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.”
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
Examples
• A new project - database.com
• Missing functionality – Salesforce1
• Unavailable system – www.salesforce.com/docs
Questions about what and why?
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?
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
Problem statement
A good problem statement is
• Concrete
• Specific
• Based on observations of the users
• Short
• Contains no solutions
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
Quick digressionCore 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
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
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
Prototype Example
Questions about planning?
Ready to start?
Let’s put the work into workshop!
Create a portal from an open source project
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
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
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
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
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
Upload the HTML to the database
• At the command-line, type
rake update_remote_db
Review
• At the command-line, type
heroku open
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/
Questions about the process?
Next steps
• Simple application configuration
• Updating content
• Updating metadata
• Customizing the look and feel
• Usability testing
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
Updating content
• Replace the sample files with your own HTML
• Update the table of contents file for your project
• Upload the content
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
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
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!
Thank you