RE: Small note on the Apache CS docs, advice on quick fixes

[Hugo Trippaers <HT...@schubergphilis.com>]

> From: Jessica Tomechak [mailto:Jessica.Tomechak@citrix.com] 
> Sent: Thursday, February 07, 2013 3:20 AM
> To: Hugo Trippaers
> Cc: Radhika Puthiyetath
> Subject: Small note on the Apache CS docs, advice on quick fixes
>
> Hi Hugo,
> I noticed a couple of doc changes you made lately and I'd like to offer some friendly advice.
>
> As I was browsing through the git logs today, I happened to see a commit message that made me want to click:
>
> "XML likes it when you close tags as well"
> d70327ae15ecbf92d8dd5e3ed5b1ee6fc4a8bdd9  
>
> The missing close para tag was not a simple oversight, but a clue to a larger issue. The whole second half of the paragraph had been deleted at some point, maybe during a merge conflict resolution. So when you see something like this, my advice is that it's worth asking "Why" before fixing.

You are absolutely right of course, I should have investigated further. However the underlying problem here was that a whole lot of changes were merged into the master branch on short notice. This resulted in a number of Jenkins jobs failing and I decided to "fix" the issues and get the builds going again as the sheer number of commits was too big to properly investigate. If I find that I need to do the same in the future, I will raise a ticket pointing to the commit so it can be followed up. 

>
> I also noticed you commented out a couple of bad hyperlinks <!--FIXME like this -->, rather than fixing them. I get that this quick-and-dirty approach could be necessary right before a > deadline. I would suggest that when you do this, it would be helpful to comment out the entire sentence, so the docs don't end up with text like "See  ."
>
> Also it would be helpful to file a bug about the broken links, with the Component field set to Doc, so someone else might fix it. Or maybe everyone but me is routinely grepping the repo > for the text FIXME? I don't know. The bugbase is where I look.

Sorry about that, I'm so used to eclipse that I forget that not everybody is using it. In my ide setup every line that contains FIXME is present in nice bright red colors at the top of my task list, so I regularly just include a dirty fix and make a mention of it with FIXME so I won't forget to deal with it later. Again raising a bug would have been more useful in retrospect :-)

>
> I hope this is helpful. Cc'ing another writer for her benefit. You can feel free to fwd to the list if you think that such specific advice would be helpful to others.
>
Certainly helpful, I think all of us need regular reminding that not everybody has the same way of working and that we need to make sure that information is properly shared. Will CC the list as reminders like this can't be repeat enough.

>
> Jessica T.
> CloudStack Tech Pubs