Creating a Documentation Portal
•Download as PPTX, PDF•
2 likes•3,184 views
This document discusses creating a documentation portal. It begins by introducing the speaker and defining what a documentation portal is. The speaker then discusses why one would create a portal, noting that it requires an ongoing commitment. Various planning steps are outlined, including defining problems, requirements and prototypes. The remainder of the document provides a workshop example for creating a portal using an open source project on GitHub called Red Sofa. Steps are outlined for setting up accounts on Heroku and Cloudant, cloning the project, uploading content and reviewing the portal. Additional topics covered include simple configuration, updating content and metadata, customization, and usability testing.
Recommended
More Related Content
Viewers also liked
Viewers also liked (9)
Similar to Creating a Documentation Portal
Similar to Creating a Documentation Portal (20)
Recently uploaded
Recently uploaded (20)
Creating a Documentation Portal
- 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
- 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
Editor's Notes
- 2 hours; spend 45 minutes or so through slide 20, then do a lot of showing Things to figure out – Can I do a split screen where I’m showing the presentation slide and the command-line or browser? How do I fix the fonts on the links? Timing – can I do the first 20 slides in 45 minutes? Timing – how long will the workshop sections take?
- Yes, I’ll put a proper picture of myself in here; I haven’t gotten one yet Writers think I’m a good programmer Programmers think I’m a good writer One thing that’s not on here – I’m also highly opinionated. I’m going to tell you today what I believe to be true. You probably won’t agree with everything. I think that’s great. I do hope, though, that I’ll stimulate you into thinking about your beliefs and what I have to say. Also, ask questions anytime, but please do raise your hand; sometimes I need to finish a point or I’ll forget what I’m talking about.
- Let’s make sure we’re all talking about the same thing before we get too far into this
- Does it have to be a website? No, of course not. It could be an app, a desktop program, an eBook, or, heck, it could even be a bunch of paper bound together. In the end, all of these things have more in common than they have differences. I’m going to talk about websites because that’s more fun for me to talk about.
- TODO – take screen shots, but hide them, in case there’s no network Click off to Bootstrap – Bootstrap is a framework developed by Twitter that makes it easy for a website to create a functional UI that works on most devices. Click off to Java – Java is a programming language, and so much more. All the bits of Java work together, but a typical project only uses bits and pieces of Java. Click off to Stash – Stash is a documentation portal that displays documentation from all kinds of projects. You may be interested in one or more. For example, many web developers are interested in JavaScript documentation as well as documentation for a specific framework, such as Bootstrap. Recap – three types of documentation portals, but each of them fits the definition. Their purpose is to provide documentation for one or more systems or projects. Click off to Gizmodo – Gizmodo is a website that has all kinds of interesting How To information. It’s also got a ton of other stuff, though. It’s not limited to documentation. It’s also far from complete. What do you think? Does a documentation portal have to be complete? I don’t think so; as a matter of fact, I think it’s impossible - we can never create documentation that will answer every question, so we always fall short of complete. Now there’s complete and there’s complete-enough, but that’s a judgment call that you get to make; put enough information there to help your users, but don’t put stuff there just to be complete, you won’t be helping anyone except the person that gets paid by the word. Click off to Wikipedia, say an article on Java – we all know Wikipedia; it’s got a lot of good information, but again, it fails to meet my definition, because that information isn’t specific to documenting systems or projects. It’s also not authoritative. What do you think, should a documentation portal be authoritative? I didn’t put it in my definition, but I do believe that a documentation portal should have an individual or a group that stands behind it, one that makes its best attempt to keep the documentation correct and will respond when requests are made to change it. Yes, you can see who edited what on Wikipedia, but how do you know that person knows the answer? Yes, you can fix it yourself, but what if you only know the information is wrong? Click off to Google – you can use Google to find documentation, but Google itself doesn’t deliver documentation. It does provide a valuable service, though, for users, and search should be considered when you are designing your portal. Here’s another issue with Google – sometimes you’ll find multiple versions of a document. Should a documentation portal provide every version of documentation for a project or service? I don’t know the answer to that one I believe it’s a business decision, not a design decision. However, when designing your portal, you should know the answer to that because it has a big impact.
- Don’t worry we’re not done, this is just a break for questions. If nobody asks anything, then say something like, “One question nobody asked is ‘Why do I care about the definition?’” You care because some people don’t see the dividing line between a documentation portal and a marketing portal or a sales portal or … they want to put their stuff in your site, or they want you to add links to their stuff, or they want you to consider their needs. Resist that.
- Talking about use cases always helps make things a bit more concrete
- When I first looked at this photo I thought “How does that guy know what to do? There are so many switches!” But then I thought about it a bit. How many different buttons do you push in a day to do your job? How often do you have to look up what the button does? This guy stares at these switches, knobs, gauges, etc., for hours everyday. He knows them all. Probably. I bet he still has the manual under the desk though, just in case, because, you see, he needs that information, but he gets it via a document, not a documentation portal. Look, I don’t want to scare you … much. You might be thinking “Of course I want a portal!” but it’s important to remember the trade-offs. There are worse things than delivering documentation via a PDF served up by your corporate website; one of them is having incorrect content online; another one is having your customers trying to read your documentation and they cannot because your portal is throwing errors or offline. Offline is actually better than throwing errors or giving them incorrect information, at least offline you aren’t actively causing harm. You risk all of those things, and others, having a documentation portal. In addition, things will go wrong. You can’t hire a consultant to spin up a portal and expect not to be paying them again in a month or two or three unless you are willing to commit your own resources to the project. And remember, every minute, every dollar you spend on your portal is one that you can’t use writing killer documentation.
- Missing functionality might not just be things like search, it might also include things like release scheduling. If you need to release every week and the current systems only release once a month, well, that’s missing functionality.
- database.com was a new project at Salesforce. It is completely separated from salesforce.com and thus requires a new way for customers to get their documentation. salesforce1 is an app for mobile devices; it needed documentation that was appropriate for phones and tablets www.salesforce.com – due to a variety of issues, our corporate web team did not want to serve documentation off our main web servers, so we had to spin up portals to replace that
- Don’t worry we’re not done, this is just a break
- Are you sure? Really sure? I want everyone of you to go back to your organization and check again. Even small companies have a lot of existing resources and often it’s better to use them than create your own. Why can’t you use the support site? Why can’t you use the existing knowledge base? This one always gets me. I get people coming to me all the time asking me to create a new portal, or do some other kind of work. The first thing I ask them is, “What problem are you trying to solve?”. I often get a momentary stare, and then a restatement of what they want me to do. Something like this, “Hey Steve, how’s it going?... Hey, you know that project I’m working on, we need you to create a new portal for it” “Oh, hey, yeah I remember that – what problem are you trying to solve?” “Well, we don’t have a portal, and we need one.” Bzzzzt! No portal for you! Not long ago we created a new portal for our release notes. Our release notes come out 4 times a year, are patched at least once a week, and have been available only as a PDF for over 10 years. When a manager on our team came to me to talk about having a release notes portal, after talking about it for a while, he created a one page problem statement. It talked about how the length of the PDF made it difficult for people to find the specific areas users needed. It talked about how users weren’t able to bookmark specific items in the release notes to share with other users or use in training. It talked about how PDFs are hard to read on mobile devices. Those are examples of problems that a documentation portal can solve. They also became items we could use to during design and development to ensure that the resulting portal solved our users problems. Without a problem statement, you can’t know whether you’re successful. Tech writers always complain that development teams don’t have specs. I complain when I don’t get a functional spec from tech writers. I need to know what functionality a portal supports. Search? Table of Contents? Print a page? Multiple languages? Multiple deliverables? Multiple versions? Without that you won’t get what you want or, and sometimes this is worse, you’ll get functionality you don’t want. Writing a functional requirements doc doesn’t have to be long. I usually tell people if they can’t create one that’s less than 5 pages long in less than an hour they need to spend some more time thinking about what they want. Don’t waste time doing a Google search for how to write one, or look for a Word template on it. Just start writing. If it helps, look at examples of good sites and comment on the functionality on them. Nobody minds. Lastly, a functional requirements document can help you confirm that you can’t use existing resources. Once you write this, go back and check again. Are you really sure you need to do this?
- Notice I’m not talking about technology yet. We don’t care, yet, what programming language things are written in, where it’s hosted, if the content is going to be in a database or the file system or … If we do our planning well, those are details that we are able to accept or reject on how well they meet our requirements and whether we have the resources. People can, and do, create websites using all kinds of systems and technology that I think are terrible choices. I create websites in technology that others think are terrible choices. I’m wrong and so are they. If the choices meet the requirements and solve the problems, they are the right choices.
- TODO – Create an example for us to work; make sure it includes some things to remove and add
- TODO – Create an example for us to work from
- Core + Paths: Are Halland, IA Summit 2007
- You’d be surprised by how few types of pages you need for a doc portal The first one is the one that meets your primary goal – get information to the user. It’s a documentation page. Sometimes a portal might only be that page type. The related documents are typically expressed as a hierarchical list (a table of contents), but they don’t have to be An example of a want is a “Contact Us” page. Those are important on sales sites because you want to gather details about the user. In a documentation portal, you want the user to be able to reach out to you is s/he has questions or comments on a particular piece of documentation, so they should be able to contact you from every page. Others, of course, include “About this site”, “About us”, etc. Remember your goal. Nothing should be in the portal if it doesn’t help meet that goal. Be strict! It’s far to easy to wind up with a site full of cruft with only a few nuggets of information. Those nuggets won’t be found; heck, users won’t even look for them. They know pretty quickly that your site isn’t useful and they go elsewhere.
- We do prototypes in a variety of ways. My favorite is on a whiteboard. I sketch out the boxes, and then I take pictures with my phone. I then put those into a shared network resource (Google Drive) and we iterate on them until we find agreement. We have the advantage of having corporate colors, fonts, etc., so we don’t have to specify those for each new portal type. Typically I show ratios for the box, i.e., the table of contents in the left column takes up 1x of the page width, the main topic takes up 3x of the page; the header takes up 1x of the page height and the body takes up 9x of the page height. Within the header, the search box is 2y of the height, with a 1y padding on top and bottom. Sometimes prototypes can be crippling. You spend so much time specifying everything, you never actually start coding the project. Another danger is that you get too attached to the prototype. A detail that, when you created the prototype wasn’t terribly important, may take a developer a great deal of time to implement. Make sure the developers know they can come to you when they hit something tricky. If you are creating the prototypes and the final portal, be careful not to change the design to easily. Remember you created the prototype for good reason.
- I need to add a photo here; but I don’t have a good one. I’ll create it on Monday when I’m in the office
- Don’t worry we’re not done, this is just a break
- This is what you’ve been waiting for, let’s get to it!
- Top level overview of the steps
- Top level overview of the steps
- Heroku’s minimal hosting solution, which is appropriate for testing, is free to use. For production, you’ll probably want to add capacity, which does cost money.
- Now remember when I said hosted for free in the cloud; cloudant is on a metered cost. If you exceed a certain number of allowed calls, you will have to pay.
- I’ll be using a git ui called SourceTree, mostly just to make it easier for you to see what’s going on On Macs or Linux boxes you should use rbenv or rvm for managing Ruby. If you are on Windows, use rubyinstaller.org
- If you are using a UI, use it to clone the repository using the same URL
- If you are using a UI, use it to clone the repository using the same URL
- To be filled in later
- To be filled in later
- To be filled in later
- To be filled in later
- To be filled in later
- Go to app_config.yaml and change the landing page option, then restart the app
- To be filled in later
- To be filled in later
- Installation details are in the readme file for the portal