Wikis – The Best Tools for Documentation and Specifications

Writing documentation and specifications for developers is a big part of my day job.  Writing clear, concise documents is very challenging.  It’s one thing to write notes for yourself, quite another to explain complex systems and the desired outcome to others.  Not only is determining a format or standard way of writing things important for clarity, but so too, are the tools one uses to communicate.  This post will focus on the tools for sharing  documentation and specifications.

The standard documentation and specification writing tool of most businesses is Microsoft Word, Visio for diagrams, and Excel for spreadsheets — or other similar tools such as Open Office, Apple’s Pages, Numbers and the Omni Group’s Omnigraffle.  I have used all of these, but found each lacking in one fundamental way; they make ongoing “knowledge transfer” difficult, if not down right impossible.

DokuWikiWhen I say “knowledge transfer”, I mean the ongoing care and feeding of systems, troubleshooting a problem or implementing an enhancement to an existing system, or set of systems.  Unless the developer, project manager or end user knows where to find the original documentation, be it a specification or write up of a process, it is much more likely that these individuals will seek out any human specialist thought to know about this program or system first and ask for a verbal “download” and knowledge transfer meeting.  Not really something that is efficient in the long run as it relies on the ongoing staffing of these so-called specialists.  I for one don’t want to be the first stop for questions about systems and programs I have documented in the past — I want my documentation to be the first thing end users turn to for help and guidance.  Document management tools such as SharePoint, LiveLink and others help by providing a search function, but I have yet to see anything beat a simple wiki for knowledge transfer.  (My favorite wiki being DokuWiki.)  Hands down, they win out.

Let’s compare using SharePoint and Word/Visio/Excel to using a wiki to better clarify this comparison.  When using SharePoint, an end user can search the contents of the SharePoint site and get a really excellent search results set showing screen previews of Office documents, filters for last updates and more.  (Truly, the search results in SharePoint are great.) However, if all of the information is stored in a file, the file must be downloaded, or at best viewed online and edited with browser plugins.   A large dataset of Office files also becomes something that must be indexed regularly and is processor intensive.  What’s more, there’s ample opportunity for the document to be shared with others outside of the document management tool which may be seen as beneficial to some people, but for me is tantamount to storing the same data in several places with things quickly getting out of sync.

If all of the documentation is done directly in an easy to read, highly searchable wiki page, then even the questions the end user may have can be added directly in the document with updates and improvements to the documentation being done by the community of users.  Every wiki I’ve ever seen tracks changes well and is extremely searchable – this is exactly what wikis were created to do.  There is no additional application needed, you just use a web browser.

So why not use a wiki for both your documentation, specifications and runbooks all in one fell swoop?  If even somewhat organized into separate namespaces, a single wiki can provide an organization with a very powerful knowledge transfer tool that doesn’t require any desktop application or special licenses.  Diagrams are really the only tool one needs an application for to create outside of the wiki.  (I would also argue for using a diagraming tool such as Open Office’s drawing tool, Visio or Omnigraffle – a future post on diagraming seems like a good idea.) A single reference point for all documentation helps prevent fragmentation of the process documents and helps facilitate a culture where knowledge transfer is done routinely, and information hoarding is no longer the norm.

[I’ll be updating this post shortly with some tips for how better to construct a wiki page, too.]

 

LastPass – Better than KeePass?

LastPassI’ve been giving LastPass a try for about a month now as a replacement for KeePass, and so far it’s a keeper.  It does more of what I need it to do, and does it better.  For those of you that may not know what either tool does, these are password safes that keep an encrypted version of all of your passwords.  You just need your master password to gain access to a file that holds all of your important passwords.  Keeping complex passwords that are unique to each site or usage is a vital way of protecting your finances and identity.  These tools make that difficult task manageable and simpler.

