Time to surf the Google Wave?

I just finished watching the 80 minute developer preview of Google Wave on YouTube and I have to say Google has managed to grab my interest in a hurry. The video was taken during a presentation at Google I/O, a developer conference for Google.

The concept behind Google Wave is certainly ambitious to say the least. If successful, Google Wave will essentially fade away the popularity of communicating via email, and replace it with Google's attempt at imagining what email would be like if it was invented today, rather than over 40 years ago (as explained in the video).

From http://wave.google.com/help/wave/about.html:

What is a wave?

A wave is equal parts conversation and document. People can communicate and work together with richly formatted text, photos, videos, maps, and more.
A wave is shared. Any participant can reply anywhere in the message, edit the content and add participants at any point in the process. Then playback lets anyone rewind the wave to see who said what and when.
A wave is live. With live transmission as you type, participants on a wave can have faster conversations, see edits and interact with extensions in real-time.

A screenshot of Google Wave in action, courtesy of Google

If you are interested enough in Google Wave, you may have already seen the developer preview video. Here I am going to say some of the key points about Google Wave as well as some of the things that impressed me, all details I have gathered from the video:

• Google Wave is a very extensible collaboration and communication tool used with a web browser. With a very modern drag and drop user interface you can instantly "drag" people into a conversation and communicate with them.
  
• Google Wave is real time, meaning you can literally watch you friends typing key for key in a conversation that you are a participant in. If you want a little more privacy you can opt to not have it show everything as you are typing. Part of the reason this is done is to maximize the amount of time that you are actually doing reading and writing rather than spending a lot of time waiting for a response.
  
• Google Wave has a playback feature to see the developments of a "wave" conversation. If you were to make a comment about something in the middle of the initial wave that was posted, the playback feature could illustrate when your comment was made in respect to all other comments and contributions to a "wave."
  
• Google Wave is being modest instead of trying to take over the web with its revolutionary concept. It is open source meaning anyone could come along and make their own version of it for implementation. With widespread adoption we could see the likes of Yahoo and Microsoft making their own versions. Along with this, Google Wave can be used on external servers outside of Google's.
• Google Wave can be expanded to do almost anything. As shown in the video one could create a "wave" to view "tweets" from their Twitter friends or create an RSVP wave to see which of their friends can attend an event. Even games of chess and sudoku can be played with friends using waves.
• An intelligent spellchecker is implemented in Google Wave that actually checks the context to suggest spelling fixes. As demonstrated in the video, if someone were to type "I love been soup," Google Wave would suggest changing "been" to "bean" and if the system is confident enough about a correction it will automatically make the correction for you.
  
• Google Wave can be embedded in third party websites seamlessly. The demo showed the usage of commenting on a blog using Google Wave embedded inside of the blog, then later showing the comment on Google Wave's official client.
• Unsurprisingly, there will be mobile versions of Google Wave for smart phones to use, such as for phones using Android and the iPhone.
  

For more information about Google Wave, you may want to look at the developer video, and checkout this blog entry posted on the Official Google Blog.

A look at my experience with SMF

The following is a significantly polished version of an article I wrote in April of 2008 that has never been posted here.

Many of my peers are well aware of the role I serve for a software organization in which I provide a significant amount of time volunteering for. Those who don't know me as well, probably aren't aware of my involvement with this software organization, which specializes in web development.

The role I perform involves a team leadership position for SMF. Simple Machines Forum (abbreviated as SMF) is a free open source message board software [see wikipedia definition]. The primary function I serve for SMF involves writing documentation and maintaining the SMF Online Manual, which is the primary repository for the official documentation of the software. Since 2006 I have been the coordinator of the documentation team of SMF, just one year after joining the team in July of 2005.

SMF is a free software, period.

