Posts Tagged 'Help'

September 24, 2013

Four Rules for Better Code Documentation

Last month, Jeremy shared some valuable information regarding technical debt on SLDN. In his post, he discussed how omitting pertinent information when you're developing for a project can cause more work to build up in the future. One of the most common areas developers overlook when it comes to technical debt is documentation. This oversight comes in two forms: A complete omission of any documentation and inadequate information when documentation does exist. Simply documenting the functionality of your code is a great start, but the best way to close the information gap and avoid technical debt that stems from documentation (or lack thereof) is to follow four simple rules.

1. Know Your Audience

When we're talking about code, it's safe to say you'll have a fairly technical audience; however, it is important to note the level of understanding your audience has on the code itself. While they should be able to grasp common terms and development concepts, they may be unfamiliar with the functionality you are programming. Because of this, it's a good idea to provide a link to an internal, technical knowledgebase or wiki that will provide in-depth details on the functionality of the technology they'll be working with. We try to use a combination of internal and external references that we think will provide the most knowledge to developers who may be looking at our code. Here's an example of that from our Dns_Domain class:

 * @SLDNDocumentation Service Overview <<< EOT
 * SoftLayer customers have the option of hosting DNS domains on the SoftLayer
 * name servers. Individual domains hosted on the SoftLayer name servers are
 * handled through the SoftLayer_Dns_Domain service.
 *
 * Domain changes are applied automatically by our nameservers, but changes may
 * not be received by the other name servers on the Internet for 72 hours after
 * your change. The SoftLayer_Dns_Domain service does not apply to customers who
 * run their own nameservers on servers purchased from SoftLayer.
 *
 * SoftLayer provides secondary DNS hosting services if you wish to maintain DNS
 * records on your name server, but have records replicated on SoftLayer's name
 * servers. Use the [[SoftLayer_Dns_Secondary]] service to manage secondary DNS
 * zones and transfers.
 * EOT
 *
 * @SLDNDocumentation Service External Link http://en.wikipedia.org/wiki/Domain_name_system Domain Name System at Wikipedia
 * @SLDNDocumentation Service External Link http://tools.ietf.org/html/rfc1035 RFC1035: Domain Names - Implementation and Specification at ietf.org
 * @SLDNDocumentation Service See Also SoftLayer_Dns_Domain_ResourceRecord
 * @SLDNDocumentation Service See Also SoftLayer_Dns_Domain_Reverse
 * @SLDNDocumentation Service See Also SoftLayer_Dns_Secondary
 *

Enabling the user to learn more about a topic, product, or even a specific call alleviates the need for users to ask multiple questions regarding the "what" or "why" and will also minimize the need for you to explain more basic concepts regarding the technology supported by your code.

2. Be Consistent - Terminology

There are two main areas developers should focus on when it comes to consistency: Formatting and terminology.

Luckily, formatting is pretty simple. Most languages have a set of standards attached to them that extend to the Docblock, which is where the documentation portion of the code normally takes place. Docblocks can be used to provide an overview of the class, identify authors or product owners and provide additional reference to those using the code. The example below uses PHP's standards for documentation tagging and allows users to quickly identify the parameters and return value for the createObject method in the Dns_Domain class:

*
     * @param string $objectType
     * @param object $templateObject
     *
     * @return SoftLayer_Dns_Domain
     */
   public static function createObject($objectType = __CLASS__, $templateObject)

Keeping consistent when it comes to terminology is a bit more difficult; especially if there have been no standards in place before. As an example, we can look to one of the most common elements of hosting: the server. Some people call this a "box," a "physical instance" or simply "hardware." The server may be a name server, a mail server, a database server or a web server.

If your company has adopted a term, use that term. If they haven't, decide on a term with your coworkers and stick to it. It's important to be as specific as possible in your documentation to avoid any confusion, and when you adopt specific terms in your documentation, you'll also find that this consistency will carry over into conversations and meetings. As a result, training new team members on your code will go more smoothly, and it will be easier for other people to assist in maintaining your code's documentation.

Bonus: It's much easier to search and replace when you only have to search for one term.

3. Forget What You Know About Your Code ... But Only Temporarily

