Just about every app you, and your business uses now has an API. An API is an Application Programming Interface which is just some fancy words for one App to tell another app how they should communicate in an automated way.
Tools to help write help documents
If you are going to be writing help documentation, having some good tools will help make the process a bit easier. Here is a list of tools that I have used or would like to try.
Writing Help Documents
- Screensteps or Clarify-it
- (they are from the same company, and I really can’t see what the difference is, however Clarify-it comes with a skitch-like tool for sharing screen shots).
- Really helps you to think about the problem in a step by step way.
- Desktop and Network versions are Cheap. Just get it!
- Inbuilt screen shot and markup tools.
- There is an online version (Screensteps Live) to host your help pages, but it is expensive. Just export the HTML to your preferred help system.
Salesforce Chatter Notifications
Chatter is a great tool, and if you use Salesforce, you should be using it, and using it every day – many times a day. Chatter is great for “working out loud” and keeping others in your team up to date with what you are doing.
There is a lot of help out there about how to use chatter, including the Chatter Best Practices page on the Salesforce website and this excellent series of 9 chatter training videos created by Engineers Australia for their Chatter implementation. They may be a bit specific to just engineers and just the stand-alone chatter app, but they are very well done.
One thing I could not find enough information on is Notifications, so here is my explanation of notifications. (Well, it started out as being only about notifications, but it may now include a bit more information also).
Chatter, like most social networks, can be Push or Pull – eg you can “pull” the information towards you by going to look at your chatter feeds, or have chatter “push” the information out to you, via notifications.
Using Graphviz in Confluence – A Tutorial
I have always liked to do flowcharts. Simple flowcharts are good flowcharts – a picture tells a thousand words. I also love Confluence, and love the hierarchical nature of the structure of Confluence – much like a flowchart. Now we combine the two and we have a great way to communicate information. Enter Graphviz and the Graphviz Confluence Plugin.
This is a Tutorial to get you started with using Graphviz in Confluence to produce flowcharts quickly and easily.
[Read more…]
Confluence is not a Word Document
You’ve just installed a shiny new Confluence set-up for your organisation, now where do you start with writing content for it? Here are my thoughts on writing for Confluence and a few tips and links to help get you started.
My two main points for writing content for Confluence are:
- Confluence is not a Word document, and
- Confluence is not a file share.
Continue reading about Confluence not being a Word Document…
Three great free Apps for Salesforce Admins
In my last post on Salesforce, I talked about the methodology I use when tackling a Salesforce implementation. One of the key points to my methodology is to do code only where it is absolutely necessary (In fact, this is my methodology when using almost any product).
I came across a situation for a client that I knew would require a trigger – the business requirement is that they enter the names of the two people involved in the purchase into the lead. These two people (Person A and B) must exist as separate Contacts in their own right but be joined as part of this purchase (Person A may then make another purchase with Person C at another time). For this scenario, the standard Salesforce Convert Lead to Opportunity button could not be used.
[Read more…]
Thinking Like Salesforce
I’m a bit of a way on the path to becoming a Salesforce Consultant (not quite certified yet, but that’s just because I have to sit for the exam). I love Salesforce and what you can do with it, but then sometimes you just come unstuck over the smallest of details and think that it is the worst piece of software in the world.
I’m a database designer first and foremost, so I think in normalisation terms – I knew how to design databases before I even knew what normalisation was (“Oh, really, it has a name?”), and it irks me to de-normalise but I do understand that it is sometimes necessary for business reasons (yes, I’m not talking about data warehousing or noSQL data models either).
So when you come across something as simple as being able to report on every aspect of the data in your database, and find that it just can’t be done in Salesforce (and yet, it can be done quite easily in Access 2007+), then you need to re-think your design. (And while I’m in a ranty mood, I just can not believe that Salesforce have not even acknowledged this to be an issue let alone provided some options or even done anything to fix it!).
So, I’m coming to the conclusion that it just takes a bit of re-thinking about how you are going to achieve the requirements of your client in Salesforce and here are some tips I’ve thought about along the way:
- Challenge the Requirement – yep, I said it – requirements are NOT set in stone. Sometimes people may think their requirements are absolutely necessary, but if you can discuss it, throw some ideas around and maybe think of another way around it, then there might just be another way to achieve what they want.
- Look in the App Exchange – first up, see if someone else has had this problem and has done 90% of the work for you already. Even if it is paid app, it is probably going to be more robust than anything you can make and be more cost effective.
- Create Procedures rather than Solutions – this is sort of the cheapskates way around things – can’t afford that fantastic app that does all the things that you want? OK, then if we have to replace that with 5 steps, that are documented well, that the user has to do each time they need to do this, is that OK? Sometimes the answer may be yes, and sometimes you can use that thinking to justify the ROI of the App purchase price per month.
- Create a Formula Field – Formula fields in Salesforce are very powerful and can be used in many ways. Did you know that you can’t do a Global search for the text inside a lookup field (eg the Account Name on a Case)? No? Well it sucks that you can’t! So create a text formula field that references the Account.Name that is linked on the Case, make it not visible to the users, but it can still be used for search. I can also use a formula field for reporting – eg link the Account’s State field into the Case via a formula, so I can quickly summarise Cases by State.
- Create a Workflow Rule – Similar to formula fields, create a text field that is updated by a Field Update workflow to put data where you want it to be. Eg, you can’t do field level auditing on long text fields (it will tell you when the field changed and who changed it but not what it was changed from or to). So create a Audit field and populate it each time the long text field is changed. I have documented a solution on this blog.
- Create a Button or a Link – A lot can be accomplished with a button or a link. Yes, you could write a trigger to create a new record in Object X, but then you have to code it, write test classes for it and maintain it. If it’s not that critical to the process, that it requires all that coding, then just create a button with a URL to prepopulate the fields on Object X. I even put things in the pre-population data that will cause an error so that the users need to stop and think about what they are creating this record for, and what else do they need to update. Other great links you can create are a link to Google Maps with a search query or a link to look up the ABR website based on the Account Name or ABN
- Add a Visualforce Page to a Standard Form – Creating Visualforce pages is easy and is not a big maintenance headache like coding is. Where I used this to great success is on a child detail record form – I wanted to show some of the field values from the header record (this is one of those infuriating things that should be easy out of the box, but it’s not). Create a simple visualforce page containing just those few fields, and style it to look like the regular detail page, and then add that visualforce page as a section in the standard form. You could even embed details from an external website into a Visualforce page (eg an image of the product the client has purchased from your web site).
- De-normalise – Yes, when it comes to the crunch, throw all your instincts out and de-normalise. I’m going to use this idea to get around the issue with reporting on multi select picklists. I have a picklist with 50 values in it, all that need to be reported on. Based on the historic data most Cases only choose 2 or 3 of the available options, so I will create 3 fields, each based on a lookup to the list of options and then report on ‘Field1=XYZ or Field2=XYZ or Field3=XYZ’ to show all Cases that have chosen that option (using URLs to pre-populate the report parameters really helps with this too).
- Use External Systems – You know what? Salesforce is not perfect and may not be the one and only one system that you use. If I do want to do the reporting the way it has previously been done, I know that Access can do it, so I can just export the data to Access when that report needs to be done, and run the report in Access. Yes, it’s a bit more fiddly but there are some great export tools to make it easier.
- Change the Process – Yes, I know, quite unthinkable to have to change your processes to work with software – but this is not bespoke software designed especially for you. You will get 95% of the benefit out of using Salesforce so it’s OK to challenge the other 5% and possibly change your processes. It would be a shame to walk away from a Salesforce implementation because it just can’t do a few minor things in your procedures.
- “Suck it and See” – You might come up with a solution that is not 100% the way you want it to work but maybe it will be OK. Flag it as something to come back to in 6 or 12 months to see if it is still a major headache for the client or it is just something they have learned to live with or have even forgotten about. Sometimes a requirement that is thought to be a “must have” at the beginning could have come about due to a poorly designed old system or a lack of understanding of how Salesforce works – and by the time Salesforce is bedded into the organisation that requirement may not be as important as it was before. Just don’t forget to re-visit it and ask the question in 6 months time.
You may have noticed that none of these solutions involve coding. Yes coding is one way to tackle the problem, but hopefully it’s the last resort. It’s not that I don’t advocate coding as a solution, it is just expensive, time consuming and difficult to maintain. It is great if you are a large organisation and have an in-house team of developers who are going to maintain it and tweak it as your requirements change, but if that is the case, why are you using Salesforce?
Actually I think these ideas would work with any “platform” product that you evaluate for you or your client’s organisation, whether it be Microsoft CRM, SharePoint, Confluence or any ERP system. These systems will get you to a point – where you take it from there is up to you.
I might add some more things to this post in the comments as I think of them.
The “One Thing, in One Place, Once” Rule using Confluence
As a database designer, I am a huge believer in the “One Thing, in One Place, Once” rule (aka Normalization, in database speak).
As I’m currently building a full enterprise help system in Confluence, of course I’m going to extend that rule to my help content also.
I started with the ideas of Re-Using Content in Confluence and Building an Inclusions Library as written by Sarah Maddox from Atlassian, then as I started to need more features, I moved on to some of the other methods for content re-use, so I thought I would summarise them.
There are 4 ways that I use to re-use Content. The {include} macro, {excerpt} macro, the {multi-excerpt} macro and the {builder-show} macro. The {include} macro is the simplest and the {builder-show} is the most complex and most powerful.
I’m mainly using these features to produce a printable version of the help content, which is a bit different than the Wiki content, as it is presented in a linear fashion, and doesn’t have as many links to content unrelated to the narrative of the document.
Have a look at the following diagram, it shows some examples of the 4 macros that I regularly use. The first box is the base page, where the content is originally created. The second box is the wiki markup mode of the page where the content is included. The third box is what will show in the final layout of the page.
(click to enlarge)
Include Macro
The {include} macro simply includes the full content of the base page into the display page.
I use this macro for small notes and info panels that are used in multiple places.
On the display page enter the following in wiki markup mode:
{include:Base Page}
The {include} Macro is a bit limiting as most of my main pages has a section at the top that shows how you navigate to this screen – I don’t need that in my printed document.
The {include} Macro can be used from other spaces with the following syntax {include:SPACEKEY:Page name}. (Also see the Perimeter Plugin from CustomWare for the {secure-include} macro, which is useful for including from spaces that the user does not have access to).
Excerpt Macro
The {excerpt} macro allows for a defined section of the base page to be included in the display page. The content that is between the two {excerpt} tags can be included in the display page.
On the display page enter the following in wiki markup mode:
{excerpt-include:Base Page|nopanel=true}
I use this macro only occasionally for very simple pages as I find it a bit limiting as it can only be used for one continuous section of content.
The {excerpt-include} macro can only be used for content within the same space, similar to the {include} macro.
Multi Excerpt Macro
The {multi-excerpt} macro is part of the Multi-Excerpt Plugin. This is a very cool plugin, but it does cost – luckily it’s not that expensive.
This plugin allows you to have multiple excerpt sections in the base page appear in the display page – the cool thing is that the excerpts can be displayed in any order you want.
Each excerpt defined must have a unique name on the page.
On the display page enter the following in wiki markup mode:
{multi-excerpt-include:pageTitle=Base Page|name=excerpt1|nopanel=true}
The addition of the spacekey parameter allows the Multi-Excerpt macro to be used across spaces, so it is quite useful.
I use this quite a bit, but it still has one limitation – you can’t nest multi-excerpt macros – but I may be asking for a bit much there.
I use it to include the overall page description, then the screen shot, then the steps on how to use the screen, but exclude the navigation and the links to other pages, in my printed content.
Builder-Show Macro
The {builder-show} macro is part of the Adaptavist Theme Builder Plugin and is the coolest macro. The way I use it basically turns Confluence into a bit of database – yes it’s a bit complex to set up, but once it’s set up, the maintenance of the pages is going to be very easy.
Here’s how I use it – There are a number of fields on each screen. The same field can be used in multiple screens, and the same description is applicable to each screen. If I keep the description in one page, then I can use that description in multiple pages – but it only ever needs to be updated in the once place in future.
With the same field description being used on a few screen pages, and the printed manual for those screen pages, it can be used in up to 5 places – all based on the same source.
The main set-up for this macro is done on the base page, where we put in codes to say which pages the content will display on.
{builder-show:title=Display Page} This is the first excerpt from my page {builder-show} {builder-show:title=Base Page} This is the rest of my page {builder-show} {builder-show:title=Base Page, Display Page} This is the second excerpt from my page {builder-show}
The first and third sentences will be shown on the display page, and the second and third sentences will be shown on the base page. Sentence 3 will be show on both pages.
The display page contains the one macro – the {import} macro.
{import:Base Page}
And that’s all there is to it :).
There is one small limitation with this macro – the content on the display page must be shown in the same order as it is on the base page.
I hope that has helped give you some ideas on how to re-use content in your Confluence site, and if you have any more cool macros to share, please leave a comment.
Websites for Community Groups
This is the second in a series of posts for Creating a Web Presence for your Community Group. In this post I will take a look at the Web Site itself.
Web Content
- About the group
- History of the group
- The Committee
- Rules of the group
- Any legal obligations (eg if you are an incorporated association)
- Minutes
- News
- Contact details
- Locations of events, clubs or meetings
- Photos and details of past events
This content can be broken up into Static and Temporal content. The static content is the information about the club itself, the committee and location and contact details. This information doesn’t change that often and is updated only when it needs to be. The temporal content is the information that is applicable to a particular point in time only. This is news, details of events, minutes etc. If people want to look back at old content that is fine, but only the most recent and relevant content should be the most visible on the site. I will put Upcoming Events into another category because that is going to be a separate post.
One thing to be aware of is the privacy of the individuals in your group. Have a discussion in your group about what your web privacy policy will be and make it known to the group (via the minutes or some formal communication). Allow people to opt out if they don’t want their names, photos and details online. See the post on Email for some more ideas about how to preserve people’s privacy.
WordPress
This is where I’m going to delve right in and say use WordPress for your site – yes that WordPress – the one that does “blogs”. WordPress is NOT just for blogs, it can be used for almost any kind of web site – including a shopping site. Wordpress is a Web Content Management System – that just means that it is an easy to use web based system that allows for the content to be separated from the design. So when you need to write a news article, you just write the article, you don’t have to worry about how it looks on the page, because that is already handled for you. Other Web CMS’s are Joomla, Drupal and Squarespace (to name just a few of the thousands there are out there).
WordPress comes in two flavours – self hosted (WordPress.org) and hosted (WordPress.com). This post will mainly focus on WordPress.com as it is free, simple to us and suits 99% of the website needs for a community group. If you want to host your own WordPress install you will need a web hosting provider. There are thousands and thousands of them out there, but for a simple WordPress hosting service you should not have to pay more than about $150 per year. Self Hosted WordPress has many features that WordPress.com does not have, including the ability to extend your site by using PlugIns, control the look of the site exactly using themes and CSS and even use custom code to make it do almost anything you could imagine. I like this article that explains self hosted WordPress in a bit more detail. If you start with WorPress.com and want to move everything to a self hosted WordPress at a later date, then it is a simple process. So there is nothing stopping you from starting now with a WordPress.com site.
Setting up WordPress
WordPress.com is simple to set up – it takes just a few minutes and you have your basic site set up – for FREE. From there you need to choose a theme. WordPress.com at the time of writing has close to 100 themes to choose from, so you should be able to find one that suits your community group. (If you want more control over the look and feel then you can pay US$15 per year to be able to apply custom CSS to your site). My advice is to stick with a simple theme with a custom header (where you can put your logo), and maybe custom colours. (This is why I love the Vigilance theme that this site is based on). See more information about Themes from the WordPress.com support site, including the great video. You may need to play around with a few themes until you find the one that is right for your group. It may not be 100% perfect, but this is where you trade off perfection for cost – remember so far this site has cost you nothing but a few hours of your time.
The next thing you want to do is create some content. Your static content such as committee, about the group etc will be created with Pages. Your temporal content such as news, events and minutes will be created as Posts. Each Post will be given a Category (eg News), which will help you navigate to only the posts about news or events. As WordPress is orignally designed for blogs, by default he Posts page will be the first page that you see when you come to the site. You need to change this to be one of your static pages. You set the home page in the Reading Options settings.
The next thing you need to set up is the Widgets that display in the sidebars. (Sidebars can be on the left, right or bottom of the page, depending on the theme you have chosen). In the sidebar, I would suggest at least some navigation to the latest news stories, some information on how to contact your group a search box, and a links to any other web sites that your group has (eg you may have images on flickr or a twitter account or facebook page). In the Events post I will talk about how to put an events widget on your sidebar.
Map your Domain to your Site
Once you are happy with the overall site, it is time to link the site to the Domain and then publicise the fact that you have a web site now. To link the Domain to the web site follow the steps to Map an Existing Domain on the WordPress.com site. This costs US$10 per year. There are three steps to this process.
- Nameservers: You will need to go back to the domain hosting provider and log into your domain management to update the Nameservers. This is where it pays to have a good hosting provider as they will have some online help on how to do that, or they will be able to help you set it up.
- Payment: You will need a Paypal account to do this (but you probably want a paypal account anyway). Go to Settings > Domains in your site to do this.
- Mapping: Once the Nameservers are set and you have paid for it you can then set the mapping up. Go to Settings > Domains in your site to do this.
This process can be a bit fiddly and don’t expect it to take a few minutes. But once it is done, it never needs to be done again (except paying for it each year).
That’s it! A simple web presence online, with your domain name for a total cost so far of under $100 for the domain and the domain mapping.
See the next posts in the series for more things to do with your website such as events and applications and ongoing management of your site.