lastpassSo what does LastPass do that KeePass does not?  Let’s start by talking about that.  LastPass works as a browser plugin that interacts with an encrypted file that is stored on your computer, and syncs the encrypted file with the LastPass servers for use on all of your devices.  Only encrypted data is shared via the Internet.  In a sense, LastPass does what I do with KeePass using DropBox natively.

LastPass does more though.  With LastPass, you can save a profile for auto completion of forms, monitor your credit, hold secure notes, and share safely your data with other LastPass users (like your spouse or family).  Both tools will generate complex passwords for you, but LastPass does it within your browser and in a simpler fashion.

Using LastPass is easier for me.  With the credit monitoring feature, and with the very reasonable annual fee, I can also have an app on my iPhone and iPad that syncs all of my passwords, too.  But perhaps the most important thing that LastPass does that KeePass does not, is multi factor authentication.  With even the free version of LastPass, you can use Google’s free application for multi-factor authentication with your phone.  This vastly improves your security and it’s easy to use.

The bottom line, I’m sold on LastPass.  So much so, I bought  a three year subscription even though the free version really does all I need it to do.

WordPress Backup Plugin (BackWPup) – Highly Recommended

backWPupFor anyone running a WordPress site, having a database backup is a very nice thing to have.  This can be achieved through several different plugins, including one reviewed here previously — Better WordPress Security, now known as iThemes Security.  I’ve also written previously about using a shell script to for database backups, especially on 1and1.com.

But what about the physical files and content directories?  Those usually require an FTP account or more. I was recently shown BackWPup, which backups not only database files, but also your entire content directory.  It does it extremely well, and with many important options in the free version.  (The paid version offers more options and controls, but for most people, the free version alone will work just fine.)

For the non-techie crowd out there, it’s interface may seem a bit daunting at first perhaps, but it’s worth learning to use.  I’ll try to outline some settings we suggest you use, too.

Let’s Go Step By Step

  1. Go to the “Add New” link under plugins.
  2. Do a search for “BackWPup” and you should easily find the plug for safe installation via the WordPress admin.
  3. Install and activate the plugin.
  4. Once you’ve got it activated, you’ll have a couple of new menu options – one at the top of your admin page, the other in the admin below your “Settings” options.  (There may be other items in between depending on what else you’ve added — we have iTheme’s Security in our left navigation panel.)  Click the Settings option under BackWPup.
  5. You’ll now have a screen with tabs for General, Jobs, Logs, Network, API Keys, Information.
    • Let’s start with General. The default setup is probably fine for everyone with checks next to “Show BackWPup links in admin bar” and “Protect BackWPup folders with .htaccess and index.php”.
    • Jobs – Again, the default setup is probably fine, but I would recommend a couple of changes.  First, click the checkbox for “No translation.”  Next, given you are most likely on a shared server for your hosting, it’s more than polite to select one of the options for “Reduce server load.”  I set mine to “medium.”
    • Logs – If you have the ability of creating a directory above the root web level, it makes sense to put the logs there and not within the web accessible levels of your site.  If you can do this, change the path to the log file folder to this “upper” level.  I also only keep 3 to 5 log files in my folders.  I also recommend selecting the checkbox for “Compression.”
    • Network and API Keys are not likely items you’ll need to touch.
    • The Information tab can provide you with some details if you are having any problems with this plugin out of the box. (I’ve never needed it.)That covers the “Settings” option.  Let’s move to creating a “Job” now. 
  6. job-viewClick the “Add new job” option in the left nav.  This is where you’ll be doing the most amount of setup.  We have five tabs showing by default, but we will soon have a sixth.  I’ll explain as we go.  Let’s take this tab by tab, too.
    • General – First off, let’s give the job a name.  I also check the “Check database tables” checkbox but leave unchecked the “WordPress XML export.”    You’ll see another tab at the top now for “DB Check.”Under the Backup File Creation section, prepend the archive name with your site’s name perhaps.  If you are like me, you may have multiple sites backed up to the same backup directory above the web level.Now it is important to pick the right Job Destination.  I don’t want large files emailed to me, nor put to DropBox, FTP, etc.  Just store this bugger in a folder that is above the root level for the web server if possible.  Click the checkbox for “Backup to Folder” and when you do, yet another tab will be visible at the top of the section.Valdate the email addresses in the Log Files section are correct and click Save Changes.schedule
    • Schedule – I prefer to have the backup run nightly.  I select the option “with WordPress cron.” When selected, you can edit the default 3am time if you desire.
    • DB Backup – Leave things as they are here, but you may also want to select Gzip under “Backup file compression.”  I do.
    • Files – By default, the program doesn’t backup its own plugin folder.  If you are backing things up to a directory above the web root, you can deselect the checkbox for “backwpup” in the “Backup plugins” section.  I also select the option of excluding thumbnails and .tmp, .DS_Store files etc.  Leave selected the “Include special files” checkbox.
    • Plugins – I compress mine with Gzip.  There’s no use leaving the backup large in my view.

    repair-db

    • DB Check– I check the checkbox for “Try to repair defect table” as this is a safe thing to do and may save you some pain.
    • To: Folder – Because we are saving things to a folder, it’s important to select the destination and the number of backups to save.  Again, I put my backups above the web root level.  If you can do that, it’s more secure.  If not, the plugin does a good job of randomizing and providing a security through obscurity model.  I don’t keep 15 copies of my site though – only 3 to 5 depending on the size.Now to move on to running our first backup.
  7. Click “Jobs” under the Dashboard tab.  You should see a screen with the job you just created listed on it.
  8. Mouse over the name of the job and you’ll see options including a link to “Run Now” – click that!

  9. If you’ve configured things correctly, you’re backup will run and show you the progress along the way.  The Gzip process may take some time depending on the size of your site and files.  Note also that if you did as I suggested above and minimized the impact to the server resources, it will take longer to run, too.  My backups tend to take a minute to as much as 4 minutes to run for a very large site with many files.