Regardless of the industry, people who write their own documentation tend to omit pertinent information about the topic. When I train technical writers, I use the peanut butter and jelly example: How would you explain the process of making a peanut butter and jelly sandwich? Many would-be instructors omit things that would result in a very poorly made sandwich ... if one could be made at all. If you don't tell the reader to get the jelly from the cupboard, how can they put jelly on the sandwich? It's important to ask yourself when writing, "Is there anything that I take for granted about this piece of code that other users might need or want to know?"

Think about a coding example where a method calls one or more methods automatically in order to do its job or a method acts like another method. In our API, the createObjects method uses the logic of the createObject method that we just discussed. While some developers may pick up on the connection based on the method's name, it is still important to reference the similarities so they can better understand exactly how the code works. We do this in two ways: First, we state that createObjects follows the logic of createObject in the overview. Second, we note that createObject is a related method. The code below shows exactly how we've implemented this:

     * @SLDNDocumentation Service Description Create multiple domains at once.
     *
     * @SLDNDocumentation Method Overview <<< EOT
     * Create multiple domains on the SoftLayer name servers. Each domain record
     * passed to ''createObjects'' follows the logic in the SoftLayer_Dns_Domain
     * ''createObject'' method.
     * EOT
     *
     * @SLDNDocumentation Method Associated Method SoftLayer_Dns_Domain::createObject

4. Peer Review

The last rule, and one that should not be skipped, is to always have a peer look over your documentation. There really isn't a lot of depth behind this one. In Development, we try to peer review documentation during the code review process. If new content is written during code changes or additions, developers can add content reviewers, who have the ability to add notes with revisions, suggestions and questions. Once all parties are satisfied with the outcome, we close out the review in the system and the content is updated in the next code release. With peer review of documentation, you'll catch typos, inconsistencies and gaps. It always helps to have a second set of eyes before your content hits its users.

Writing better documentation really is that easy: Know your audience, be consistent, don't take your knowledge for granted, and use the peer review process. I put these four rules into practice every day as a technical writer at SoftLayer, and they make my life so much easier. By following these rules, you'll have better documentation for your users and will hopefully eliminate some of that pesky technical debt.

Go, and create better documentation!

-Sarah

November 20, 2012

Community Development: Catalysing European Startups

SoftLayer works hard and plays hard. A few weeks ago, I traveled to Dallas for the first "Global Catalyst Summit"* where the community development teams in Europe, Asia and the United States all came together under one roof to learn, strategize and bond. What that really means is that we all experienced a week of hardcore information flow and brutal fun.

The onboarding process to become a part of the SoftLayer's Community Development (Catalyst) team is pretty rigorous, and traveling to Dallas from Amsterdam for the training made it even more intense. In short order, I learned about the roots of the Catalyst program and why SoftLayer is so interested in investing in helping startups succeed. I got the low-down on the hundreds of companies that are taking advantage of the program right now, and I was inspired by the six incredible people who focus exclusively on the Catalyst program at SoftLayer ... And Big Tex:

SoftLayer Community Development Team and Big Tex

When the whirlwind week of orientation and training came to an end, I came to a solid conclusion: I am working at SoftLayer for a reason. I believe SoftLayer has the most kick-ass global on-demand technology platform out there, and our focus on innovation and automation is reflected in everything we do. On top of that, we give that platform to startups to help springboard their success. I get to work with a community of world-changers. Needless to say, that's an amazing conclusion to come to.

As a member of the Catalyst team in EMEA (Europe, Middle East, Africa), I can provide signficant resources to entrepreneurs who are building awesome new applications and technologies that are making a difference locally, regionally and globally. Anna Bofill Bert and I work out of SoftLayer's Amsterdam office, and we are fully dedicated to helping startup and developer communities in our region.

As a review exercise and a way to educate the audience that may be unfamiliar with Catalyst, I thought I'd bullet out a few of the main ideas:

What is Catalyst?

