|
|
|
posted at
05:13 PM
|
trackback
|
|
link
 Ok, we've seen some tips. What's the best way to conduct a tech review? There are many; the list below represents ways I have personally seen tried. Each approach has pluses and minuses. None are perfect, but if one isn’t working for you, try another.
Send out hardcopy
Advantages- People can review practically anywhere.
- Easy to get you incremental reviews – e.g. "Here’s the first 20 pages."
Disadvantages- Lots of people prefer working in soft copy.
- Need a way to show overall context of the docs you’re sending out for review.
- Handwriting can be hard to read, and people use idiosyncratic editing marks.
- Reviewers can't see each other's comments.
- Comments have to be transcribed.
- Can use a whole lotta paper.
- Potentially hard to enforce your schedule.
Send out softcopy (e.g. Word files) individually to each reviewer
Advantages- Reviewers can do softcopy edits – for example, use Word’s revision marks and comments.
Disadvantages- Reviewers can't see each other's comments.
- Need a way to show overall context of the docs you’re sending out for review.
- You must individually collate comments.
- Your doc format has to lend itself to this (i.e., might not work if you use proprietary authoring tools that your reviewers don’t have access to).
- Potentially hard to enforce your schedule.
Post a complete read-only doc set in a central location and specify which docs to review. Note that this is most useful when your doc set is finished enough to actually have context.
Advantages- People can see docs in context.
- They can choose what to review (among the topics you designate, hopefully).
Disadvantages- Need a way to guide a people to only the docs you want to review.
- Folks have to devise a way to send you comments.
- Reviewers can't see each other's comments.
- Potentially hard to enforce your schedule.
Put a read/write review copy in a central location and let folks have at this shared content.
Advantages- Reviewers can see each other's comments.
- Comments are all in one place.
- Reviewers can choose what to review (among the topics you designate).
- Potentially can show the context.
Disadvantages- You need source control to make sure people don’t hammer each other’s versions of the document. (If one reviewer checks out a doc for review and forgets to check it back in, it can hold up everyone.)
- Can suffer from the "I see someone else has reviewed this, so I won’t bother" problem.
- Potentially hard to enforce your schedule.
Use a tech-review tool. There are some dedicated tools that are designed to facilitate collaborative review. (LiveTechDocs is one; I’ve never used it, so I have no opinion on its qualities.)
Advantages- Depends on the tool. In the ideal case, the tool allows centralized review, multiple reviewers, an easy way to indicate comments, and low-friction workflow.
- Might provide more control over the schedule -- e.g., a way to remind reviewers of outstanding reviews, and a way to shut off review when your review period ends.
Disadvantages- Well, everyone needs to have the tool, which might require licenses or other overhead.
- Might support only limited document formats (and potentially not yours).
Put your content on a wiki and have reviewers edit it directly.
Advantages- You get a kind of finished text (pre-edit, presumably) rather than comments on the text.
- People in effect see each other’s comments.
- From the schedule perspective, you can take a drop of your content at any time
- People like wikis.[1]
Disadvantages- Often don’t support revision marks, etc. – it can be hard to tell what changes were made and by whom, except indirectly via page history.
Live reviews in a meeting. Set up a meeting, invite all your reviewers, show a document on the screen, and then discuss. Here’s Colleague Jim:I’ve settled on the "cage and feed" method. I order lunch for the reviewers, and then I project each topic on the wall, focusing their attention on areas that need help. I stack the agenda so that the most "important" topics appear first, which gives me most of the coverage I need. Follow-ups for more peripheral topics can be done over email. Advantages- You can get a bunch of feedback all at once.
- Your reviewers (hopefully) are all in agreement when you’ve finished.
- You control what reviewers see and comment on – you set the priorities.
- You control the schedule.
Disadvantages- Can be hard to organize (getting everyone to one meeting).
- You probably can't do these frequently.
- Can easily get off track unless you keep very firm control of the agenda.
- People rarely come prepared with comments already -- then often start reading at the meeting.
- In general, you get through less material, tho often with better feedback.
If you know of other strategies, by all means, let us know!
[categories]
writing
|
posted at
09:57 PM
|
trackback
|
|
link
Herewith, then, some ideas. I will actually start with general tips. Next time, some strategies.
Tips - Spell out what you want from the reviewer. Don't just throw it at them and hope for the best. Leave questions about specific things you want to get answered or draw their attention to. Colleague Brian left the following suggestions as a comment on the previous post:
I have a little boilerplate message telling them I want to know two things: (1) Is what's there correct? Run the code, try the steps, etc. (2) Is anything not there that should be? - Prioritize. You will have more to review than they'll have time for; not everything can be reviewed. Pick out the material that's most critical. Include the pri-2 stuff if you want, but make sure your priorities are clear to the reviewers. (See also next point.)
- Don't overwhelm. Choose a reasonable number of topics for review, not the entirety of a 1000-page book or doc set.
- Be aware of the reviewers' schedule. Don't schedule a tech review at a time when your reviewers are in their own crunch mode (which might not coincide with yours).
- Provide context. Show the reviewers how the topics under review fit into the larger documentation set and how they relate to each other. (Provide a table of contents, point to an online doc set, whatever.) Don't just give them a stack of docs in arbitrary order.
- Make it easy to review. Use any means you can – technological or other – to make it easy for people to review your docs. Stated another way, don't make your process a burden to the reviewers. Don't make it hard to get the docs to review, don't require that reviewers use clunky tools, don't make it hard for reviewers to get their feedback to you. If they want to email comments, say yes. If they want to meet with you face-to-face, say yes, etc.[1]
- Get the right reviewers, i.e., people who can provide you with concrete feedback. For example, don't send an enormous whitepaper for review to someone who only knows about a small segment of your product. Colleague Doug:
The targeted approach has worked best for me overall as in: I will focus most of my energy on these two people who actually have a clue and actually respond to me while still including all of the others that will ignore me. By the same token, ...
- Don't overlook possible reviewers. People who are not necessarily on your radar can be great reviewers, not just the direct stakeholders -- testers, other writers, even outside people who are under NDA.
- Find several reviewers. Don't rely on a single reviewer. At the same time, beyond a certain core number (3? 6?), you'll only get incremental additional value at best. (And don't forget that there will be overlap between you and other writers – don't overwhelm your backup reviewers.)
- Understand what you can get from specific reviewers. As I noted in the last post, people will have different knowledge, interests, and strengths to bring to a review. Find folks to cover the range of what you need.
- Be clear about your schedule. When do you want it (need it) back by?
And of course, ...
- Allow enough time! Paradoxically (or not), you also don't want to allow too much time.
- If you're not getting reviews, send out highly targeted, very specific text in email. This is a trick suggested by Colleague Rick: "I like to pull out a pre-edited paragraph that's over the line to get their attention. You can't do this on every article, but you can do it 4-5 times a year on the most difficult documents. I use it only when they are swamped and the usual requests for TR are ignored."
A particularly sneaky variation on this is to send out something that you know is wrong and say "This is ok, right?" From KC Lemson: "You'll be amazed at how quickly someone will take the time to correct you, particularly if the question was aimed at more than one person, since it's an opportunity for that person to prove their knowledge in front of others." Careful, tho. Rick: "You can't cry wolf too often."
- Finally, be grateful and acknowledge the help. Make people glad they helped you and willing to help you again.
In general, put yourself in their spot: if you were being asked to spend several hours reviewing someone else's work, how much time would you consider reasonable to do that, how much work would you be willing to do, and what would make it easiest for you?
Next time, strategies for how to conduct tech review.
[categories]
writing
|
Thursday, 12 August 2010
|
Pity the intermediate user
posted at
11:57 AM
|
trackback
|
|
link
Here's a fun exercise to try: Take a manual for a product that you know well and markup each section with who you think the writer is addressing--beginners, intermediate, or advanced users. Then calculate the percentage of the book dedicated to each type of audience. If there is a gap in the middle, as there often is, ask yourself if the documentation is truly serving the product's best interests. Expert information in a beginner's manual befuddles new users. Manuals that too dumbed down infuriate the experts. Those who somehow manage to graduate from being newbies? Well, I guess they'll figure it out.  This is one of those ideas that rings true the moment you hear it. In my own world, we put a lot of effort into ramp-up documentation -- start-up tutorials and overviews. However, our product, and to some extent the documention, has had the reputation for holding your hand tightly when you're a total newbie, but then dropping you off a cliff when it's time to move beyond the beginner stuff. And, of course, as Meyer suggests, we do create documentation that's strictly for experienced users, where we assume that the reader has fairly deep background on the topic in question. I would like to think that we provide a reasonable bridge from beginner to intermediate user, but I'm sure there are many users who would beg to differ.
There is a reason for all this. Writing beginners' documentation is common because it's the obvious audience (i.e., people new to your product) and because it's comparatively easy to gauge both what users know (nothing) and what they need (an intro to feature _________). Similarly, writing for an advanced audience can be easy (paradoxically) because you can assume all sorts of things about what they know and you can concentrate on very fine details of your product. You can often also simply describe features and technologies and let the reader deduce his or her own scenarios.
The intermediate audience is hard to write for, tho. One reason is that it's a spongy term -- maybe I work with a product (e.g. ASP.NET) regularly, but I've never used some particular feature (membership, say). In some senses I'm a beginner w/r/t membership, even though I'm an "intermediate" ASP.NET user. What can the writer for membership features assume about me? Hard to tell.
Or let's say I've done the beginner turorials for membership, which were relatively easy for the writer to spec and write. What is it I want to do now? Once I'm past the beginner stage, the matrix of possible scenarios that I need information for grows very quickly, and often starts overlapping with other features or technologies. It is considerably harder for writers to try to anticipate these scenarios and write docs for them.
In the documentation that accompanies early versions of a product, there's yet another problem. It's a priority to sort out what your beginner scenarios are and address those. There's a good chance, tho, that you don't even know what the intermediate scenarios are yet.[1]
I don't mean to suggest that because there are obstacles to writing intermediate docs, we are off the hook for doing it. It's an issue of being able to prioritize resources to address those scenarios and of having information about what those scenarios are.
For what it's worth, intermediate documentation is a niche that's often filled by two sources: blogs and third-party books. One could perhaps argue -- tho I won't -- that maybe that's the natural path: product docs -> blogs/books.
In any event, Meyer is right: the intermediate user is often frustrated. I know this from times when I myself am the intermediate user (of Office products, say) and can find only basics. Perhaps now that we've been reminded that we are short-changing this audience, we'll redouble our efforts to reach them.
[categories]
writing
|
posted at
06:12 PM
|
trackback
|
|
link
The advantage is you can go right to your version and be assured that what you're reading applies to you. The disadvantage is that the versions pile up (4 versions and counting), with a lot of overlap, which is inefficient in various dimensions.
Are you familiar with a doc set that handles versioning differently than this? (Conceptual or API reference or both.) If so, leave a comment with a link.
Thanks!
[categories]
writing, aspnet, technology
|
posted at
09:38 PM
|
trackback
|
|
link
 This gave me pause. We try to get a technical review of anything substantial we write, and we put a lot of stock in those reviews. Yet I still felt that whatever change I was arguing for was valid. So that got me to thinking about tech reviews and where they fit into the overall scheme of things when it comes to assessing the done-ness of a document. Conclusion: reviews are good (indeed, essential), but they're not the last word.
