This is sort of nerdy and writerly, but this is supposedly a blog about technical writing--if there isn't a place for nerdy and writerly....
A few weeks ago there was an e-mail thread on the DocBook mailing list about the best practice for using the sect1, sect2, ..., sect5 tags. Someone suggested that nobody should use those elements and just use the infinitely nesting section element. They went as far as suggesting that the offending sectN elements be removed in the next rev of DocBook.
I agree with this sentiment. While I can see the basic desire to know if I'm writing a section or a sub-section, I rarely find it to be a need. My basic organizational style doesn't involve more than three levels of sections. It also, generally, ends up with a structure such that higher level sections are just containers for lower level sections. Therefore, it is rare that I ever find myself caring or wondering what section level I'm at. It is usually three or less and if I'm filling it with a lot of content it is the deepest level I'm going to hit for the topic at hand.
Even when I do find myself wishing the schema would tell me how deep I've gone or enforcing depth limits, the added flexibility of nested sections overrides the wish. The sectN elements make reusability tough. A sect3 must always be placed inside a sect2, but a section can be a sect3 or a sect2. I have seen several cases where a section was a top level in one guide and a nested section in another.
There were several people on the mailing list who did not agree with the idea of doing away with the sectN elements. One claimed that it was imperative to enforce section levels. Another just said that you can feel free to remove any elements you want, but it wouldn't be DocBook anymore. I can see that for some writers, or writing groups, it might be important to enforce section levels. However, there are ways of enforcing style guidelines than encoding them into a schema. We do it by being disciplined and occasional peer editing.
I can also see the value of keeping the sectN elements in place for legacy documents. This, in my mind, is the best reason for keeping them. There is a lot of content out there that is using DocBook and likely a lot that use the sectN elements. It doesn't hurt too much to keep the elements in place while encouraging people to use the section element instead.
June 10, 2011
April 28, 2011
Agile Is NOT a Process
Rant warning.
I've heard one too many people either ask me if I work in an agile environment or tell me that their team is doing agile development. The English teacher in me goes berserk when I think of the abuse they are doing to the word agile. They have taken a simple, clear word and turned it into marketing slang for any manner of product management process that doesn't involve long range planning.
I've worked on several teams that were "agile" and been to training to for another that was attempting to be "agile". Let's just say I've seen mixed results.
In fact, one of the most agile teams I worked on did formal long range project planning with feature specs and everything. We had an overall idea of what we wanted to build and worked towards it. However, we also did good beta programs and customer outreach during the development cycle. This way we could validate what we were doing against what was really needed. If we needed to change, we did. It probably helped that I worked with a very talented group of software engineers who liked modular architectures and an excellent customer facing product manager who understood the customer's as well as the the developer's.
The least agile team I worked on also followed the classic model. However, they were a monolithic, top-down driven team that was a slave to their process. Development cycles were months long and getting a new feature in, or responding to a change in priorities, was virtually impossible. I wasn't on this team long (it made me crazy), so I have no idea what confluence of factors made it so rigid.
This same team is now "agile" thanks to adopting SCRUM. They still have long development cycles, although they are split into two week sections. Getting new features, or responding to changing demands, is still virtually impossible. The things that have changed are that less people actually know what the feature set will look like, the writers are more in the dark than usual, and the release date is so fuzzy that it may simply arrive without warning.
I worked on an XP "agile" team as well. I'd put there agility in the moderate range, but they were that agile before XP. What XP did bring was more frequent meetings, less shared information, and a steep decline in release quality. We still marched for a set date and a predefined feature set, but product management reserved the right to change the feature set at will without changing the release date. We also did away with any meaningful sense of resource planning. More meetings and less quality is the kind of outcome I look for from a hot process.
One friend was telling me that his work estimates for a big project were rejected because they were done in hours. Since they are SCRUM "agile", estimates cannot be anything as tangible as hours. So, he went back to his desk, removed the word hours from the estimates, and waited a day before resubmitting the estimates. Naturally, they were perfectly OK. One of the funniest parts of this to me was that he was asked to do planning four months out.
At FuseSource we are pretty agile, without using any formal process. We keep in touch with customers, design in a way that makes responding to change easier, keep open lines of communication between all functional groups, and get the job done. Things can get a little chaotic, but that is pretty common in software development. The key point is that we make solid quality products and can respond to customer needs quickly.
So my point is that being agile isn't about doing "agile". Most of what people mean way they say they are on a team that is doing agile development is that they are following one of the "agile" product management processes that their management was sold. If the team isn't agile, no amount of mystical "agile" religion will make it agile. All doing "agile" will do is replace one set of rigidity with another. On the flip-side an agile team will be agile regardless of the process imposed on it. There are definitely processes that will be less efficient than others, but a truly agile team will either stop using them or find a way to make them work.
I've heard one too many people either ask me if I work in an agile environment or tell me that their team is doing agile development. The English teacher in me goes berserk when I think of the abuse they are doing to the word agile. They have taken a simple, clear word and turned it into marketing slang for any manner of product management process that doesn't involve long range planning.
I've worked on several teams that were "agile" and been to training to for another that was attempting to be "agile". Let's just say I've seen mixed results.
In fact, one of the most agile teams I worked on did formal long range project planning with feature specs and everything. We had an overall idea of what we wanted to build and worked towards it. However, we also did good beta programs and customer outreach during the development cycle. This way we could validate what we were doing against what was really needed. If we needed to change, we did. It probably helped that I worked with a very talented group of software engineers who liked modular architectures and an excellent customer facing product manager who understood the customer's as well as the the developer's.
The least agile team I worked on also followed the classic model. However, they were a monolithic, top-down driven team that was a slave to their process. Development cycles were months long and getting a new feature in, or responding to a change in priorities, was virtually impossible. I wasn't on this team long (it made me crazy), so I have no idea what confluence of factors made it so rigid.
This same team is now "agile" thanks to adopting SCRUM. They still have long development cycles, although they are split into two week sections. Getting new features, or responding to changing demands, is still virtually impossible. The things that have changed are that less people actually know what the feature set will look like, the writers are more in the dark than usual, and the release date is so fuzzy that it may simply arrive without warning.
I worked on an XP "agile" team as well. I'd put there agility in the moderate range, but they were that agile before XP. What XP did bring was more frequent meetings, less shared information, and a steep decline in release quality. We still marched for a set date and a predefined feature set, but product management reserved the right to change the feature set at will without changing the release date. We also did away with any meaningful sense of resource planning. More meetings and less quality is the kind of outcome I look for from a hot process.
One friend was telling me that his work estimates for a big project were rejected because they were done in hours. Since they are SCRUM "agile", estimates cannot be anything as tangible as hours. So, he went back to his desk, removed the word hours from the estimates, and waited a day before resubmitting the estimates. Naturally, they were perfectly OK. One of the funniest parts of this to me was that he was asked to do planning four months out.
At FuseSource we are pretty agile, without using any formal process. We keep in touch with customers, design in a way that makes responding to change easier, keep open lines of communication between all functional groups, and get the job done. Things can get a little chaotic, but that is pretty common in software development. The key point is that we make solid quality products and can respond to customer needs quickly.
So my point is that being agile isn't about doing "agile". Most of what people mean way they say they are on a team that is doing agile development is that they are following one of the "agile" product management processes that their management was sold. If the team isn't agile, no amount of mystical "agile" religion will make it agile. All doing "agile" will do is replace one set of rigidity with another. On the flip-side an agile team will be agile regardless of the process imposed on it. There are definitely processes that will be less efficient than others, but a truly agile team will either stop using them or find a way to make them work.
April 27, 2011
Video Tutorials
Video is all the rage these days, but I have been trying to avoid making them. It's not that I don't appreciate the strength of videos for marketing and for visual learners. It is just that my medium is static words on a page, not moving pictures with audio.
It came to pass that FuseSource wants video tutorials and the writers have been assigned the task of producing them. I did the first one recently and it was an interesting challenge - I should say series of challenges.
The first challenge is figuring out what software to use building the tutorials. There are a number of screen recording tools available, like Camtasia, you can record a WebEx, or you can go with a tool geared more towards e-learning and demo creation, like Captivate. I quickly ruled out the WebEx idea. Some consultation with co-workers who make video tutorials at Progress strongly suggested using Captivate over Camtasia. Captivate is more forgiving and more flexible.
The big problem with Captivate is the price tag.... So, I set out to find a freeware alternative if possible. Fortunately I stumbled upon Wink from DebugMode(http://www.debugmode.com/wink/). I has most of the features of Captivate for free!!
Tool in hand, I created the video portion of the tutorial. Wink lets you record as a stream or based on mouse/keyboard clicks. I opted for the mouse/keyboard clicks method because that was what I was told worked best. So, I ran through the demo I was using for the tutorial and captured everything. This was a little nerve wracking because you want it to go smoothly. This is where doing it based on mouse/keyboard clicks comes in handy. If you record the demo as a steam, you have to restart every time you make a mistake. Using the mouse/keyboard saves the session as a collection of individual frames so you can remove mistakes later.
The resulting video capture was pretty good overall. A few places were choppy and in a few places the cursor jumped around a bit.
Wink lets you do a bunch of editing of the individual slides, so I could fix most of the choppy bits. I could also edit out any mistakes. It also allows you to add text boxes, images, and links onto the frames. This is one place where the price of the software is evident-there are not a lot of choices for button styles or text box controls.
Laying down the audio was tedious, but not because the tool makes it hard. In fact Wink makes it pretty simple. Doing audio is tedious for several reasons. The first is that I hate listening to my own voice for an entire day. Second, I'm not a trained voice talent, so I am not graceful at reading prepared texts. There are stops, stutters, strange tonal changes, pauses. I had to redo several portions of the audio multiple times to get it acceptable.
So, the first one is done. I've learned that doing a video takes a lot of prep work. You need to plan out what you intend to do and make sure that it is a) not too long b) visually interesting (watching a maven build scroll by does not make good video) c) going to work consistently. I've also learned that it takes a long time to make a short video. This first one took the better part of a day and it is only a few minutes long. I'm pretty sure I'll get better, but not so sure I can get faster.
It came to pass that FuseSource wants video tutorials and the writers have been assigned the task of producing them. I did the first one recently and it was an interesting challenge - I should say series of challenges.
The first challenge is figuring out what software to use building the tutorials. There are a number of screen recording tools available, like Camtasia, you can record a WebEx, or you can go with a tool geared more towards e-learning and demo creation, like Captivate. I quickly ruled out the WebEx idea. Some consultation with co-workers who make video tutorials at Progress strongly suggested using Captivate over Camtasia. Captivate is more forgiving and more flexible.
The big problem with Captivate is the price tag.... So, I set out to find a freeware alternative if possible. Fortunately I stumbled upon Wink from DebugMode(http://www.debugmode.com/wink/). I has most of the features of Captivate for free!!
Tool in hand, I created the video portion of the tutorial. Wink lets you record as a stream or based on mouse/keyboard clicks. I opted for the mouse/keyboard clicks method because that was what I was told worked best. So, I ran through the demo I was using for the tutorial and captured everything. This was a little nerve wracking because you want it to go smoothly. This is where doing it based on mouse/keyboard clicks comes in handy. If you record the demo as a steam, you have to restart every time you make a mistake. Using the mouse/keyboard saves the session as a collection of individual frames so you can remove mistakes later.
The resulting video capture was pretty good overall. A few places were choppy and in a few places the cursor jumped around a bit.
Wink lets you do a bunch of editing of the individual slides, so I could fix most of the choppy bits. I could also edit out any mistakes. It also allows you to add text boxes, images, and links onto the frames. This is one place where the price of the software is evident-there are not a lot of choices for button styles or text box controls.
Laying down the audio was tedious, but not because the tool makes it hard. In fact Wink makes it pretty simple. Doing audio is tedious for several reasons. The first is that I hate listening to my own voice for an entire day. Second, I'm not a trained voice talent, so I am not graceful at reading prepared texts. There are stops, stutters, strange tonal changes, pauses. I had to redo several portions of the audio multiple times to get it acceptable.
So, the first one is done. I've learned that doing a video takes a lot of prep work. You need to plan out what you intend to do and make sure that it is a) not too long b) visually interesting (watching a maven build scroll by does not make good video) c) going to work consistently. I've also learned that it takes a long time to make a short video. This first one took the better part of a day and it is only a few minutes long. I'm pretty sure I'll get better, but not so sure I can get faster.
February 23, 2011
Context First
I just listened to a talk by Brian O'Leary called "Context first: A unified theory of publishing"(http://vimeo.com/20179653). In the talk O'Leary posits that the thing killing the publishing industry is something he calls the container model. Publishers, and authors, think of content in terms of the container it is intended to fill and in doing so leave the content's metadata, its context, on the table. A newspaper company, and its writers, think of the content the generate as articles that live in a single edition of the news paper. All of the context that links an article to other articles in time and space is lost. When the article goes on-line, there is an attempt to recreate the context, but it is never going to recreate the full context. The paradigm needs to shift so that context is a primary consideration when creating content. Modern customers live in a world of content abundance and thus do not value content as much as they value services that make content discovery easy.
What does this have to do with technical writing? A lot. A large chunk of what technical writers do is make information accessible and discoverable. If we primarily think in terms of books, articles, help systems, topics, etc. then we run the risk of forgetting how each chunk of information fits into the whole and making that clear. We also forget to add the metadata needed to make the content easily discoverable. It is the indexing argument for the digital age. Authors put the indexing off until the end and usually end up with less than ideal indexes or none at all. Now we skip the indexes because everyone uses search to discover content, but we don't add any of the metadata to make the content search better. We leave it up to full text search to pluck words off the page or title searches.
Thinking about content as part of a whole and adding metadata to improve content discovery are key parts of a modern digital technical library. It is also value that requires specific skills to create. Indexing is hard and so is tagging.
What does this have to do with technical writing? A lot. A large chunk of what technical writers do is make information accessible and discoverable. If we primarily think in terms of books, articles, help systems, topics, etc. then we run the risk of forgetting how each chunk of information fits into the whole and making that clear. We also forget to add the metadata needed to make the content easily discoverable. It is the indexing argument for the digital age. Authors put the indexing off until the end and usually end up with less than ideal indexes or none at all. Now we skip the indexes because everyone uses search to discover content, but we don't add any of the metadata to make the content search better. We leave it up to full text search to pluck words off the page or title searches.
Thinking about content as part of a whole and adding metadata to improve content discovery are key parts of a modern digital technical library. It is also value that requires specific skills to create. Indexing is hard and so is tagging.
February 9, 2011
Someday ...
Interesting thoughts on building software that can be applied to documentation as well: AlBlue’s Blog: Someday ...: "Someday, all software will be built this way. I've been a fan of Git for a while now; I've written a few Git posts in the past including the..."
In the case of documentation, the source would be XML of some ilk and the build process fully automated.
In the case of documentation, the source would be XML of some ilk and the build process fully automated.
January 28, 2011
Mark-up Smackdown
In the tradition of old is new mark-up languages are making a serious comeback for professional technical documentation. In the dark ages troff and other *roff variants ruled the roost. As more writers moved into technical writing and computer graphics got more powerful WYSIWYG tools like FrameMaker and Word rose to prominence. Now the pendulum is swinging back to mark-up.
Markup languages come in two basic flavors: presentation mark-up and structural mark-up. The difference is that presentation mark-up is focused on how the text is presented and structural mark-up is focused on the structure of the content. The difference is subtle but important.
Focusing on presentation, as most current WYSIWYG editors do, tend to favor a particular presentation medium (the Web, print, slides). While the presented content appears to have a structure because it has headings and lists, etc. the underlying source has no real structure. A writer is free to use lists and headings in any way they wish. This is nice for. Writer, but makes content reuse more difficult.
Focusing on structure removes the preference for any one particular presentation medium, but it does mean that more work is required to transform the source content into a presentation medium. The underlying source has an enforced structure to which a writer must adhere. The enforced structure is limiting, but allows for easier reuse.
Among the popular current presentation mark-up languages there is a pretty consistent preference towards Web presentation. Along with HTML there are a number of wiki mark-ups in use including MediaWiki, Confluence, and MoinMoin. There is also Markdown and Textile. They all attempt to make it easier to craft good looking content on the Web. To a high degree they all succeed. I personally like Textile and Markdown because they allow the writer to mix in HTML code to fill in gaps left by the mark-up language. The draw back to all of these languages is that they do not replicate all of the functionality of HTML and their syntaxes can be fidgety. If you don't do it exactly right the resulting output is bad and there are no good tools to help you get it right.
In terms of appropriateness for large technical documentation projects, presentation languages have serious drawbacks that counteract the oft touted claim that they are way easier to use than the alternatives. Because they leave structure up to the writer and the base unit of content is a page, it is difficult to recombine content or enforce uniform structure across a documentation set. They don't generally provide tools for indexing content or thinking of organizing content beyond a single page. They also don't have easy translations into any other presentation medium than HTML.
Structured mark-up languages, such as DocBook and DITA, push concerns about presentation into backend processing stages. The mark-up itself deals with content structure. They have enforced concepts of what makes up a unit of content. DocBook uses structures like chapters and sections. DITA uses structures like procedures and reference topics. These units of information are easily combined into larger structures like books and libraries. The drawback for some writers is that there is no easy way of seeing what the content will look like when it is published. A lot of people find it easier to write when they can see a representation of the final product and feel like they need control over the design of the content on the page. Another drawback is that structural mark-up tends to be more complex than presentation mark-up. The learning curve is steeper, but there are a numbered of tools available that support content completion for DocBook and DITA.
For large scale documentation projects structured mark-up, despite its steeper learning curve, has the edge over presentation mark-up. The freely available toolchains for them provide translation into Web and print formats. They have indexing mechanisms and provide structures to support content beyond a single page or unit.
The presentation mark-up will continue to be good choices for content developed by small teams or developers. For big projects down by professional teams, structured mark-up i the future.
Markup languages come in two basic flavors: presentation mark-up and structural mark-up. The difference is that presentation mark-up is focused on how the text is presented and structural mark-up is focused on the structure of the content. The difference is subtle but important.
Focusing on presentation, as most current WYSIWYG editors do, tend to favor a particular presentation medium (the Web, print, slides). While the presented content appears to have a structure because it has headings and lists, etc. the underlying source has no real structure. A writer is free to use lists and headings in any way they wish. This is nice for. Writer, but makes content reuse more difficult.
Focusing on structure removes the preference for any one particular presentation medium, but it does mean that more work is required to transform the source content into a presentation medium. The underlying source has an enforced structure to which a writer must adhere. The enforced structure is limiting, but allows for easier reuse.
Among the popular current presentation mark-up languages there is a pretty consistent preference towards Web presentation. Along with HTML there are a number of wiki mark-ups in use including MediaWiki, Confluence, and MoinMoin. There is also Markdown and Textile. They all attempt to make it easier to craft good looking content on the Web. To a high degree they all succeed. I personally like Textile and Markdown because they allow the writer to mix in HTML code to fill in gaps left by the mark-up language. The draw back to all of these languages is that they do not replicate all of the functionality of HTML and their syntaxes can be fidgety. If you don't do it exactly right the resulting output is bad and there are no good tools to help you get it right.
In terms of appropriateness for large technical documentation projects, presentation languages have serious drawbacks that counteract the oft touted claim that they are way easier to use than the alternatives. Because they leave structure up to the writer and the base unit of content is a page, it is difficult to recombine content or enforce uniform structure across a documentation set. They don't generally provide tools for indexing content or thinking of organizing content beyond a single page. They also don't have easy translations into any other presentation medium than HTML.
Structured mark-up languages, such as DocBook and DITA, push concerns about presentation into backend processing stages. The mark-up itself deals with content structure. They have enforced concepts of what makes up a unit of content. DocBook uses structures like chapters and sections. DITA uses structures like procedures and reference topics. These units of information are easily combined into larger structures like books and libraries. The drawback for some writers is that there is no easy way of seeing what the content will look like when it is published. A lot of people find it easier to write when they can see a representation of the final product and feel like they need control over the design of the content on the page. Another drawback is that structural mark-up tends to be more complex than presentation mark-up. The learning curve is steeper, but there are a numbered of tools available that support content completion for DocBook and DITA.
For large scale documentation projects structured mark-up, despite its steeper learning curve, has the edge over presentation mark-up. The freely available toolchains for them provide translation into Web and print formats. They have indexing mechanisms and provide structures to support content beyond a single page or unit.
The presentation mark-up will continue to be good choices for content developed by small teams or developers. For big projects down by professional teams, structured mark-up i the future.
January 14, 2011
Resolutions
I recently read an article by one of those magazine shrinks that said that the important part about new years resolutions isn't keeping them; it's making them that matters. The process of making resolutions forces you to imagine how you would like your life to be different and imagine actions you can take to make the dream real. The more specific the resolutions the better.
Since it is that time of year, I'm going to take the article to heart and make three specific resolutions; one for work, one for family, and one for me.
For work I resolve to work as part of a team that accepts nothing short of excellent. Far to often we settle for doing the minimum because of resource constraints or we accept crappy user interfaces because the developers know best. This year I resolve that I will strive to do what is needed to provide the maximum benefit for the end user. I will not simply accept good enough. I will not sit idly by when a developer creates a bad UI or tries to slip a buggy feature into a release because it is good enough or there isn't enough time to fix it.
At home I resolve to do more around the house. I have a bad habit of putting off washing the dinner dishes until H just does them. I also tend to let laundry sit without being folded. In the warmer months I'm not great at keeping up with the yard work. This year I will be better about getting this stuff done.
For myself I resolve to take better care of myself. This includes flossing every night, doing something active at least three times a week, and eating better. I'll think twice before stopping at the McDonalds for a super size Big Mac meal. I'll actually order non-fat lattes. I'll eat more veggies. I'll actually start using the gym at work.
I want to be around for Kenzie for as long as possible. I also want to be a good role model for her. I want her to grow up seeing her dad living a healthy lifestyle, treating his partner with love and respect, and striving to be the best the he can be.
I know I'll fall short of these resolutions, but I will try to get closer to living my life according to them.
Since it is that time of year, I'm going to take the article to heart and make three specific resolutions; one for work, one for family, and one for me.
For work I resolve to work as part of a team that accepts nothing short of excellent. Far to often we settle for doing the minimum because of resource constraints or we accept crappy user interfaces because the developers know best. This year I resolve that I will strive to do what is needed to provide the maximum benefit for the end user. I will not simply accept good enough. I will not sit idly by when a developer creates a bad UI or tries to slip a buggy feature into a release because it is good enough or there isn't enough time to fix it.
At home I resolve to do more around the house. I have a bad habit of putting off washing the dinner dishes until H just does them. I also tend to let laundry sit without being folded. In the warmer months I'm not great at keeping up with the yard work. This year I will be better about getting this stuff done.
For myself I resolve to take better care of myself. This includes flossing every night, doing something active at least three times a week, and eating better. I'll think twice before stopping at the McDonalds for a super size Big Mac meal. I'll actually order non-fat lattes. I'll eat more veggies. I'll actually start using the gym at work.
I want to be around for Kenzie for as long as possible. I also want to be a good role model for her. I want her to grow up seeing her dad living a healthy lifestyle, treating his partner with love and respect, and striving to be the best the he can be.
I know I'll fall short of these resolutions, but I will try to get closer to living my life according to them.
November 30, 2010
The Silent Bias
One of the frustrating things about working as a writer in engineering driven organizations is the persistent, although unspoken, bias against documentation. There is a lot of lip service given to how "good documentation is as important as good code", but the truth comes out when the rubber hits the road. Writers as not given the same respect as coders, coding take priority over reviewing, documentation is expected to rush, and documentation is rarely involved in product design except as an after thought.
Not too long ago, I was part of a discussion about how to handle documentation for one of the Apache projects. The community wanted to make it easy for people to submit documentation to the project, so they had set the barrier to entry well below that which was acceptable for code submissions. Before any code written by a coder without commit rights must have the code reviewed by a committer before it can be added to the code base. For documentation the only requirement for making changes was a signed CLA. Everyone agreed that documentation is as important as code, but didn't see how the different standards exposed the truth. Committers didn't want to have to review documentation changes because it was a hit on their time.
The other interesting thing about the discussion was the assumption that writers wouldn't, or couldn't, learn how to use a source control system or a build system. Most writers do find source control systems tedious, but they are also a fact of life for anyone working in engineering centric firms. A writer who is capable of writing good documentation for an open source project is more than capable of learning a build system and a source control system.
I won't go into my other sob stories about how documentation, even documentation that is integrated into a user interface, is treated like an after thought in the product design process. I also won't go into how many writers and writing teams are complicit in continuing the silent bias.
I will say that the silent bias does hurt product quality in the end. Crappy documentation lowers the user's impression of the product.
Not too long ago, I was part of a discussion about how to handle documentation for one of the Apache projects. The community wanted to make it easy for people to submit documentation to the project, so they had set the barrier to entry well below that which was acceptable for code submissions. Before any code written by a coder without commit rights must have the code reviewed by a committer before it can be added to the code base. For documentation the only requirement for making changes was a signed CLA. Everyone agreed that documentation is as important as code, but didn't see how the different standards exposed the truth. Committers didn't want to have to review documentation changes because it was a hit on their time.
The other interesting thing about the discussion was the assumption that writers wouldn't, or couldn't, learn how to use a source control system or a build system. Most writers do find source control systems tedious, but they are also a fact of life for anyone working in engineering centric firms. A writer who is capable of writing good documentation for an open source project is more than capable of learning a build system and a source control system.
I won't go into my other sob stories about how documentation, even documentation that is integrated into a user interface, is treated like an after thought in the product design process. I also won't go into how many writers and writing teams are complicit in continuing the silent bias.
I will say that the silent bias does hurt product quality in the end. Crappy documentation lowers the user's impression of the product.
November 2, 2010
Marking it Up
At my last gig I spent most of my time writing in Frame Maker and Word. It was terrible. These are supposedly the alpha dogs of the computerized word manipulation tools, but they really point out the draw backs to all of the fancy WYSIWYG writing technology that has been developed. The text on the screen looks great, but the interface required to make the text look great gets in the way of writing. All of the buttons and fancy fonts and margin controls and table tools are distractions. The crashes and weird behaviors are annoyances.
When I joined FuseSource I returned to a shop that eschews all the fancy tools for writing in a mark-up language. Most of the documentation is written in DocBook XML. I'm not going to lie and say that DocBook is easy to learn or that it doesn't have it's quirks. You do need to learn which tags to use and when to use them. Some of the tags don't make sense or are overly complicated.
What I will say is that once you learn some of the tags, they fade into the background and you are left with just the writing. Your hands can stay on the keyboard because your not off looking for the bold button or using some key combo. You don't worry about how things will look because it is not in your face. You worry about what the words say when you are writing and wait until you publish to worry about what it looks like.
I've also been doing some work in other mark up languages like Confluence wiki text, Markdown, and Jade. Like DocBook they have their quirks. Unlike DocBook, they are true presentation mark up. The marks do not denote what the word represents it denotes how it will look. This makes the writing process a little different, but using mark up makes creating the content the center of the process. You still aren't confronted with a constant representation of the page. You still don't have to twist your hands into awkward twister poses to underline something.
When you are done creating the content, you can think about how it will be laid out in a medium. You can customize things for professional printing, for PDFs that will be printed out in an office, for a desktop Web browser, and for an iPhone. The layout process has it's own time and space. You can focus on that and not on the words.
Combining the writing process and the layout process is not more efficient. The human mind is lousy at multitasking.
When I joined FuseSource I returned to a shop that eschews all the fancy tools for writing in a mark-up language. Most of the documentation is written in DocBook XML. I'm not going to lie and say that DocBook is easy to learn or that it doesn't have it's quirks. You do need to learn which tags to use and when to use them. Some of the tags don't make sense or are overly complicated.
What I will say is that once you learn some of the tags, they fade into the background and you are left with just the writing. Your hands can stay on the keyboard because your not off looking for the bold button or using some key combo. You don't worry about how things will look because it is not in your face. You worry about what the words say when you are writing and wait until you publish to worry about what it looks like.
I've also been doing some work in other mark up languages like Confluence wiki text, Markdown, and Jade. Like DocBook they have their quirks. Unlike DocBook, they are true presentation mark up. The marks do not denote what the word represents it denotes how it will look. This makes the writing process a little different, but using mark up makes creating the content the center of the process. You still aren't confronted with a constant representation of the page. You still don't have to twist your hands into awkward twister poses to underline something.
When you are done creating the content, you can think about how it will be laid out in a medium. You can customize things for professional printing, for PDFs that will be printed out in an office, for a desktop Web browser, and for an iPhone. The layout process has it's own time and space. You can focus on that and not on the words.
Combining the writing process and the layout process is not more efficient. The human mind is lousy at multitasking.
October 15, 2010
Integrating Community Content with Commercial Content
One of the challenges facing a doc team working on commercial open source products is navigating the space between community sourced content and commercially sourced content. Does it make sense to use community sourced content? How much content does the team push back into the community? What policies need to be in place to facilitate the transfer content across the boundary?
To maximize efficiency, it makes sense to incorporate community sourced documentation into the commercial documentation. Leveraging the community multiplies the number of writers without increasing costs. The community also, in many cases, is where the most knowledgeable people (users and developers) live.
Using the community content creates a number of dilemmas:
The first is the legal ramifications of using the content. Can the content be reused? What citations and notices need to be included? Does using community content mean that all of the commercially generated content become owned by the community?
Once the legal issues are resolved, the next dilemma is a product question. If the bulk of the content is community sourced, what it the value being added by the doc team? Is it just repackaging to align with specific versions and ease accessibility? Does the doc team edit the content? Or is there some percentage of content that is added exclusively to the commercial documentation?
The product team also needs to determine how much of the work done by the doc team is kept internal. For the code,, the answer is that most of it is pushed back into the community. Only very targeted features are kept back as a value add. For documentation, the question is more nuanced. Documentation is almost exclusive a value add proposition for a commercial open source offering, so figuring out how much to dilute that value is difficult. If content is being taken from the community, the doc team has an obligation, morally, to return something back. At the very least, the doc team should provide editing support to the community. Beyond that, however, what is the right amount of back flow?
Once the product team has decided the strategic approach, the technical dilemmas rear their head:
Is the community content in a format that is easily consumable by the doc team? Many open source products use wikis of one flavor or another for their documentation. While wikis are easy to edit and provide some nice community features, they are not great for commercial documentation. They have versioning problems, limited formatting capabilities, limited work flow control, and a number of other deficiencies. Commercial doc teams typically work in either a dinosaur product, like FrameMaker or Word, or an XML format, like DocBook or DITA. Some wikis have tools for exporting to XML formats with varying levels of success. Some open sour projects are willing to switch to XML. In either case, there are hurdles that need to be overcome if content is to be shared.
Many open source projects are not great about versioning documentation. They end up with a single set of documentation with a mishmash of content and a lot of "in version x, but in version y". Commercial documentation cannot function that way. How do you ensure some level of version sanity when importing the community content?
Community content is either very stale or in a constant state of flux. Stale content is easy to merge, but constantly changing content poses a problem. Is there a single person responsible for handling merges? Is there a merge schedule? What about outbound merges?
While many communities generate good quality content, it is often in need of editing and vetting. How is that handled? Are the edits made in the community version and imported? Are they made internally and exported on a case by case basis? How is the community content vetted? Does need to reviewed by internal engineers? Or can it be assumed that the community's self-policing ensures that the content is technically accurate?
FuseSource has taken a firewall approach to solving the problem. The community content is used as an information source, but not directly copied. When content is contributed back into the community, it is added to the project's wiki alongside the other content. We do provide some editing support to the community sites. There have also been cases where the product team decided that a piece of content made more sense in the community, so it was simply contributed.
Initially, we choose this approach for technical reasons. We didn't have a clean way to get content out of a Confluence wiki and into DocBook. Fintan Bolton solved that problem with his Confdoc plug-in, but we have continued the same firewall approach. Now it is for simplicity sake. Building an import/export system and a set of policies about moving content back and forth the divide seems to be of dubious value in many cases.
Much of the community sourced content is excellent for highly technical users who are comfortable off-roading. It needs some serious work to be made appropriate for the average corporate developer. In many ways, it would be inappropriate to dumb down the content in the community. Solving the versioning issues are tricky. Is it worth the effort if the community does not seem to care?
We do directly import some reference content. The import is one way. We make edits in the community and then suck the content into our repository. It works because the amount of material sucked in is massive and easy to edit. There is, however, a decent amount of post-processing that needs to be done after the content is inside the wall.
Neither method is particularly efficient. I'd love to hear how other groups solve this problem.
To maximize efficiency, it makes sense to incorporate community sourced documentation into the commercial documentation. Leveraging the community multiplies the number of writers without increasing costs. The community also, in many cases, is where the most knowledgeable people (users and developers) live.
Using the community content creates a number of dilemmas:
The first is the legal ramifications of using the content. Can the content be reused? What citations and notices need to be included? Does using community content mean that all of the commercially generated content become owned by the community?
Once the legal issues are resolved, the next dilemma is a product question. If the bulk of the content is community sourced, what it the value being added by the doc team? Is it just repackaging to align with specific versions and ease accessibility? Does the doc team edit the content? Or is there some percentage of content that is added exclusively to the commercial documentation?
The product team also needs to determine how much of the work done by the doc team is kept internal. For the code,, the answer is that most of it is pushed back into the community. Only very targeted features are kept back as a value add. For documentation, the question is more nuanced. Documentation is almost exclusive a value add proposition for a commercial open source offering, so figuring out how much to dilute that value is difficult. If content is being taken from the community, the doc team has an obligation, morally, to return something back. At the very least, the doc team should provide editing support to the community. Beyond that, however, what is the right amount of back flow?
Once the product team has decided the strategic approach, the technical dilemmas rear their head:
Is the community content in a format that is easily consumable by the doc team? Many open source products use wikis of one flavor or another for their documentation. While wikis are easy to edit and provide some nice community features, they are not great for commercial documentation. They have versioning problems, limited formatting capabilities, limited work flow control, and a number of other deficiencies. Commercial doc teams typically work in either a dinosaur product, like FrameMaker or Word, or an XML format, like DocBook or DITA. Some wikis have tools for exporting to XML formats with varying levels of success. Some open sour projects are willing to switch to XML. In either case, there are hurdles that need to be overcome if content is to be shared.
Many open source projects are not great about versioning documentation. They end up with a single set of documentation with a mishmash of content and a lot of "in version x, but in version y". Commercial documentation cannot function that way. How do you ensure some level of version sanity when importing the community content?
Community content is either very stale or in a constant state of flux. Stale content is easy to merge, but constantly changing content poses a problem. Is there a single person responsible for handling merges? Is there a merge schedule? What about outbound merges?
While many communities generate good quality content, it is often in need of editing and vetting. How is that handled? Are the edits made in the community version and imported? Are they made internally and exported on a case by case basis? How is the community content vetted? Does need to reviewed by internal engineers? Or can it be assumed that the community's self-policing ensures that the content is technically accurate?
FuseSource has taken a firewall approach to solving the problem. The community content is used as an information source, but not directly copied. When content is contributed back into the community, it is added to the project's wiki alongside the other content. We do provide some editing support to the community sites. There have also been cases where the product team decided that a piece of content made more sense in the community, so it was simply contributed.
Initially, we choose this approach for technical reasons. We didn't have a clean way to get content out of a Confluence wiki and into DocBook. Fintan Bolton solved that problem with his Confdoc plug-in, but we have continued the same firewall approach. Now it is for simplicity sake. Building an import/export system and a set of policies about moving content back and forth the divide seems to be of dubious value in many cases.
Much of the community sourced content is excellent for highly technical users who are comfortable off-roading. It needs some serious work to be made appropriate for the average corporate developer. In many ways, it would be inappropriate to dumb down the content in the community. Solving the versioning issues are tricky. Is it worth the effort if the community does not seem to care?
We do directly import some reference content. The import is one way. We make edits in the community and then suck the content into our repository. It works because the amount of material sucked in is massive and easy to edit. There is, however, a decent amount of post-processing that needs to be done after the content is inside the wall.
Neither method is particularly efficient. I'd love to hear how other groups solve this problem.
October 8, 2010
Commercial Open Source Documentation
I'm back working on the Fuse products again and couldn't be happier. The fact that they are commercial offerings of open source projects makes working on them more interesting than working on commercially developed software. It is not that the products themselves are necessarily more interesting (although in this case they are), it is the challenges around documenting them that is more interesting.
In a purely commercial world, the whole process is controlled. The engineers are located within the boundaries of the company. They answer to managers that you can ping. The feature sets and release cycle are well defined and mostly static. The documentation requirements are usually spelled out by the product manager with some input from the writers. They are usually well understood early in the cycle. When the product ships, the documentation is frozen until the next release is planned.
In a commercial open source world, things are different. While some of the engineers work for the company, most of them are part of a larger community that are beyond the corporate wall. Feature sets and release cycles are planned, but the plans are usually changed due to unpredictable changes from the community. Documentation requirements tend to be fluid to match the product development process. Customers have a large influence on setting requirements for documentation. There is an expectation that improvements will roll out over the course of a products life cycle.
In addition there is the ongoing struggle between what to take from the community, what to offer back to the community, and what to keep as part of the commercial value add. Do you offer cleaned up versions of the community written documentation? Do you push content written internally back to the community? If so, what? What is the process for sharing content between the community and the internal documentation team?
Coping requires fluidity and focus. Being capable of changing when needed is crucial, but so isn't staying focused on the core value of what is being delivered to the customers. If a change doesn't make sense, you need to be able to see it.
The other thing that is crucial is a dedication to quality. It is far too easy to let quality slip in an effort to meet all of the demands. When you let quality slip, you let your value slip. The community can write documentation of questionable quality without paying for a writer or an offshore writer can be hired to do some rudimentary editing. Neither outcome is good for you or the customers. In the commercial open source market, customers do read the documentation.
In a purely commercial world, the whole process is controlled. The engineers are located within the boundaries of the company. They answer to managers that you can ping. The feature sets and release cycle are well defined and mostly static. The documentation requirements are usually spelled out by the product manager with some input from the writers. They are usually well understood early in the cycle. When the product ships, the documentation is frozen until the next release is planned.
In a commercial open source world, things are different. While some of the engineers work for the company, most of them are part of a larger community that are beyond the corporate wall. Feature sets and release cycles are planned, but the plans are usually changed due to unpredictable changes from the community. Documentation requirements tend to be fluid to match the product development process. Customers have a large influence on setting requirements for documentation. There is an expectation that improvements will roll out over the course of a products life cycle.
In addition there is the ongoing struggle between what to take from the community, what to offer back to the community, and what to keep as part of the commercial value add. Do you offer cleaned up versions of the community written documentation? Do you push content written internally back to the community? If so, what? What is the process for sharing content between the community and the internal documentation team?
Coping requires fluidity and focus. Being capable of changing when needed is crucial, but so isn't staying focused on the core value of what is being delivered to the customers. If a change doesn't make sense, you need to be able to see it.
The other thing that is crucial is a dedication to quality. It is far too easy to let quality slip in an effort to meet all of the demands. When you let quality slip, you let your value slip. The community can write documentation of questionable quality without paying for a writer or an offshore writer can be hired to do some rudimentary editing. Neither outcome is good for you or the customers. In the commercial open source market, customers do read the documentation.
What's more important: technical or writer?
Lately I have seen, and heard, a number of discussions of what skills are most important in a technical writer. The conclusion reached in most of these discussions saddens me. It seems that conventional wisdom is that technical skills are considered primary. One recruiter told me that all of the positions she has open are for programmer/writers with an emphasis on programming.
I can see why businesses would want technical writers that are highly technical. It lightens the burden on the engineers because the writers don't ask as many questions. It also means that the writers can do more than just write documentation. They can do QA or possibly code. The business doesn't have to waste as much money on documentation.
Ideally, businesses, and engineers, would like to see technical writers cease to exist. They cost money, ask too many questions, delay delivery dates, and whine about usability issues. The only value they serve is to create a bunch of content that customers demand, but never read.
What I cannot understand is why technical writers believe that technical skills are primary. The "technical" in the title is an adjective describing "writer." The value of a technical writer is that they can take jargon laden technical information from engineers and turn it into something readable by the uninitiated. They can write a process in a way that makes it clear. They can distill complex technical topics into chunks that a user can digest. Writing is the primary skill.
I'm not arguing that some technical skills are not important. My background in software engineering has been invaluable to me. However, it is my writing skills that make me good at my job. I've worked with several technical writers with excellent technical skills who were terrible technical writers. Sadly, they poor quality of their content usually is overlooked because they fit in with the engineers.
Writing first; technical second.
I can see why businesses would want technical writers that are highly technical. It lightens the burden on the engineers because the writers don't ask as many questions. It also means that the writers can do more than just write documentation. They can do QA or possibly code. The business doesn't have to waste as much money on documentation.
Ideally, businesses, and engineers, would like to see technical writers cease to exist. They cost money, ask too many questions, delay delivery dates, and whine about usability issues. The only value they serve is to create a bunch of content that customers demand, but never read.
What I cannot understand is why technical writers believe that technical skills are primary. The "technical" in the title is an adjective describing "writer." The value of a technical writer is that they can take jargon laden technical information from engineers and turn it into something readable by the uninitiated. They can write a process in a way that makes it clear. They can distill complex technical topics into chunks that a user can digest. Writing is the primary skill.
I'm not arguing that some technical skills are not important. My background in software engineering has been invaluable to me. However, it is my writing skills that make me good at my job. I've worked with several technical writers with excellent technical skills who were terrible technical writers. Sadly, they poor quality of their content usually is overlooked because they fit in with the engineers.
Writing first; technical second.
August 27, 2010
Getting Lost in Features
I have two pet peeves when it comes to "features". One is that we get very caught up in documenting a product's features and not how to use the product. The other, and the one this post is about, is that we tend to crave more features even when they don't make the product any better.
Yesterday I came across two articles. The first article was about a CS professor who uses old BBC micros to teach his students how to program. The micro strips away all of the "features" of modern IDE's and forces the students to think about the code. The second article was a meditation on the possibility that documentation efforts have become so focused on the shiny presentation features and rich editing features that quality content has been overlooked.
The "feature" overload problem makes me remember my early days of MP3 players with horror. I wanted no part of the iPod. It only supported a few formats, didn't have a radio tuner, didn't record, couldn't edit song titles, didn't have a way to make playlists on the fly..... Instead I raced out and bought a fancy Rio that supported every format known to man, recorded, had a radio tuner, and even had network syncing. The thing rocked, but it was a bitch to use. Worse, the radio sucked and I never recorded anything. The only "feature" that was useful was the network syncing because I didn't have a place near the computer to put the syncing cradle. As more of my friends got iPods and I got to use them, I became very jealous. The iPod looked good and was easy to use. Less features, but a better solution to the problem. When the Rio died, I replaced it with an iPod and never looked back.
I look at some of the Webhelp systems in the world and ask myself how much does all that Javascript goodness really add to the usefulness of the documentation. Does a collapsible TOC really make it easier to find things? Does putting the index on a separate tab make it easier to use? Does the half-assed search capabilities built into the system make it faster to find information? What about the buttons that collapse the TOC pain or sync the display to the TOC? They all look cool, but would spending more time on good content and good organization be more valuable? My answer is that the "features" of most documentation UI's are not that helpful and that better content is usually a good answer. Personally, I find using search painful and would prefer a halfway decent index any day.
I have the same problem with a lot of the documentation tools that are on the market. Framemaker, RoboHelp, ePublisher Pro, Flare, Word etc. are all powerful feature rich tools that are intended to make documentation production easier. They all, in their own ways, takes the writer away from the content. WYSWYG editors place too much emphasis on page-layout and distract from the words on the page. To cope with all of their features, and the odd missing features, takes a learning curve and often you are forced to make compromises to fit the tool.
Even some of the XML editor's for documentation can go overboard. They all do auto-complete to various degrees and have WYSWYG views. Give me a simple editors that validates my mark-up and spell checks and I'd be happy.
Let me focus on the words and not the tool.
We need to remember what problem the product is intended to solve and make it excellent at solving that problem. Strip away all features that do not further that goal.
Yesterday I came across two articles. The first article was about a CS professor who uses old BBC micros to teach his students how to program. The micro strips away all of the "features" of modern IDE's and forces the students to think about the code. The second article was a meditation on the possibility that documentation efforts have become so focused on the shiny presentation features and rich editing features that quality content has been overlooked.
The "feature" overload problem makes me remember my early days of MP3 players with horror. I wanted no part of the iPod. It only supported a few formats, didn't have a radio tuner, didn't record, couldn't edit song titles, didn't have a way to make playlists on the fly..... Instead I raced out and bought a fancy Rio that supported every format known to man, recorded, had a radio tuner, and even had network syncing. The thing rocked, but it was a bitch to use. Worse, the radio sucked and I never recorded anything. The only "feature" that was useful was the network syncing because I didn't have a place near the computer to put the syncing cradle. As more of my friends got iPods and I got to use them, I became very jealous. The iPod looked good and was easy to use. Less features, but a better solution to the problem. When the Rio died, I replaced it with an iPod and never looked back.
I look at some of the Webhelp systems in the world and ask myself how much does all that Javascript goodness really add to the usefulness of the documentation. Does a collapsible TOC really make it easier to find things? Does putting the index on a separate tab make it easier to use? Does the half-assed search capabilities built into the system make it faster to find information? What about the buttons that collapse the TOC pain or sync the display to the TOC? They all look cool, but would spending more time on good content and good organization be more valuable? My answer is that the "features" of most documentation UI's are not that helpful and that better content is usually a good answer. Personally, I find using search painful and would prefer a halfway decent index any day.
I have the same problem with a lot of the documentation tools that are on the market. Framemaker, RoboHelp, ePublisher Pro, Flare, Word etc. are all powerful feature rich tools that are intended to make documentation production easier. They all, in their own ways, takes the writer away from the content. WYSWYG editors place too much emphasis on page-layout and distract from the words on the page. To cope with all of their features, and the odd missing features, takes a learning curve and often you are forced to make compromises to fit the tool.
Even some of the XML editor's for documentation can go overboard. They all do auto-complete to various degrees and have WYSWYG views. Give me a simple editors that validates my mark-up and spell checks and I'd be happy.
Let me focus on the words and not the tool.
We need to remember what problem the product is intended to solve and make it excellent at solving that problem. Strip away all features that do not further that goal.
Subscribe to:
Posts (Atom)