A method for writing content

 After some reading I started to realise that I need to have a method for writing articles and creating content, just like producing software or baking a cake. I’d seen it written that content is like a conversation with the reader, so where should I start? I should begin with a topic. Write something in the subject or headline box. Make it a bit questiony. Or answery. Or something.

Right, now I know what I’m writing. What next? Doing some research might help, with a bit of Googling, Binging, and Yahooing. I recommend that when I use my Mac, I should use Devon Agent for it’s natty search aggregation and ranking. I can put a search term in and it goes and finds information from all over the web. But sometimes I use a PC. Ok, it’s been a while since I checked it out, but last time I looked there was a tool called Copernicus that was rather useful and did something similar.

As for writing tools, I quite like MacJournal, and MarsEdit is good too. On Windows, I like Live Writer. I could use a web browser to want to blog. Outlook, Mail.app, or Thunderbird email work quite well. Anything with an autosave. On Linux I have no idea what you could use. (please send suggestions for tools in the form of links to Flickr, photos of names of applications written on napkins. best one gets a gold star).

Well of course I have a writing tool. Pen and paper. In fact it’s a rather lovely imitation Moleskine type notebook with coloured pages and a classic fountain pen (I ditched the pen quickly in favour of something less leaky...blotchy white work shirts isn't a good look). I prefer this to the real thing at the moment for three reasons. Firstly, it’s slightly cheaper. Secondly the coloured pages are ace for sectioning it up. Finally, it’s about twice as thick as a Moleskine so it’ll last longer and so it’ll get replaced less frequently. I think I got it from Rymans on the Strand but I'm not sure. Anyhow, now that I have a title and done some research, what now? First up, put down the traditional equipment, it’s not going to work for what I have in mind. Consider the English Language lessons you had in school, particularly the bit about stories having a start, middle, and end.

But I’m not writing fiction! It doesn’t matter. Everything is fiction unless it’s supported by evidence, and even then it’s open to interpretation and errors of omission. What is true to me might not be true at all. What matters is that you are writing and not just presenting tables of data, so you need to use structure and narrative, therefore it’s fiction. But rather than go down the rather boring start-middle-end style which will lead you into having something like “put water in kettle, boil kettle, pour into mug with teabag, remove bag, add milk; that’s how you make tea” where you have to read to the end to find out what it was all about, you should do it backwards. This also implies that it's a magical kettle that heats the water itself... it's too easy to miss details and forget vital steps.

If I try a end-middle-start approach, I’ll get a “Here’s how you make a perfect cup of tea...” type of linear guide which is great if that’s what I intended, but once a reader skips to the end I have lost them. I doubt that they will ever go back to the start unless they are desperate for a brew. Besides, what is a perfect cup of tea? Perfect by what standard? Anyhow, I’ll have saved them the embarrassment of reading something to the end then realising it wasn’t what they wanted. We all know everyone reads everything to the end.

Ok, I’ve done a whole bunch of words and arranged them into sentences, put the sentences into groups called paragraphs and shuffled these into reverse order. So that’s why a notebook isn’t going to work. Ok, it could if I’d used some scissors. Now all that is left is to merge the one or two sentence paragraphs into the larger blocks, read and edit it make it all make sense again, fix the spelling and grammar and fire in some hyperlinks preferably with a shotgun. Links are awesome. I can add embellishments too which may or may not be true just to make it a bit more excited, never mind the supporting evidence.

Optionally add a nice image from Flickr, and don’t forget to attribute it. Of course this will make for a fairly gibberish article. There are much better ways of writing for the web, and if this article inspired you then you should continue and read more on the subject.

And on that note, I need to have the start of the article here - the TL;DR version. So, this is an article about a method of writing. Would you like to know how to write an article? Read this one to find out.

CQ5 best practices for component development

Following on from my advice for best practices for developing with Adobe Day CQ5, here are some suggestions centred around component development - you should tailor these to fit your needs. They should help if you are unsure where to start. There's lots of technical documentation on the product itself and the core open source frameworks; elements of these are useful for developers, but there's scant information on methodologies or strategies you can apply when starting out. Some of this may also apply to other systems albeit with different no-go areas and so on.

Avoid copying components

Firstly, avoid modifying anything under /libs. Also avoid copying anything from /libs to /apps. There are a few reasons for this:

1. If you upgrade you will hate yourself for doing this. Your boss and co-workers may hate you too.
2. Changing /libs implies that you are either not going to version control it, or that you are going to. Either way leads to madness, unless you like code to go missing and have servers which behave differently or if you want to add half of the core product to subversion. 

Copies to /apps should be VERY limited for a few significant reasons:

1. when you upgrade, you need to upgrade this code too if you want it to work or at the very minimum have the new features. 
2. there's no way of quickly identifying these 'overlays'.
3. if you overlay something that is key, things go sour very quickly post-upgrade.
4. having two components with the same name in the same group breaks design mode in CQ5.4 - for me at least

Override the bare minimum

All components for paragraph systems should have a 'sling:superResourceType ' of 'foundation/components/parbase'. Development of derived components should be done using 'sling:superResourceType' where possible. An example might be creating a paragraph system that behaves differently. Say you want to make one where component display is inverted, so that new components are inserted at the top - this is a parsys with a 'sling:superResourceType' of 'foundation/components/parsys' and a customised script. There's no need to copy the whole component.

Component Organisation

A recommended structure for component definition is

 /apps/<site-id>/components/page/<component>
/apps/<site-id>/components/content/<component>
/apps/<site-id>/src
/apps/<site-id>/install 
/apps/<site-id>/widgets
/apps/<site-id>/nodetypes
/apps/<site-id>/templates/<template>

Of course, all of these are optional. Page rendering components explicitly defined in the templates are split from paragraph and non-whole-page components such as navigational bars. This is purely for the benefit of developers; it means it's possible to see at a glance if the component is used to render a whole page or if it might appear as part of a page - a useful distinction. It has another benefit, for example it allows a 'sitemap' paragraph component which lists in HTML format to exist as well as a machine-readable sitemap.xml page type for SEO - two very different things with the same name.

Composition of Page Types 

A process of decomposition into sub-scripts is applied to the page rendering code to create a solid foundation which will allow extension of the basic type into more specifc page components:

/apps/<site-id>/components/page/base
/apps/<site-id>/components/page/base/base.jsp
/apps/<site-id>/components/page/base/head.jsp
/apps/<site-id>/components/page/base/body.jsp
/apps/<site-id>/components/page/base/header.jsp
/apps/<site-id>/components/page/base/content.jsp
/apps/<site-id>/components/page/base/footer.jsp

The base component extends the foundation page, with a 'sling:superResourceType ' of 'foundation/components/page'. 'base.jsp' basically sets the page doctype, outputs the <html> tags and includes head and body. Subsequenty, body.jsp includes header.jsp, content.jsp, and footer.jsp.

Extensible Page Components

This is the minimum for a base component which is extensible. We can easily make this better by adding other override-able scripts, such as adding an analytics.jsp or a meta.jsp. From this start point we can create a new component with a 'sling:superResourceType ' of '<site-id>/components/page/base', and the only thing we need to create is content.jsp

/apps/<site-id>/components/page/twocolumn/content.jsp
/apps/<site-id>/components/page/twocolumn/left.jsp
/apps/<site-id>/components/page/twocolumn/right.jsp

This obviously a two column layout. In order to separate content from code we should create a new component with a 'sling:superResourceType ' of '<site-id>/components/page/twocolumn', which now needs no scripts at all. It will derive all configuration and code from the super type, leaving us free to change the super type if we want a different representation (so long as the paragraph systems have the same names). We can also override the two column layout if we so chose, by creating a script which does something then including the overridden script. For example, we could create a  /apps/<site-id>/components/page/contentpage/right.jsp script which displays a title component then includes the  /apps/<site-id>/components/page/twocolumn/right.jsp  script. This gives a great level of flexibility.

Content has a type

Remember that when content is being created, the component path is 'stamped' into the content so that Sling knows what script to use to render it. Always plan components so that an appropriate resource type is associated with the content. In our page example, it is much better that it is a 'content page' than a 'two column page' or even a 'base page' as the intent is that is it content. The fact that it displays in two columns is incidental, especially if in six months time a third column is added. It's much more future proof to use a layer of inheritance, but only if it doesn't add unnecessary complexity.

Favour composition over inheritance

Components is CQ5 should also favour composition over inheritance. If you want a list-image component for example, don't take a list component, copy it, and hack it to have an image. A reasonable approach is to create a new component and add the necessary components to it. When you upgrade CQ to a new version, you'll have no changes to make - it'll automatically use the new version. If you did it by creating a new component by forking code, you could find it difficult to get it working if there have been major changes to the original component.

I hope this guide has been useful. It's based on real world development practices and is the basis of any recommendation I would give at this time. 

Day CQ5 Development Best Practices

Here's a quick reference list on some best practices for developing with Apache Sling and Adobe Day CQ5. Whether you view these as helpful hints, golden rules, or as definitive best practice guidelines, these should be followed during development and will help you to achieve a professional result with CQ5.

1. Avoid using loginAdministrative. Do you really need to run some code as superuser or is it more appropriate to use the contextual user? Remember that 'admin' can do anything and see everything, so you lose any security control over the situation. You also lose any audit of changes, as they will be logged as 'admin'. In general, if you create a repository session, you are responsible for closing that session. If you didn't create it you can assume that it will be closed later by the framework.
2. If using login or loginAdministrative, use logout. You need to remember to end any sessions created with 'loginAdministrative', otherwise you have a session leak and will run out of resources.
3. If not using loginAdministrative, don't logout. You shouldn't close sessions which you haven't explicitly created. Their lifecycle is managed by Sling.
4. Every call to getService should have an ungetService call. Each get call increments a counter and if we don't decrement the reference count it will not be able to release the service, potentially wasting resources.
5. If you are implementing servlets, be careful with implementing OptingServlet & Filter interfaces - they can break the POST requests needed by CRXDE.  
6. Break down logic into services and move as much code out of the JSP as possible into OSGi bundles. It's much easier to test OSGi bundles and makes the JSPs far easier to read. It'll also allow you to reuse the services as development progresses.
7. Use resourceResolver.map on all links in javascript and linked resources such as images - the link rewriter only does .html links and skips script blocks. This is essential if you want to do any kind of remapping of content.

There are also some rules which affect the CQ5 author...

1. Don't set body css color attribute - it hides labels in the dialogues if you set it to white. You should have an id or a class on your body element in your page, or a div element to contain your content.
2. Avoid inline styles unless you don't want to be able to reuse components. All styles should be kept in external stylesheet files.
3. Be careful with float css, it upsets the ExtJS based author system. It can cause element to overlap. It can also make it hard to click on elements to edit them. You might need to add css clear styles to subsequent elements to make things work.
4. Exceptions behave differently in CQ5 author and CQ5 publish, so make sure to use try/catch, value checking, and good exception handling practices. Make all your components fail independently, and not fail the whole page.
5. It's possible to create components without editing them by dragging them from the sidekick to the page. This doesn't set any data so make sure your code assumes that null is a possible value.
6. Always add a css style sheet for the rich text editor which matches your site design; it will make it much easier for your authors.

And finally, CQ5 Dispatcher considerations...

1. Anything with a query string is never cached. Anything which isn't a GET request is never cached. Pages with authentication are not cached.
2. Headers sent by CQ5 are not sent if the page is retrieved from the dispatcher cache. Content expiry, caching rules, and so on should be managed by the dispatcher server. This includes cookies.
3. You can cache everything else if you set the right rules in the dispatcher.
4. If you want to prevent caching by the dispatcher you can set a special header 'dispatcher: nocache'.
5. If you have remapping rules in /etc/map you'll need to add rewriting to the dispatcher web server using mod_rewrite or URL rewriting in IIS
6. Once it's cached by dispatcher, it stays cached until the publisher makes an invalidation call. Don't cache content which can change without author intervention.

Hopefully these rules will help developers avoid simple mistakes when working with JCR repositories, Apache Sling, and Abode Day CQ5. They might also be useful if you are doing code reviews too, as they are simple things to look out for. Finally, if you consider these rules when designing your solution, you might just be able to make your caching just that little bit more efficient or avoid CSS that is problematic in the author environment. 

How to fix Rosetta Stone error 1142 on Windows 7

A lot of people have complained or asked online how to get rid of the Error 1142 message when using Rosetta Stone on Windows. When Rosetta is starting up, it will quit with this message. The help and answers to these questions are not very helpful, ranging from the advice given in the official help which is to check the clock settings and firewall permissions, through to reinstalling Adobe Air and even the whole of Rosetta.

I found that the 'RosettaStoneDaemon' Windows service had been disabled on my PC. To fix this, open up the control panel, and go to administrative tools. You should see 'services' - right click on this and run as administrator (if you just open it you might not be able to make changes). Find the 'RosettaStoneDaemon', open it and set startup type to 'Automatic (delayed start)'. You can either reboot or start the service yourself, then close all these windows and go and have some fun in Rosetta - it should work just fine now.

Disclaimer: these are internals of the operating system, and changing setting in here can enable or disable features. Be careful, and if you're not sure what you are doing go find someone who does. If you break your computer, it's your own fault. 

Russian with Rosetta Stone Totale 4

I’ve just started learning Russian using the Rosetta Stone Totale 4 software. I’ve got levels 1, 2 & 3. This is my first impressions of the programme.

Installation went smoothly. I had to install the base tool, which is on the first disk. It insisted on running upgrades to this from the internet. It also needed to update the Adobe Air software on my PC – I guess this is how they managed to make it work on both PC and Mac. Once it was ready, I could install the language levels. It has to put all the files in the same place, so I picked a drive with lots of space. If ever I add the next levels I’ll want to have enough room to install them. It’s easy, just follow the on screen instructions to add another level.

The licence key is hidden inside the box on the back of a plastic card in the front flap and has to have a silver security covering scratched off. Confusingly the software presented me with three boxes for codes but I only had one. It doesn’t allow cut and paste, so I typed it in and it magically filled the remaining two codes in for me.

I guess what most people reading this might be interested in is… is it any good? Well it seems to teach in a very different style to other methods I’ve seen. It’s not phrase based, so even though I’ve completed lesson one with scores over 80% (this takes about an hour) I don’t yet feel like I’ve learnt anything. I suspect that it’s like this because it’s introducing sounds and concepts into the language centres of my brain in a way that will promote long term learning as opposed to remembering phrases and regurgitating them parrot fashion. There are four lessons in the fist level, so logically I’m 25% through it. The first lesson is slightly shorter than the others, so it’s more like 20% progress. If I get to the end of the first level I will be very disappointed if I can’t say anything useful.

The speech recognition feature is pretty cool, especially with the included headset. I’ve already got a great headset, so I opted to use my Corsair HS-1 mostly because they have a mute button and volume control on the cord unlike the included set. The speech recognition is configurable, so it’s possible to turn up the accuracy and the difficulty. Mostly  the lessons seem to consist of a word being pronounced, then either you repeat it (and the computer accepts what you just said), or you click on the matching word. The writing part shows an onscreen keyboard and you have to fill in the blank. The grammar section is also a fill-in-the-blank game, but multiple choice.

I’ll probably know in a month or two if this is going to work for me, but I’ll probably have to supplement this with other learning activities.