The SoftLayer Catalyst Startup Program provides:

  • A generous monthly hosting credit toward dedicated, cloud or hybrid compute environments for a FULL YEAR (Ideal for dev-ops/next generation startup compute applications who want high performance from the start).
  • Direct connection to highest level programming team at SoftLayer — Our Innovation Team. Participating companies get help and advice from the people that are writing the book on highly scalable, global infrastructure environments.
  • Connection to the SoftLayer Marketing and PR Team for help getting spreading the word around the world about all the cool stuff participating startups are doing.

We reach startups by listening to them and meeting needs that all of them express. We are telling the SoftLayer story, networking, making friends, drinking too much and travelling like mad. In the course of a month, we went to Lean Start Up Machine in Rotterdam, Structure Europe in Amsterdam, Pioneers Festival in Vienna, HowToWeb in Bucharest and we managed to complete a quick tour of startup communities in Spain.

Like our peers on the US team, we partner with incubators and accelerators to make sure that when startups look for help getting started, they also find SoftLayer. We're already working with partners like Springboard, Seedcamp, GameFounders, Startup Sauna, the INLEA Foundation and Tetuan Valley, and the list of supported communities seems to grow daily. When the portfolio companies in each of these organizations are given access to the Catalyst program, that means SoftLayer's Catalyst customer base is growing pretty phenomenally as well.

What I actually like most about how we help startups is the mentorship and office hours we provide participating companies as well. SoftLayer was founded by ten guys in a living room in 2005, and we've got hundreds of millions of dollars in annual revenue as of 2012. That success is what the SoftLayer team is excited to share insights about.

Hustling is a major part of startup culture, so it's only fitting that I feel like I had to hustle through this blog to get all of my thoughts down. Given that SoftLayer EMEA is a bit of a startup itself, I'm happy to be practicing what we preach. If you'd like more information about Catalyst or you want to apply, please feel free to hit me up: esampson@softlayer.com

We want to be part of your company's success story.

-@EmilyBlitz

*Note: As an homage to Big Tex after the fire, we referred to our meeting as the "Global Catalyst Summit with Big Tex" at the Texas State Fair. We hope to see you back in action in 2013, Big Tex!

April 3, 2012

Tips and Tricks - How to Use SFTP

Too often, new customers can get overwhelmed by a small administrative task on a Linux server. One of the more common questions I see in technical support is when a drive partition runs out of space. The website appears offline, and on of my coworkers advises you to just free-up some space. "Just?! Where can I find files that are deletable without affecting my website?"

Don't worry ... it's really quit simple. If you can use FTP (File Transfer Protocol), you can handle this bit of server management. Depending on the exact problem, we might instruct you to free up space by removing files in one of the following directories:

  • /var/log
  • /usr/local/cpanel
  • /usr/local/apache/logs
  • /usr/local/apache/domlogs

The reason these directories are usually overlooked is because they are not accessible by normal FTP users — users who only upload website content. When you upload website content to the server via FTP, the FTP user is limited to the directory structure for that website. Directories starting with "/var" and "/usr" cannot be accessed by these non-root users (The "root" user can access anything). And while root is a powerful user, for the sake of security, it is not normally allowed to log in over FTP because FTP is not secure ... That's where SFTP (Secure File Transfer Protocol) comes in.

Most FTP clients support SFTP, so you don't have to learn a new environment to securely access any file on the server. Every FTP client is different, but I'll illustrate with FileZilla because it's free and available on Mac, Windows and Linux. If you don't already have an FTP client, I highly recommend FileZilla. Because there are a few ways to use FileZilla to get an SFTP connection, I can share different options for you to try:

Quick Connect

The Quick Connect bar is the quickest way to connect to your server. Start FileZilla and look immediately under the toolbar for the Quick Connect bar:

SFTP Tutorial

Enter the hostname (IP address or domain name), “root” in the Username field, the root password in the Password field, and “22″ in the port field. Remember, port 22 is for SFTP, the same as SSH. Click the Quickconnect button to connect.

Using the Site Manager

The Site Manager lets you save your login details. Start FileZilla and you'll see the following:

SFTP Tutorial

To open the Site Manager, click the left-most icon in tool bar or go to File >> Site Manager in the menu.

SFTP Tutorial

Enter an IP address or domain name for your server in the Host field, and select "SFTP" as your protocol. You'll enter the root user's login information, and you're ready to connect by clicking the "Connect" button or you can click the "OK" button to save and close the dialog box.