Why is that, tho? Well, here are some of the reasons I came up with (with help from the folks on my team) as to why a tech review might not be giving you the entire story:- TR is often done in a big hurry. It tends to come at a bad time for our reviewers, who have their own pressing deadlines to attend to. Anecdote: For our most recent release, our primary reviewer read something like 10 of our chapters all in one day (Father's Day, in fact). How carefully do you think he considered everything he was reading?
- In our division, TR is mostly about code. One thing that interests most of our reviewers is code, and they'll usually read that. Descriptions? Background? Step-by-step procedures? Maybe. Even so, reviewers often do not run code or follow steps to see if they work. One of my writers is quite adamant on this point: "Assume they haven't run your code. The burden of testing code is on you."
- Reviewers focus on what they're interested in. Not surprisingly, individual developers or testers, sometimes PMs, will zero in on the features they're most familiar with. If they don't work with something, they're unlikely to give it a thorough review, and might not even read it. (Sometimes they'll admit this, sometimes not.) If you get only one review, you need to be aware of what that reviewer's concerns are (and aren't) with respect to your document.
- TR often isn't looking at the big picture. Most reviewers will consider the text a given and will react to specifics in it. It's a pretty rare reviewer who will contemplate the flow or order of information, or even whether a section of a document (or the document itself) should even exist. And of course, few reviewers will sit and think about what's missing in your doc. (Another way to say this is that few reviewers do what's sometimes called a developmental edit of the document they're reading.)
- Reviewers focus on what's immediately in front of them. Somewhat related to the previous point. Unlike the writer, the reviewer probably doesn't know where any given document fits into the larger plan, and is therefore unlikely to assess the document in a bigger context. For example, a reviewer might simply assume that some concept or technique discussed in a document has been introduced somewhere else and not think to ask "Does the reader already know this?" This is a function of how tech review often occurs -- in pieces, with documentation not necessarily presented for review in the same order that the reader will ultimately see it.
- One review is just one opinion, as of today. A flippant way to say this is that if you get one review, you get one opinion. If you get two reviews, you have three opinions, and so on. Reviewers don't necessarily agree with each other, often quite dramatically. And even a single reviewer might change their mind based on others' thoughts, new information, your passionate rebuttal, time of day, phase of moon, whatever. (Much like editors, haha.) To be clear, the opinions you're getting are from experts, and are specifically what you're asking for. Still, even for the reviewers, there's a difference between an opinion and a fact.
- Reviewers make mistakes. Sometimes when you push back on a tech-review comment, the response is "Oops." But to know that, you'd have to push back, innit?
- Reviewers are not (necessarily) our audience. This is a variation on Homo Logicus -- our reviewers already know tons of stuff about what we're writing, and it's difficult to imagine the state of mind of someone to whom this is all new. For example, there's something slightly absurd about a bunch of lifelong professional programmers opining about what a rank beginner will or won't understand. That's like you and me sitting around arguing about how hard a foreigner might find it to learn English. No, we writerly types are the reader advocates, and we need to take that into account when we process TR comments.
- You have to know what you're getting from whom. If you're interested in the accuracy of your code, get a review from a tester. If you want to know whether your approach is a best practice, try grabbing a Dev lead. If you want to know whether you're messaging a feature right, grab the lead PM. Or whatever. But you don't want get these mixed up -- don't expect a tester to be telling you whether your document is positioning the product right, and I wouldn’t count on a lead PM to be running the steps in my procedures. (Always there are exceptions, of course.) As such, you need to weight appropriately the feedback you get from different people, based on their roles, and for that matter, on what you already know about their reviewing history, the time they're able to devote, and basically all of the above. Plus ...
- Some people are good reviewers, and others aren’t. ‘Nuff said.
The takeaway here is that you should not think that because something has gone through tech review, it must be right, and you must especially not think that because a reviewer said nothing about a chunk of text or code, that the reviewer must therefore approve of it. You're not necessarily getting approval; you're just not getting disapproval, based on what occurred to the reviewer off the top of their head in the small amount of time they allotted to reviewing your text.
And importantly, as one of writers summed it up, a tech review is just one type of input. It's an essential one, but there are other factors that go into documentation review beyond what you get in technical review.
Coming soon (for a broad definition of "soon"): Ok, so how do you get a good tech review? If you already have thots about that, by all means, leave a comment.
[categories]
writing
|
posted at
04:23 PM
|
trackback
|
|
link
So, when will this be available? Well, ok, so it's not Christmas 2010. This one's easy -- Christmas seems to have become something of a charged term. Let's, uh, not use that one.
What about Holidays 2010? Dunno, seems ok to me. Is it perhaps not specific enough? Maybe Holiday Season 2010? Maybe that's too long?
So the solution is ... Holiday 2010? Which holiday? Are they maybe leaving themselves lots of room to release during some holiday in 2010? Halloween-Thanksgiving-Christmas-whatever?
The thing is, that's distracting me so much that I haven't actually read the ad copy.
[categories]
language
|
posted at
03:06 PM
|
trackback
|
|
link
I just love this stuff. The Web Forms model was predicated on the idea of making web development something like forms for Windows client apps -- the page is a form, you drop controls onto it, set their properties, and respond to their events. This basically worked, although as many people pointed out over the years, this type of client-forms analogy was a leaky abstraction. There's a certain black-box quality to the Web Forms model, and doing tricky stuff -- perhaps just adding controls on the fly -- tended to make it clear just how much man there was behind the curtain. Plus its 8+ years of development have left it with a certain amont of cruft; even internally we still see questions about how to do things with (e.g.) the DataGrid control.
 ASP.NET MVC of course seeks to remove all this and, in a sense, get back to the basics of GET and POST, and instead of patching over them, embraces the realities of Web programming, like statelessness. The theory of MVC is lovely, but the implementation remains, at this point anyway, something that seems a bit ambitious as a candidate for Web Development 101.[1] (Likewise Ajax, which in spite of the elegance of libraries like jQuery, is still for the code junkie.)
And now there's Razor syntax. I said it earlier sort of jocularly, but in a sense it really is MVC for the rest of us. It has the purity of MVC -- the abstraction level is (comparatively) low (no "web controls"), it trucks openly with standard Web mechanics, it does not spill gallons of markup into your pages. Plus it offers a set of APIs that represent, to sound contradictory for a moment, thoughtful abstractions of functionality that is popular and, lest we forget, can sometimes be annoyingly complex to accomplish in "normal" ASP.NET, like database access or managing files. Plus it's completely backed by ASP.NET and beyond that, the .NET Framework in a -- and if I read this word much more I'm going to scream -- seamless way.
For years I've poked at redoing my blog app, through ASP.NET 2.0, Dynamic Data, and then MVC. This time, I might really do it.[2] :-)
Anyway, we did something a little different for the documentation this time around as well. More about that next time.
[categories]
aspnet
|
posted at
05:52 PM
|
trackback
|
|
link
 A diversion. As I will touch on later, there's a difference between a person who can write and a person whose job is writing. A programmer who writes the occasional blog entry is not (yet) a technical writer, who in contrast spends week after week documenting not just the interesting and cool things that are fun to write about, but also the seemingly endless APIs, the unsexy readme files, the installation instructions, and all the other stuff that users need, and who do this on relentless schedules. (As people sometimes say, "that's why they call it work").
Ok, writing. How do you assess writing skills, and specifically technical writing? If anyone's developed a foolproof way, I haven't heard of it.
What about writing samples? A good start, and indeed, a necessary condition, but not a sufficient one. It's hard to imagine a candidate with no writing samples at all getting far in the process. On the other hand, impressive writing samples are always nice, but it's never clear how much of the work actually is the candidate's and how much was contributed by (for example) editorial review. In this regard, blog entries are (IMO) actually good writing samples. If a good blog is added to a sample that shows experience writing API docs, I definitely sit up and take notice. (FWIW, I haven't seen this a lot.) A writing sample can also become an interesting point of drilldown, as I'll explain in a minute.
Writing test? This idea has always been bandied about (you'd never hire an editor without an editing test), but it's never really come to fruition, at least that I've seen. Decades ago I used to administer a writing test that consisted of listing a handful of SQL-like statements and the resulting output and asking the candidate to sketch out the documentation for this "language." However, that's a pretty intensive effort that we don't have the time for in our brisk process. (We might also have some constraints associated with having to administer the same test the same way each time, but I'm not sure about that.)
So we do a lot of our assessment via questions. If I indeed have the charter to investigate the candidate's writing skills (I don't always), during the interview, I ask some questions that are fairly broad, along these lines.- I see that you did some writing for [Product X]. What does that product do? (I just pick something off their resume.) To me this is a pretty simple test for writing ability. Can you describe something to me that I don't know about? Did you bother to establish what I might already know about it? Can you tune your description to my knowledge and interest? Like that.
- You're given a 1.0 product to work on, and six weeks to do it. What do you do? Here I'm looking for thoughts on how to plan, how to prioritize, how to use available resources creatively, what to produce, whether they consider non-writing avenues (e.g. video), how to think beyond the next deadline, maybe how to negotiate with other teams, etc. If they've been in the business for a while, they've faced this one, so I'm all ears about how it went and maybe what they learned.
- What's your experience with editors? Tell me about a time when you and the editor disagreed about something. Obviously, I am leery of people who either have not been edited or who are grumbly about editing. (To be fair, I know writers who are justified in their skepticism about technical editors. Still, a response like "My editor was an idiot, so I just ignored them" is, as you can imagine, not encouraging.)
- How do you know if you've succeeded? I'm looking for some insights into things like getting reviews, checking customer feedback (or otherwise interacting with customers) — whatever they might think of. This might also tell me something about whether the writer is actively interested in doing a good job or has a "it's published, I'm done" attitude.
- What skills do you think make a good technical writer? If "good grammar and spelling" seems to be a focus, I start to have my doubts.
- What's the best kind of documentation? The winner here is "the best doc is doc that's not needed," but I'm interested to hear whether they've thought about the purpose of documentation, how it's used, by whom, etc. For our context, I also like to hear about code samples and other programmer-centric thinking.
- If you could do any job tomorrow, what would it be? This seems like a transparent snare, but an open tech-writer position can attract people who think they might want to look into this writing business because they're tired of what they're doing and hey, they wrote a whitepaper once and that was fun.[1]
If I have a decent writing sample, I might also ask some specifics about the sample -- what was the thinking, why this approach, what were some of the issues, how was it received, etc. I also hope to get some sense of whether they were using a style guide/sheet and had a formal editing and publishing process. I'll also ask what tools they've used, not because I care specifically about those tools, but because I am interested if they've worked in a professional environment and how they feel about that.
If they've provided multiple samples, I might ask which is their favorite and why. What I'm hoping to elicit here is some enthusiasm and pride for their work.
Hmm. I see that these are questions about writing skills in a very broad definition. But that's what we're after.
There's a million more questions (I have a 6-page document full of them), but the specifics aren't really that important. The important point is that what I probe for is to determine whether the person sitting across from me is, in fact, a writer. As Chris Sells once said, "Don't prepare. Be yourself. If you're not a fit for MS, no amount of preparation in the days before an interview will help." (Read his whole interview.)
There are times when it's obvious, either pro or con. There are other times when it's just not clear. (An odd case that I've learned to trust is the person who seems to be -- in fact, is -- a good writer but is not driven to it compulsively, and would not write except as a job.)
I know from experience that it's quite a bit harder to find a really good programmer/writer than I would have imagined in my younger days. As you might expect (?), I've worked with folks where the programming skills definitely were the stronger half of the binomial. That, I suppose, is where my job comes into it. :-)
[categories]
work, writing
|
posted at
11:21 PM
|
trackback
|
|
link
Before we get any further, I need to say this very clearly: what you read here does not necessarily reflect company policy, or our team's philosophy, or any specific or actual interview questions. What you're getting here are my personal thoughts about the interview process for technical writers. Ok, with that out of the way ...  If you interview in our group, you're looking for a "programmer/writer" position, meaning that you're a writer and you can program. So the interview process has to address both the technical and the writing.
There’s some difference in how this is handled for full-time positions vs. contracting positions. For contractors, the idea is that we’re looking for someone with a specific set of skills to solve a short-term problem. As such, the interview process focuses on drilling down into those skills and what the candidate can do to help with that particular problem. For a full-time position, the idea is that you’re hiring not just for now, but for 10 years from now. FTEs are an investment, so you’re looking as much for aptitude and what the company calls "core competencies" as you are for those specific skills. The FTE interview cycle is necessarily more elaborate and wider in scope.
I should also note that it’s an ongoing discussion about which is more important, the technical or the writing. This is sometimes articulated as "Is it easier to teach a programmer to write or to teach a writer to program?" I work in the most programmer-centric division of a programmer-centric company, so my sense is that there's a bias in favor of highly technical candidates. Of course, the ideal candidate can do both, and we have plenty of people (some whose job description does not include "writer") who have both technical and writer chops. But if you're faced with two good candidates, one a long-time programmer with a little writing experience, and one a long-time writer with a little programming experience, which do you choose? Answer: I don't know. Or more like: it depends – on the position, on the candidate, and on the team.
All that said, whether the position is for a contracting job or a full-time position, there’s still a technical screen early on to get an idea of the technical end of your capabilities. I don't usually participate in technical screens, so I’m not really an expert on that side interview process. But in general, our group documents web technologies, so we're interested in what you know about that, and about working with the .NET platform specifically.
So this is the flavor of the sort of thing that we might think about asking you, which are all questions I'm just making up for the purposes of illustration:- How do you get the value of a field that's been submitted in a form?
- Describe what's "cascading" about CSS.
- What are some options for maintaining state between pages?
- What's a cross-site scripting exploit and how can you protect against it?
- What's AJAX and what's it good for?
What these questions get at is not a specific set of knowledge about how ASP.NET works so much as a candidate's experience with web programming. If you've done server-based programming for the web, these are things you've presumably encountered, if not necessarily become an expert at. (Have I mentioned that these are not necessarily specific questions that might come up?) If you don't know any of these things (or whatever kind of equivalent questions are actually asked), one might wonder whether you're a good candidate for writing about web technologies.
There might also be a slew of ASP.NET-specific questions as well, again depending on what exactly the interview is for and what the candidate seems to know, perhaps along the lines of What's view state? or What are your options for displaying data on an .aspx page? or -- heh-heh -- In an ASP.NET app, how do you establish read-write permissions for SQL Server when the database isn't on the same box as the web server? Heh-heh.[1]
There are also likely questions to determine how much a candidate understands about .NET and about object-oriented programming, which might be along the lines of, dunno, How do you create a read-only property? or What's the difference between an interface and an abstract class? Questions that, again, are really more about familiarity than about super-expertise.
Ok, so that's technical, which I will say again that I am not generally involved with. Whenever the opportunity arises, I do try to get involved with assessing the other half of technical writing, namely writing. More on that next time.
[categories]
writing
|
posted at
01:05 PM
|
trackback
|
|
link
The idea is appealing in a number of ways, among them:- The developer developed the code, so they understand it best.
- When an API changes, it's easier to change comments in source code than to track down and update some document somewhere.
- That's one less technical writer you need to hire.
In my experience, tho, there's little guarantee that you'll end up with decent documentation. Here's a list of reasons why:- Most developers would rather code then write. This is all the more true, I think, when the writing consists of revising existing docs (comments) for an update.
- Is it cost-effective to have developers writing documentation at coder rates? Maybe, maybe not.
- Many developers are not strong writers, mechanically speaking -- not just spelling and grammar, but being able to articulate what it is they need to say.[1]
- Many developers (or many that I work with, anyway) are not native speakers of English (assuming the target documentation is supposed to be in English).
- Developers might not understand what the reader actually needs to know -- after all, it's generally obvious to the developer.
- Developers are often focused on details like syntax or parameter definitions, not on the reasons why a piece of code exists or why the user might need to use it.
- Developers often have a hard time grasping that the reader does not have the same knowledge that the developer does (cf The Rise and Fall of Homo Logicus).
You occasionally encounter an attitude among some developers that they have to write the docs because no technical writer could possibly understand their code. This is horse poop.
As a side issue, there's also the larger issue that API docs is to understanding a product as a dictionary is to understanding a language. Raymond Chen:There's more to documentation than dry function descriptions, people! The function description is a reference; you go there when you already know what's going on and you just need to fine-tune a detail. The real learning happens in the overviews and articles. If you want to learn how to operate your radio, you don't read the schematic first. I should add that I don't think that XML code comments are not useful. They can be part of the info (among many sources) that a tech writer uses to create docs. In individual instances where the various issues raised above are not issues, using developer-generated documentation for APIs (when used with additional material) will work just fine.
A final note: XML code comments can become the initial drafts that are fed into a community-supported doc effort. That can work. A limitation here, tho, is that improvements made by the community tend not to go back into the doc comments.
[categories]
writing
|
|
|
|