That’s all you should need to do to safely backup your database and your content for your WordPress site.  Hat’s off to the developers at BackWPup for their excellent work!

In a future post, I’ll show how to take a backup file and either restore a site, or use it to move to a new host.

LinkedIn vs. Spam

LinkedIn - Spam CapitalI used to have a LinkedIn profile. I even provided a link to it from this website as I viewed it as a great networking tool and means of showing my CV and experience.  At some point though I came to realize that LinkedIn had to be the source for a large amount of the spam I was getting at work, and worse yet, unsolicited sales calls.

I get it.  People need to make a living and I’ve put my experience out there for all to see, including the kinds of projects I have worked on, tools I’ve used, etc.  That’s very ripe for data mining by any sales force team and my main employer is seen as a good catch by most everyone.

But I don’t want solicitations.  Neither in email, voice mail, mailers or otherwise – not in any form.  So I deleted my profile completely.  Or have attempted to.  I still get requests each week from friends, people I have worked with and vendors who want me to join their list of LinkedIn contacts.   Unsubscribing from LinkedIn’s mailing list appears to have absolutely no effect or benefit here and so I report it as spam and do what I can to block all email from LinkedIn.

Anyone out there have a better solution to share?

iThemes Security – A must have

iTheme Security Pro Earlier I wrote about a plugin for WordPress I found to be extremely valuable – Better WP Security.  Specifically, its ability to block brute force attacks against simpler passwords and username combinations.  This was a major threat to all WordPress sites almost a year ago.

Since then, there have been many updates to the Better WP Security plugin, and the developer has also been hired by iThemes to continue his development (and monetize the plugin’s advanced features).  This is great news really as the free version of the plugin is excellent and there are now a wider range of paid advanced features many web developers and site administrators should consider using, now.  The plugin is more robust than it was even; no small task for a developer starting with what already seemed to me to be a full featured security plugin.