If you just saved your settings and the Site Manager is not open, click the Site Manager icon again. From there, you can select the site under the "Select Entry" box, and you just have to click "Connect" to initiate the SFTP connection with your saved settings.

If you see a pop-up that warns of an "Unknown host key," clicking the "Always trust this host, add this key to the cache" option will prevent this interruption from showing in the future. Once you click "OK" to complete the connection, your FileZilla screen should look like this:

SFTP Tutorial

Notice the "Remote site" section on the middle right of the FileZilla screen:

SFTP Tutorial

This area in FileZilla is the directory and file listing of the server. Navigate the server's file structure here, and click "/" to access the top of the folder structure. You should see the "/usr" and "/var" directories, and you can explore the filesystem to delete the files technical support recommended to create space!

Message Log

If you have a problem connecting to your server by FTP or SFTP, the open area below the Quickconnect bar is the Message Log. If you can copy and paste this text into a ticket, you'll help technical support troubleshoot your connection problems. Below is an example log of a successful FTP session:

Status: Connecting to server.example.com...
Response:   fzSftp started
Command:    open "root@server.example.com" 22
Command:    Trust new Hostkey: Once
Command:    Pass: **********
Status: Connected to server.example.com
Status: Retrieving directory listing...
Command:    pwd
Response:   Current directory is: "/root"
Command:    ls
Status: Listing directory /root
Status: Calculating timezone offset of server...
Command:    mtime ".lesshst"
Response:   1326387703
Status: Timezone offsets: Server: -21600 seconds. Local: -21600 seconds. Difference: 0 seconds.
Status: Directory listing successful

And here's an example of a failed connection:

Status: Resolving address of example.com
Status: Connecting to 192.0.43.10:21...
Error:  Connection timed out
Error:  Could not connect to server
Status: Waiting to retry...
Status: Resolving address of example.com
Status: Connecting to 192.0.43.10:21...
Error:  Connection attempt interrupted by user

If you have any questions, leave them in a comment below. Enjoy your new-found SFTP powers!

-Lyndell

March 7, 2011

March Madness - Customer Experience Style

If you are a SoftLayer customer you probably noticed a maintenance window early Sunday morning. If you aren't a SoftLayer customer, (you should be, and) you may have even noticed on quite a few social media outlets that we were trying to provide real-time updates about the maintenance progress, and our customers were doing so as well.

SoftLayer customers were given two internal tickets notifying them if they were to be affected, and when those tickets were created, the ticket system would have then sent an email to the admin user on that account. Additionally, our portal notification system was updated to show details about the window, and we created new threads in our customer forums to provide regular, centralized updates. We went as far as taking a few calls and meetings with customers to talk about their concerns with the maintenance timing and length because we know that any downtime is bad downtime in the world of hosting.

Saturday night, we had extra support on staff online, and our social media ninja was awake and letting the world know step by step what we were doing with real time status alerts. We wanted to be extremely transparent during the entire process. This was not a maintenance we could avoid, and we tried to roll as many different things that needed work into this maintenance without making a roll back impossible.

The maintenance itself went well, and as planned, most items that were taken down were back online well before the window ended. We ran into a few snags in bringing all of the CloudLayer CCIs back online, but even with those delays for a few customers, the work was completed by the time we committed to.

Now for the customer experience aspect. From reading various tweets from our customers, it seems like we should/could have done a few things even better: Been more proactive, sent standard email, attempted phone calls, etc.

While some of these options may be considered, not all are feasible. If you are one of the customers that tweeted, has blogged, is planning on tweeting, is planning on blogging or believes we're being anything less than genuine and transparent on our social media platforms, I want to hear from you.

Please comment on this blog, tweet me @skinman454, email me skinman@softlayer.com, call me at 214.442.0592, come by our office and visit.

Whatever it takes, just contact me. I can't put myself in your shoes and feel your pain on things like this unless we have a chance to talk about it. I look forward to our conversation.

-Skinman

October 14, 2010

Full Circle

