Do you fight to keep good documentation? Do you struggle with others that don’t make any documentation? Do you find the entire process of creating documentation too cumbersome? Do you find situations where you know someone made documentation but you can’t find it? Do you use an web based wiki today that absolutely sucks for handling screenshots? Do you find documentation is in the inbox of your IT employees and when they leave the company, no one can find anything anymore? If any of these conditions are true, what would you say if I could provide a way using nothing more than an email give you and your team a centralized shared document repository with fantastic native inline screenshots using nothing more than Control-C and Control-V? What if you could then share those links with anyone in your organization and as corrections and improvements are made, edit the shared documents using nothing more than Microsoft Word?
I’ve spent a lot of time investigating IT documentation products and I’ve found them all to be incredibly lacking when it comes to screenshot management and formatting with things like tables and colors. Fortunately I’ve now in my opinion at least, solved this issue and found a way to provide brain-dead simple single click documentation that anyone can make. In fact it’s so easy, you can chastise your peers for not doing documentation! Oh and on top of all of this? You can implement it without any additional cost beyond the Windows licenses you already own. That’s right, free! The requirements are:
1) Active Directory Domain Controller
2) Exchange Server
3) Windows Client with Microsoft Outlook and Word
4) Sharepoint 2013 Foundation (aka the free one)
The basic concept is to leverage the already fantastic editor that Outlook provides including its ability to add inline images using nothing more than copy and paste from your clipboard. A user creates a new email and creates their documentation just as they would any other email. Once they are done, they send the message (including just as a cc if desired) to an email address. Sharepoint monitors this email address constantly and takes anything sent to it and adds it to a document library in SharePoint including meta data such as the user that uploaded it. It also indexes the content for search that can be used by anyone in your organization with access to this SharePoint site.
In other words, you can make documentation as easily as:
CREATE
WHICH BECOMES STRUCTURE AND SEARCHABLE
AND VIEWED BY ANYONE WITH A SINGLE CLICK
If this sounds interesting to you, stick around because I’m going to walk you through literally every single screen required to set this up from end to end. I built an entirely new environment from scratch just to produce this HOWTO. The only steps completed that are not featured here were:
- Installing Windows / Cloning the VMs
- Installing Active Directory and Exchange
- Installing Office on my Windows 8.1 client computer
Note that these instructions are designed for Windows 2012 R2 / Windows 8.1 but if you are still on Windows 2008 R2, you can follow the exact same steps. Oh and one more thing. If you’re going to be taking screenshots, you want to make sure you’re doing it as quickly and as productively as possible. So to aid you in that task, consider using Greenshot. I’ve gone into a lot more detail here: https://pleasework.robbievance.net/the-right-way-to-take-screenshots/
Let’s begin shall we!
SharePoint 2013 Foundation Installation
SharePoint 2013 Foundation with SP1
http://www.microsoft.com/en-ca/download/details.aspx?id=42039
Note: If you try to install the original (non SP1) SharePoint 2013 Foundation onto a Windows 2012 R2 box, the installer will fail trying to install the IIS Application role. Using the SP1 installer gets around this issue
- Run the SharePoint Foundation executable installer
- Choose Install software prerequisites
- You’ll get a list of what will be installed. Press Next
- As noted above, the step below will fail if you are running on Windows 2012 R2 and are using any release of SharePoint foundation prior to SP1
Note this step requires internet access as additional software is downloaded
- Press Finish and reboot when prompted
- Once restarted, the installer will continue where it left off
- You’ll be prompted to restart again. Do so
- Yes we are back here again. Be patient
- All prerequisites have been installed. Press Finish
- Run the installer executable again but this time select Install SharePoint Foundation
- For the Server Type, choose Stand-alone. For our purposes as an attempt to build a single server host our HOWTO repository, this is ideal. Press Install Now
- When prompted, leave the wizard selected and press Close
- Press Next
- Press Yes
- Wait while SharePoint is configured. This process will take a while
- Press Finish
- You’ll then be taken to the SharePoint landing page. Notice the search is missing in the top right. You need to install the latest Cumulative Update to fix this. As of this writing, that is July 2014
- Unfortunately, this update is behind the Microsoft hotfix email wall. You have to provide an email address and they’ll email you a link.
- You can do that here: http://support.microsoft.com/hotfix/KBHotfix.aspx?kbnum=2882999
- Once downloaded run the installer. You’ll also note SharePoint itself around 860MB while the update is 1.1GB. Isn’t that wonderful?
- Choose a folder to extract the installer to
- Accept the terms and press Continue
- Note this process takes a long time. I don’t know why since the CPU is idle for most of it but this could be upwards of 40 minutes…
- Eventually, you should be asked to reboot. Press Yes
- Once the server boots back up, open your web browser and browse to http://[computername]. You should find the search is now present
- Next we need to install the SMTP Server feature. Open Server Manager and choose Manage / Add Roles and Features
- Press Next 4 times to get to the Features selection screen
- Select the SMTP Server service and press next until the feature is installed
- Next we need to configure Sharepoint to allow incoming email. From the start menu, open the Sharepoint Central Administration control panel
- Press System Settings
- Choose Configure incoming e-mail settings
- For Enable Incoming E-Mail, choose Yes
- Leave the rest of the settings as default. Note the email address is going to be [listname]@[servername.domain.com. We can get fancy with this later if we want but for now this will work just fine. Make a note of the address
- Press OK
- At this point you can do all sorts of design with Sharepoint. For now, we’re going to assume the main landing space will be our repository
- Go back to the main site and press REMOVE THIS to clean up the page a little bit
- Go to the sprocket and choose Site Settings
- Under Look and Fee, choose Title, description, and logo
- Update the title and description as you see fit
- Select Documents on the left and then the Library tab and finally Library Settings on the right
- Choose Incoming e-email settings
- Select Yes to allow this document library to receive email. Provide the email address howtos@corpsp1.corp.local
- Choose Yes to save the original email as that will be our HOWTO document
- For now, select Accept e-mail message from any sender. For production, you’d likely want to restrict this
- At this point we need to configure a new Exchange Send Connector to forward mail to the SMTP server on our SharePoint box
- This is going to vary depending on your mail server but for Exchange 2013 it is Mail flow / send connectors / add
- For the name, type in the domain that you recorded above which in this case is corpsp1.corp.local
- Configure it as Custom
- Type in the IP address of your SharePoint server. You can validate if your SharePoint mail server is working by running the following command from your Exchange server: telnet [SharepointIP] 25
- For testing, do not require authentication
- Specify the send connector address space as the FQDN SharePoint provided. Do not use a scoped connector
- For the source server, choose your Exchange server from the drop down list
- The last thing we need to do is make a configuration change to allow HOWTOs to be viewed directly in Internet Explorer
- Open the Central Administration page and choose Manage web applications
- Single click on your SharePoint site and choose General Settings / General Settings
- Scroll down and find the section for Browser File Handling and choose Permissive and press OK
- That’s it! You’re now ready to use your HOWTO repository. How do you use it? Simple. In Outlook, create a new email and send it to howtos@corpsp1.corp.local
- Include whatever pictures and formatting you’d like. When you’re done, hit Send. That’s it.
- In a few moments, it will now appear in your repository. Everyone in your team now has shared searchable access to all of your HOWTO documents that can be generated as easily as an email!
- Clicking on the link shows you what you’d expect
- But what if you’d like to make a change? Simple. You can edit it with Microsoft Word. From the Library tab choose Open with Explorer
- By default, these files are in an .EML format which by default open in Outlook. Right click on the file and choose Open With
- Select Word and be sure that Use this app for all .eml files is selected
- Now simply double click and edit the file to your hearts content. When you’re done, simply press Save. It will be written back to SharePoint automatically.
- Bonus: You can enable version history so you can track changes over time