If you are still on the older Better WP Security plugin, before you update, deactivate the older version of the plugin.  Failing to do this can make your site inaccessible as there are conflicts in the features and the plugin’s ability to update them when active.  Once you’ve updated to the iTheme’s version, you simply need to reactivate the plugin and check to see what new options are available that you should consider including in your site’s security features.

If you failed to deactivate the plugin, you’ll need to move the plugin directory for Better WP Security out of your site’s plugin folder and perhaps remove any updates the plugin did to your htaccess file.  Once you do that, you should be able to complete the update or reinstall the plugin.

What are the Traits of a Problem Solver?

dealing with disastersWho do you go to when disaster strikes?  I’ve been told I’m a good problem solver, and am often a “go-to” person for others when there are difficult technical issues to resolve.  What am I doing to be tagged in this manner?  Note, I don’t know that I actually believe I am better at solving problems, I’m just aware that I do indeed work and get paid to do so, frequently.

I decided to put together a list of attributes that I think make for good problem solving in the technical world.  I hope this perhaps helps others.  I am more than open to feedback for improvement on this list – please weigh in if you see something missing or that can be improved.

Traits of a Good Problem Solver

  • Has A Good Memory
    If you can’t remember what systems are “touched” by a specific action, you’ll be forced to rely on others that do.  Or you will have to look up and research these dependencies on your own first, or discover them in a longer, even more painful path.
  • Has Persistence
    Solving a technical glitch can be difficult, especially when it is something that is difficult to reproduce.  The most difficult problems I encounter are the ones that appear to happen randomly.  The reality is that with a technical issue, this is really never the case; the challenge is in determining what conditions must be met to reproduce the issue.  Is it only happening on a specific server?  Could it involve caching?  Have we established the exact steps taken to create the issue?  What conditions in our testing environment might be missing in the production environment that could be part of the cause?  It takes persistence to work through all of these permutations.
  • Has Patience
    While similar to persistence, this is a different trait in my view.  Perhaps an example will help highlight why I think so.  Often in web development or other technical fields, we are working on custom code or at least an integration of something in a unique environment.  How long will it take to figure out what’s wrong when you are diagnosing something that perhaps has not been seen by others before?  It could be two minutes due to some clarity or luck, or two days, or even weeks.  Being patient and persistent is what will get you through these sorts of problems.
  • Documents Everything
    Very similar to having a good memory, being one who documents everything, including problems and their resolution, really helps problem solving.  Have we seen something like this issue before?  What did we do to fix it before?  There’s nothing worse to me than diving down the same rabbit hole because you forgot how your resolved an issue previously.  Write it down in a tool that has good search features, like a wiki, or Evernote.
  • Can Write Effective Search Engine Queries
    Learning to broaden or restrict your search query is a skill.  So is knowing what keywords to include in your search.  LetMeGoogleThatForYou.com is often used as a joke by me as a none-too-subtle means of poking fun at someone’s poor attempt to solve a problem, but there are skills to using a search engine for sure.  Develop them!
  • Has a Process for Change Management
    The first question I always ask when there’s a problem reported at work is “What’s changed?”  Having a good change management system in place with a code repository as well as a testing->stage->production deployment path for your code makes answering this question easier.  If code hasn’t changed, how about data?  If neither, is there a new browser or an update that has been rolled out?  Some other environmental variable change?  Stable systems don’t usually just “break” — something has been changed that caused a problem or exposed an issue kept hidden previously.

What other traits make a good problem solver for you?  Please let me know what you think.

A New Template – Responsive Design

A long overdue change to our site came about today; a new template. It’s been years since we changed our template and while keeping the same header and color scheme for branding reasons, it’s nice to finally have a responsive design and not a separate template for mobile users. The separate template path never felt very clean or simple. The mobile view bothered me.

Again we are also reminded of the power behind a solid CMS platform. Changing our site’s look and feel was a simple thing and quite painless. Long live WordPress!