One of the great things about working in the Hosting industry is knowing that lots of cool stuff is right at your fingertips. Our data centers host tens of thousands of servers, many with several sites, from the smallest mom and pop “about me” type site, to the large scale social networking sites. Another interesting facet of the job is curiosity. I find myself trying to figure out where some of my favorite sites are hosted.

When we get tickets from our customers oftentimes we’ll have to do extensive research to get to the bottom of an issue. As much as I’d like to claim to be a walking tech-dictionary, I’m a horrible liar. Google is a good friend to us, and points us to a wealth of resources. Around the internet there are plenty of white-papers, how-to’s, forums, and tech blogs. Where this gets interesting is when Google points us to a location hosted here at SoftLayer!

I look at this as an example of things going full circle. Customers helping us help customers. The beauty of the tech industry is there really are no trade secrets. The open-source community is great about assisting each other, and those who lean towards Microsoft have tons of tech forums, Technet and MS KB articles. Being able to host many of these types of sites is an honor to me, because we’re doing our part in assisting the IT Community as a whole.

-Matthew

April 2, 2009

We Need New Small Businesses

It is often said that small business is the backbone of our economy. According to the U.S. Small Business Administration, small business employs half of all private sector employees. Over the past decade, small business has produced between 60 and 80 percent of net new jobs. We need small businesses to prosper and lead us out of the economic mess in which we find ourselves.

I track growth in domain names every week. I think it indicates how quickly new small businesses are being formed. After all, what business can you think of today (large or small) that does not have some sort of web site? I can’t think of any. One of the things on any small business start up checklist today is the web site. Hence, most all of them register a domain name.

So what’s been happening with growth in domain names? Lately, it’s not too pretty.

Chart

With all the talk lately about stimulating the economy, one of the best ways to do this would be to encourage the formation of new businesses.

Some would argue that we need to fix the credit market mess to help banks be able to lend to small business startups. This couldn’t be further from the truth. How many small businesses do you know that started with a commercial loan from a bank? I cynically say that banks do not want to loan to businesses until the business can survive without need of a bank, and that was true even before the credit crisis. This was certainly true in SoftLayer’s case – when the founders were preparing for launch in late 2005, there wasn’t a bank anywhere that would touch the SoftLayer business plan. What I’m saying is that the credit crisis isn’t that much of a barrier to small business startups. Passionate entrepreneurs will find a way to get going.

But all the passion to start one’s own business doesn’t go very far in the face of the real barriers to starting a business. One of the real barriers that an entrepreneur must overcome is tax issues. Do they begin as a sole proprietor? A partnership? An LLC? An “S” Corp? Should they incorporate? All of them have different tax implications. All of them have to deal with either income taxes at the personal level or corporate level. Some have to deal with self-employment taxes. Others must deal with 941 taxes. Then there are state and local tax issues, such as the margin tax if you’re in Texas. And don’t forget sales taxes and property taxes either.

One of the strategies that allowed the Internet to cement itself in our society during the 1990’s was this: just let it develop without taxing it. Without that burden, the Internet took off like wildfire.

Ergo, if we’d like a bunch of new small businesses to get going, let’s ease up on the tax burden on new startups. This would cost the government hardly any money at all. Think about it – businesses that don’t yet exist do not pay any taxes. Workers that are not yet employed do not pay any taxes. Currently unemployed workers do not pay income taxes, except for a pittance on unemployment benefits. So allowing new businesses to form and employ workers and transact business “tax-free” for a defined start-up period would produce an EXPLOSION of small business startups.

How long should this tax free period be? Per the SBA, if a new business survives 4 years, they have a great shot at surviving long term. So why not give all new business startups a tax holiday for four years as they establish themselves? Can you imagine how big the tax base would grow as these healthy, strong 4-year- old businesses begin paying taxes?

It seems that the biggest issue facing our new President and his administration is how to pay for all the things they’d like to do. Let me suggest that expanding the tax base is the best way to grow government revenues, as opposed to increasing the rates on the current tax base. Allowing a flood of new businesses to take root and grow our tax base may be the best way to fund our growing public budgets.

Naturally, SoftLayer would be more than happy to assist these new businesses with our enterprise class data center outsourcing services so that the new businesses focus on their business plan – not their IT overhead.

Subscribe to help