The first bit of knowledge I would like to throw out there and emphasize is that SMF is completely free for anyone to use. Yes our organization has had some heat thrown at us by a small group of individuals that go around advocating an Open Source license called GPL, with an attitude very much akin to that those who do not use a GPL license yet still release software free of charge are acting in a bad way, with no questions asked. This is at least the impression I get. From what I understand, these people aren't necessarily so against commercial products, but they feel all software that does happen to be free as in 'free beer', should also be 'free' as in complete freedom. What this means in our context is that currently we do not allow others to modify our software and redistribute it under a different name ("fork" the software as it is frequently called) which is one of the key components of what the GPL license would allow. We actually do occasionally allow redistribution, but only in special cases in which permission is asked and then granted. We have had legitimate reasons for not allowing others to fork our software. SMF traces its roots back to a predecessor message board software called YaBB SE, which was released under a GPL license. Sadly YaBB SE had a fork, and while I know that I wasn't around back during those days, I have heard about how the fork damaged the integrity and reputation of the software. Granted the SMF software is much more mature than YaBB SE happened to be back in the day. If SMF was "forked" it would probably be left standing strong, however we still have our reasons to be against going with a strict enforcement of using a GPL license. Reasons however in which I either lack the expertise to discuss, or are internal matters that I am not privy of mentioning.

Now let me be clear that I am by no means against the GPL. I think for instance GPL is really great for Linux. I think the one of the major problems however is that GPL just was not designed for web development. I will save the argument for another day, but essentially the GPL was not made with the idea of web software in mind. I am not an expert on this subject, but I have had colleagues who are very experienced in programming and licensing who have given good reasons as to why the GPL does not make the perfect fit when regarding licensing web projects.

Why do I spend time on SMF and how did I discover it?
First off, SMF was not the first message board I used. phpBB was, and at the time I didn't mind it. But the version available at the time, version 2, by my judgment, was quickly becoming obsolete as it wasn't quick enough to release a significant upgrade to remain competitive. However I do have a a lot of respect for the people behind the phpBB project, and just like SMF, phpBB is also free (and 'GPL free' for that matter). However phpBB just did not offer a lot of the features I wanted for my own message board that other free competitors had to offer. I eventually found my way to Invision Power Board, another quality forum package and was quite happy with it until the unfortunate change in direction was made for the project when IPB became a software that cost money to use.

From there, I eventual crossed paths with SMF, and almost instantly fell in love with it. What was it that I liked about SMF when I first discovered it? In general I was impressed with all the configurable administrative settings that were available and the good looking, friendly user interface.

I think what ultimately inspired me so much to contribute to SMF was the friendly user community behind SMF. I was essentially a young and inexperienced member when I first signed up to the community as a member, but the community never made me feel like I knew nothing and was worthless. Instead, I only became more and more encouraged and confident in myself, quickly trying out and learning new things on a daily basis. I recall being impressed with how many ordinary users would go around helping other SMF users, providing support for the usage, as well as installation of the software. I realized then that I found something that made me feel good. Sure there was the sentimental feeling from giving back to something that I believed in, but I think more so than anything else, I found a place where I could help others out and feel welcomed by all.

What do I do with SMF? Do I just write documentation?
Documentation is actually only one of the activities I am involved with. The list of everything that I do is an extensive one, but here I will try to keep it simple, highlighting what I do the most.

Documentation is my main duty over at SMF. I write new documents and edit existing ones. As mentioned before, I am responsible for maintaining the Online Manual, which is powered by the SMF software. Maintenance includes the responsibility of upgrading it when new versions of SMF are released. I also do some programming so that we have special features needed for handling the documentation, since SMF was not designed as a wiki software.

But if documentation isn't the only thing I do, then what else do I do or have I done in the past?

