Creating a Documentation Portal

Creating a Documentation Portal

Steve AndersonInformation [email protected]@SteveLAnderson

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

Sign up for Heroku

https://signup.heroku.com

Sign up for Cloudant

https://cloudant.com/sign-up/

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