I recently had a call with some people who are interested in contributing to the Real World Open Source and Real World Linux communities here one developerWorks! Yay! I would like to see a lot more input by people in these places. As a part of that conversation they requested me to outline my recommendations for people new to writing in this environment. I decided that this might be of interest to the general public, so I'm posting here rather than privately through email.
Writing in developerWorks is not like having your own Wordpress or other blog. You can do a good deal of customization to make it fit your own preferences, but you will need to fit into the overall developerWorks framework. This framework may change around you, so the general rule of thumb is "Keep It Super Simple". Your content is what is most important here, not any bells and whistles that you might add, so write things that do well with plain, clean HTML. I prefer to do my writing in an HTML editor, actually. I tend to use Kompozer, an open-source editor. Unfortunately, development on this project seems to have stalled out, but it's still my favorite editor. It produces clean HTML with no muss or fuss and allows me to easily put something together which I can just paste into place. You can use any editor that you choose which can save HTML. However, bear these things in mind:
- Don't use a lot of styles and parameters on the HTML. Sometimes you need to, but keep it to a minimum. This will make your article behave better when it's published.
- Be cautious about what comes out of a word processor. When I write something in LibreOffice and them paste it into the blog there is a lot of hidden style information that ends up in the HTML. This is ugly and bulky and will do weird things to your entries. Be prepared to clean up anything that you do.
- Including images is good, but you will be working with a simpler subset of formatting options. You will also need to upload your image to the developerWorks server or reference the link externally.
- Posting audio and video is good, but remember that this can sometimes be unpredictable. For example, when posting a YouTube video, you must use the old-school <object> code rather than a simpler <iframe>. Someday this may change, but for now it is necessary. Some embeds simply will not work.
The included HTML editor is decent, but a little thin for me. I have two browser plugins that I use to help me write entries that I have not pre-written in Kompozer.
Write Area - This plugin will give you a fuller editor that you can invoke in any text area with a right-click. It provides more formatting options for links and images. Unfortunately it does not include a spell checker, though. so be sure to double-check your work. I use this a lot! (I'm using it now). It's been a real help to get around any site that has a limited window in which to write. It's free for Firefox. I'm sure that people with other browser preference will find similar add-ons. I'm just telling you what I use.
Scribefire - This plugin provides more than just an editor. It is a blog management system, allowing you to work with various blogs on different sites. It will give me a list of the blogs that I use and let me edit or create a new entry for any of them. This can be handy, but it sometimes does some strange things with more advanced formatting. (Remember, I said to keep it simple?) Another feature is that it will allow me to simultaneously publish the same thing on multiple blogs at once. I did run into one issue, which I mentioned in a previous post. Do not use the '#' symbol in your article titles with Scribefire. This caused it to get lost when trying to agregate my existing entries. That was very frustrating for quite a while until I tracked down the issue.
There are other blogging tools which are compatible with developerWorks, but these are the ones that I generally use.
Any pictures that you want to use need to either live on the system or be linked with the URL. For some content, especially copywrited content, I just link to it. That saves some of the usage hassles and acts as an automatic credit to the owner. For example, Dilbert cartoons are a great thing to include from time to time and they have a simple method for linking to their content.
If you're going to do things like this, you should expect to have to tweak the HTML from time to time. Sometimes developerWorks seems to alter things that are not entered through the raw HTML view. (That's the <h> button in your toolbar if you are using the default blog editor.) HTML is nothing to be afraid of, and many of you are technical people anyway, so you should feel comfortable with it.
For some pictures, though, it's best to upload them. If you are using the default editor, uploading is automatic. You click the icon to insert a picture and it gives you a chance to upload your picture. I will often use this step just to get the picture up and then go into Write Area to manipulate it and make it look nice with the article.
You can also upload an image file directly. Select the Settings link, next to New Entry. On the Create & Edit tab you'll find File Uploads. You can manage everything here. Note that this interface acts much like old-school FTP, so you can't overwrite existing files.
If you need to change something you need to delete it and then upload the new one. That provides a window where the file may not exist, but it's pretty quick.
Copy the link for an existing file and you can use a conventional <img> tag to include it.
Bookmarking major linksI quickly got annoyed by some of the steps to getting to areas like file management. They are easy to find, but require a number of clicks to get there. This was easily remedied with a few book marks. I have bookmarks set up for my main blog and the entries page. These reside in a folder on my bookmark toolbar, so it's pretty easy to jump right to the spot I want. If I did more file management I'd probably set up a bookmark for it as well, but it's just as easy to go to the entries page and then click over to files. (Two quick clicks versus three slow ones.) It seems like such a silly thing, but it really helped me a lot.
Contributing to the Real World communities
That should get you started with basic blogging. If there are questions that I have raised rather than answered I'll be happy to address them. You can email me or comment here. I may make this a living document and update it rather than writing additional chapters. I've set up the Real World Open Source and Real World Linux communities so that any member can draft an article. Simply become a member and start one. When you submit it, I'll be notified and can release it. Feel free to use this to post a great topical discovery or idea without taking on the burden of maintaining your own blog. If you decide to start your own, let me know and I'll follow it.