Well, for starters, I have written a few modification packages. For those of you who may not know, modifications (often abbreviated as 'mods') generally are third party packages of code that either directly modify code in the software (in SMF's case), or at least provide instructions for someone to manually modify the software by themselves. Modifications that I have written provide additional functionality that SMF does not have in its default download package. One modification I wrote has actually been made into a default feature in SMF 2.0.

A long time ago I even released a few themes, but my theme designing skills are not the best and consequently the themes I released faded to a point where they stopped being updated for more recent versions of SMF.

A huge part of what I do with SMF when I have the time is provide support for those who have installed the SMF software and need assistance with using it. I often like to focus in on areas where there is high demand for a certain type of support, but low supply of those able to help. Such examples often include people asking for minor tweaks that require editing SMF's code to achieve a certain functionality or feature. Many users are not that knowledgeable in regards to coding, and coding related questions usually take much longer to answer than other questions, so I try to step in and help with such questions whenever I can.

Another huge part of my involvement with SMF involves providing feedback to the team behind SMF, offering suggestions and advice on the ideas of others as well as coming up with my own ideas. I also beta test the software and report bugs that I find in SMF so that they can be fixed. There have been some events and concepts that would not have taken place if I hadn't been the one to initially come up with a certain idea. I take pride in helping SMF move forward and helping to make the community into more of a friendly environment. I have often suggested ways of getting the people in the community more involved, by employing the usage of contests and other means. It is my belief that maintaining a friendly community that is able to connect with the team behind SMF and feel welcomed is virtually the most vital thing for SMF to remain a strong message board software.

Paying Due Respect in a Professional Setting

The following is something I wrote for a team of people I work for in a web software project. You could probably figure out what project with minimal detective work. This isn't anything like the first two things I wrote, however it's been awhile since I've posted anything on here, so I figure a less formal writeup wouldn't kill me.

Basically what I say here I feel can apply to almost any professional environment where there is a lot of online discussion where you do a lot of typing (such as on a message board).

Hello peers, I've noticed little things that get me a little discouraged with the occasional lack of manners and respect going around on the team boards.

First of all, if you want to be taken seriously, please type in comprehensible English. If you do not know English very well, that is understandable, but do try your best! I have seen some posts with so many typos that I literally feel like discrediting immediately anything said in the post because of the lack of effort that the poster put into their post. These are posts that come from people who I know can write in English with no problem. Frankly I find it rude to make a post with very poor grammar and several typos. Please read through what you are typing, I have seen some posts where I am sure that the poster didn't bother to even really look at the screen while they typed and never checked their post once.

Now I am a bit overly paranoid with my posts, often reading them 3 to 4 times over, but I don't expect people to be that careful.

The other thing is I expect everyone here to have the utmost regard for being completely respectful, even to a point where it seems almost comical. Truth is people can get sensitive over anything, and to avoid these problems it really does help to plaster your posts with phrases such as "With all due respect" ... "I appreciate your suggestions, however."

For a good example, think of a time where you may have said "There's no point in that." We all have done it. However as less harmful as you meant for that post to be, what you really are implying is that the person who made a suggestion made a very pointless and stupid suggestion. Now, you may actually think this, but you never want to imply such a thing. Hopefully the person with the suggestion is reasonable enough not to read too far into it, however, it could help to cover all grounds such as "I respect your opinion, and see why you could think that way, however I think your suggestion has two problems that you may have not thought about..."

Call me crazy but I would feel ten times better seeing something like this:

I respect your opinion about why we should add the "Awesome" mod to the default package, and understand your reasoning, but I think your suggestion has two issues..."

Over this:

"There is no point in adding the mod to the default install."

See my point? Please be extra careful to word your posts to be as respectful as feasibly possible as well as making an effort in writing in complete English sentences with proper grammar. Honestly it is a lot harder to read your post and understand it when it is filled with typos and lack of capital letters and punctuation, and I will just have to not take the post as serious as the ones where people took the time and effort to write properly and read through what they wrote at least once to make sure it read properly. Would you type like that in a resume? I would hope not, and the team boards here are a professional enough setting to not act like a 10 year old.

And a good example of me trying out the respect card when someone replied to what I wrote and claimed I was taking things too far with the grammar expectations:

Can you explain what you mean a little bit more? By no means am I trying to say it is a crime to have the occasional typos in a post, no one is perfect after all. What I mean is more when the quality of a post seems obsessively sub-standard for what I know the poster is capable of.

Also I respectfully challenge your claim that I am taking things too far with the basis that I am not mandating anything. I question your reasoning as what I state in my post are merely suggestions, not mandated rules that everyone has to follow. If I personally decide that I will not take posts as seriously when I have to make a huge effort to comprehend them, that is my decision. Quality pays off, trust me on this. There is also a difference between a post with a few small typos and a post with no structure or flow to it. By flow, I mean the ability to follow the train of thought.

I could have lashed out at the individual and called him "lazy" and "irresponsible," but from experience I know no good can come out of trying to outwit someone by throwing them insults. Instead I tried to reason enough with him while still remaining firm to my own opinions. There is a point where you do not wish to disqualify your views just to keep someone happy, but when doing so, I would suggest trying to as respectful as possible.

Starting and Maintaining a Website

Undoubtedly you've come across it before, a "dead" website. Not the one which leads to a 404 Not Found page but one that has been abandoned by its creator, long left to rut and be forgotten. Be it a blog, an informative website, some kind of fan appreciation website, or something else, many webmasters rush to develop on a particular concept that lacks depth and any sense of a significant purpose, to publish a website that is all but destined to fail.

For those of you who have an ambition to create a website or who have a new website out, I have written some pointers pertaining to what I believe are crucial points in producing and maintaining a website, particularly one that thrives itself behind a community of people.

Establishing a Base: Drawing out and delivering on an effective concept

So frequently forgotten, but essential in website development involves the ability to create something fresh and original. Webmasters frequently opt to create generic duplications of websites that are already out there on the world wide web. It can be a good thing to have more than one option to quench your thirst in a certain topic of interest; if sports is your ball game, you may dislike the popular sports website provided by ESPN, and really appreciate the fact that there is a sports website that caters better to your own personal taste. However, be careful. If you think you can create a website with the same topic of 1000s of other existing websites with the simple reason that you think you can do a better job, watch out. Think about whether you are being naive and unrealistic. If you really think you can do a better job than the existing competition, think long and hard about how you can bring improvements to the table. Having a fresh perspective to offer on a common topic can help you tremendously in garnering enough interest in your take on the topic.

You may not like spending time with planning the groundwork for your website, but in the end it could save you countless time and could ultimately make the difference between you creating a successfully developed website and one that you would eventually abandon.

Planning is crucial. Think about what you want to do and how you will be able to do it. Be realistic, and don't lie to yourself about what you can and cannot do. If you think you will be able to create a website from scratch with very minimal knowledge of web programming, you may come to a disappointing conclusion. There are plenty of available website creators, Content Management Systems (CMS for short) and forum software applications (often free!) that you can use at your disposal if you are not knowledgeable or don't have enough time to make your own system from scratch. And if you don't like the idea of using something others created, there is always the possibility of adapting to something custom in the future.

In planning, be sure to lay out every minute detail. It is better to do more planning than what is needed than to not do enough. Hopefully someday I will get around in making my own version of a fairly typical checklist for preparing a website.

Providing Content: Communicating ideas by producing media to entertain and inform

Unless your website is virtually exclusively about communication and interaction, you will likely find that a website that people come back to is going to be a website that frequently provides fresh and interesting quality content. Even a community oriented website should still focus on getting the users to contribute their own content in some form, such as by hosting their blogs. In the end it is usually very important to provide content for your website. This is where it is advantageous to have a website that covers a topic that you are very knowledgeable about. With vast knowledge on a topic, you will find it a lot easier to write and provide content frequently. Do not rely completely on others to provide all of the content. While it is likely going to be the case that you will find others to help you in providing content, this is likely not going to happen right away. You may have to be exclusively involved in producing content until your website reaches a larger audience. Chances are when people see you working hard at writing insightful content, these people will likely feel more willing to also come in and offer their own share of knowledge.

Keep in mind in that videos, audio and illustrations are becoming increasingly popular and effective alternative tools for providing content over just providing everyday writing. Spark up your visitors by providing interesting and relevant media whenever it is possible.

Time and Commitment: Showing dedication and being responsible

Another factor to consider when making a website regards the time factor. If scarce on time, you may want to rethink the idea of starting a new website. If you are determined to do it with little time, be sure to state clearly to your users what they should realistically expect from you. This will help prevent disappointing your viewers. If you can manage to publish a new article once every week on the same day, then you have the advantage of the users coming back each week expecting to at least find something new on that day even if that is all you can provide with your limited time.

Realize that our lives take completely unexpected turns that can potentially impact your ability to always be available for your site, so try to prepare for these instances. This is one of the times when having a staff of people helping you out will help out the most. If you won't be around and you know about your absence in advance and have formed a close relationship with many of your website visitors, be sure to give advance notice of your absence.

Marketing: Spreading the word and staying true to yourself

Marketing your website is tricky and I cannot speak from experience on exactly what you should do, however I will state that while it is desirable to have a "popular" website, try not to be too overwhelmed by the concept of popularity. Having your website viewed by many can require patience and will almost always never happen in a very short amount of time. Whatever you do, try to avoid "selling out." Always remain loyal to your core user base. The people who are fans of your website before it hits mainstream popularity are the people you should care about. If you find yourself evolving your website just to cater to more people, your site may end up getting more generic and you may end of becoming less and less interested and less passionate about it yourself.

Whatever you do, try to be careful and find the right balance between remaining loyal to your most loyal and dedicated users, as well as ways to open up and broaden the appeal of your website to a wider audience. How to do this is up to you and will depend on different situations. Seek the feedback of others, including the fans and toughest critics of your website. You might find that the passionate users of your website may be more than willing to help spread the word out. Even websites can rise in popularity through grassroots campaigning.

Think of third party outlets that could help spread the word out about yourself. Perhaps you could post videos to YouTube that you make that relate to something about your website. Stay current with the trends and crazes that erupt on the internet. For instance right now could prove to be a good time to have a Twitter account for your website where you can post useful information on.

Creating a Community: Bringing the concept behind a community to the world wide web

The idea behind a community oriented website is becoming more and more popular as time moves on. Social networking sites such as Facebook and Myspace focus on bringing people together in an online version of a community. For some this feels entirely natural but for others the idea involving such heavy online interaction is confusing. I believe it is a great idea to carry a community feeling to your website but at the same time try your best to make everyone feel welcome, including those who do not understand the point behind the whole social networking sensation on the internet. For instance, I believe it is a big mistake to require users to register to perform basic tasks on your website.

A great way to provide a community feeling to your website is to include a message board with your website. A message board is a place where people can post their thoughts and opinions in a given context of discussion. You may be familiar with message boards provided on many Facebook fan pages, however the type of message board you can include can be potentially a lot more complete and offer a lot more control than what Facebook provides. Some free message board options include SMF, phpBB, and MyBB. I of course hold a personal bias to SMF because I am a team member, but if you are interested in including a message board, I suggest you try out some different ones to find the one that best meet your tastes

Ability to Adapt: Making adjustments in times of rapidly changing preferences

Sometimes it takes a little bit of evolution to survive in the world of the internet. You may be familiar with the whole "Web 2.0" sensation going around the the internet right now. If not, you can always search Google to find out about it. It is debatable whether the whole trend of flashy, big buttons and curvy feeling provided by Web 2.0 is just a fade or something necessary to appeal to the masses. However there is always going to be the possibility that as time goes on, people are going to expect certain things out of your website. Don't be surprised that if your website lasts 5 years or maybe even less, the whole design of it which may seem perfectly fine and modern to you when you started, will end up seeming highly dated and dull after awhile.

The process of site redesigns are a very common practice on the internet. Some choose to make a bigger deal out of website updates than others do. Think along the lines of "My Website: Version 2.0!" for people who like to update in a dramatic fashion. Whether you want to casually release minor updates throughout time, or come out strong with flashy and big changes is up to you. But be sure to listen to user feedback. Try to avoid changing for the sake of change, but rather change and adapt to cater to the evolving internet standards and expectations. Don't run the risk of leaving your users surprised and unhappy about changes you make. Try to involve both your heavy users and casual newcomers to your site in the process of updating your sites functionality and appearance.

The Hard Facts: Maintaining a website is not an easy task

The truth is maintaining a website can be hard thing to do. If you are paying for hosting, you may have to pay more and more as your site becomes more popular. If your site becomes a huge deal, you may even find yourself in the position of having to pay for your own servers to use as well as paying for a team of employees to keep your site running. The bigger of a deal your site becomes, the more crucial and valuable it will prove to be for you to invest your resources into it. Certainly not every huge website was started by a major corporation, sometimes even the really popular ones started as a hobby project by a high school or college students. While popularity in such vast proportions won't come to most, do prepare yourself for the future.

Make long and short term goals of where you want to see your site progress. No site is perfect, and each and every site out there could use improvements. Always seek feedback from your visitors and your staff. It is unwise to assume that you always know best.

Staying Secure: The Three U's: Update! Update! Update!

Any software that you use can be hacked. Security holes are found by hackers who show no mercy when it comes to respecting your website. This is why it is important to always use the most up to date software. When an update is released for any software that you use, be sure to update your install of that software as soon as you possibly can. Be sure to check back for security updates for each and every software you use. This can be done by visiting each website that provides the software you use, subscribing to a mailing list that notifies you of updates as well as subscribing to RSS feeds when available where news updates are posted for the software.

And Good Luck!

Whether you are looking to start something casual or hope to someday become an internet entrepreneur, I wish all of those who are thinking of building a website or web service the best of luck. What I provided is just some advice I have to offer about what to think about when in the process of building and maintaining a website. But do listen to the valuable suggestions provided by others across the internet. What I had to say was a fairly general outline which did not particularly offer detailed feedback on what exactly you should do.

As always questions and comments relating to this article can be asked in a comment left here or by sending an email to my email address at thorsen.j@gmail.com.

Special thanks goes to Jade Elizabeth a friend and colleague of mine, for her help in proofreading this piece before it was published.

Uncovering Documentation

Do you recall the last time you opened the instruction manual to something, anything, using it for its one and only purpose: assisting you through a process? Maybe it depends on what type of person you are. I for one, am somebody who prefers to master the art of trial and error, making guesses, sometimes completely random and desperate to try to get something to work. But sometimes guessing can only get a person so far, sometimes one must resort to an instruction manual in order to properly troubleshoot or assemble an item that he or she has purchased. Sometimes instruction manuals feel natural and sufficient; think Legos. While other times you feel like an idiot, shuffling through the pages to find out why your product is not turning on, doubting to find your answer, but doing it out of sheer desperation.

I am going to admit that documentation, as I like to call it; the process of writing and rendering documents for instruction manuals, is a hit or miss with people. Some live by it, choosing to lead their life by following examples word for word, while others prefer to dodge reading documentation at all costs. Being one who lives with the philosophy of trial and error myself, it may seem like an unnatural fit for me to be directly involved with documentation on a daily basis. But I am. In 2005 I found myself involved with writing documentation in a official team membership capacity for the Simple Machines Forum software, SMF for short. As sudden as it seemed for me to be involved with the documentation process, things didn't slow down from there. Just under a year after joining the team behind Simple Machines, I was promoted to become the coordinator behind the entire documentation for the software when the previous coordinator was promoted to project management.

What I am going to describe here is just some of the nature of what it is like to "craft" documentation, as I will call it, a form of art so to speak. The entire process behind documentation if done properly can take wit, ingenuity and patience to get done right. Indeed the process behind preparing an instruction manual for any type of product may actually require trial and error to achieve even mediocre results. For instance, an idea for improving the documentation for a product may end up in the gutter, ending up as an ineffective way of communicating instructions. Sometimes it takes a test audience to work out what works well in guiding people through a process and what proves to be poor at conveying the required assistance.

The following is an actual statement I released to the documentation team of SMF in November of 2008, letting them know what I believe is crucial for documentation for the SMF project. What I believe is necessary for the documentation for SMF also applies to the documentation for just about anything:

• Documentation is the key to support; support is the key to maintaining a userbase. Documentation thus is the most critical point in holding a solid suppertbase, and by association is the most important thing in maintaining users.

• Users want clear and to the point documentation. They do not have the time to sit through massive technical documents and dig their way through the irrelevant parts to get at what they want; documents thus should be what the users want: clear and to the point. Documents should put emphasis on the most relevant, and separate the advance technical information from the basic crucial information.

• Documentation should hold to a professional standard of expectation. All officially published documentation should hold no grammatical errors and should be structured in an elegant and logical way; documentation should always make sense and never be unclear, documentation should be of excellent quality.

• The writers of documentation should acknowledge the various ranges of user expertise. Documentation should be available in a way that does not alienate and confuse the most primitive and basic computer user but also to not bore an advance user.

• Documentation should hold to a standard in layout and style. Documentation should always be consistent from one place to another.

• Documentation should revolve around user feedback. The best people to tell us what documentation should be provided and how it should be provided is by the users of the software. The Documentation Team should always try to seek user feedback to know where progress can be made.

The most crucial points I constructed about documentation is that documentation should always put the user in mind. An effective delivery of documentation is only effective because the people writing the documentation sought the feedback of actual people using the product that they are documenting. It is very hard to anticipate what users of a product will understand and what ideas they won't be able to grasp.

Another major point brought up above is the quality of the documentation. I have skimmed through instruction manuals with regrettable typos. When the quality of documentation is awful, one may assume that the person hired to write the documentation isn't fluent in the language they are writing with, and were mainly responsible for some other task in assembling the product but to cut costs they also were assigned the task of writing the instruction manual! This shows that for one, the company did not value the importance of putting out documentation, and only did it because it can be an expected norm in the consumer world. But to the reader, poorly written documentation can prove to be unwholesome (pitiful and messy). This would likely result in not effectively allowing the consumer to understand the instructions.

It is also my belief that when writing documentation, the writers should try their best to separate the more advanced material that not everyone needs from the basic fundamentals. Sure it is sometimes only the advanced topics that one may need to look up for a relatively basic product, but to an average person, reading through a clash of both basic and advanced concepts could prove to be overwhelming. Frequently in instruction manuals this objective is achieved by having an advanced concepts chapter somewhere in the book or to clearly box and label material that is only for the "advance user."

The Typical Documentation Process For Me

When starting a brand new document for SMF I need to perform a variety of tasks to make sure I am going about my work properly. First off, I look around to see if similar material was already covered elsewhere. It can prove demoralizing when one writes something only to find out someone else already started to work on the same thing. After I am absolutely certain that the topic I am to write about has not already been partly or completely covered, I communicate with the members of the documentation team so that they are aware of what I am working on. This is useful to prevent duplicate work.

Next, I check for standards. I look around for documents published in the same section as where the document in progress is going to be published, and examine what type of style and formatting they have so that I can closely match the same type of standards to the document I am about to write. A solid consistency in writing documentation is very important. It is not very appealing to find documents that are written completely differently from one page to the other. When reading through an instruction manual, it is ideal to read through it with the feeling that one person could have written it all, even though in reality a group of very diverse people may have worked together on it.

After checking for standards I get to writing, analyzing the SMF software carefully to document whatever aspect I set out to write about. During writing I check for user feedback to see if people have left advice about what type of information I should cover. I also may communicate with the other members of the SMF documentation team asking for advice and feedback on what to write about or how to phrase a certain sentence.

In the end, the entire process of documentation is like a form of writing. Technical writing to be precise. The kind I am experienced with is a form of group peer review in which we all examine "holes," as in what type of topics are missing documentation, and do our best to fill said holes in with information carefully "crafted" with our keyboards, one tap at a time. We rely heavily on the users of our software to assist in telling us what parts of our online instruction manual [1] is hard to understand, and what topics we are missing documentation on.

I greatly enjoy writing documentation and hope to continue a career that can allow me to pay due respect to those who find themselves writing documentation on a daily basis even if I may not pursue a career that directly involves documentation.

References

Here is the Online instruction manual [1] that SMF provides for its users that I work on along with three other people who are on the documentation team of SMF.

Here is a list of the current Documentation Team behind SMF.

Any questions or comments you are welcome to email me at thorsen.j@gmail.com. I will be happy to try to answer any questions that I can that pertain to documentation.