I’d be interested in what parts you don’t agree with Matt. I’ll happily admit I’ve been less than impressed with the WordPress documentation (and yes I MAY yet offer my time and expertise to improve it!).
To anticipate Matt, here are some of the points I disagree with, after spending a few months on some documentation, both on the software’s official site and a separate, site for the company planning a hosted service around the software:
Point #3: the source code *can* be *part* of the documentation, if the functions and variables are properly documented inside the code. They are useful for developers who see a function and wonder where it’s referenced, etc. Developers are users too.
Point #5: just make a separate stylesheet for the printed version of the documentation. Somehow I don’t think people are likely to download a 100 page document, then print that out. Specific pages, however, absolutely, but you don’t even have to make a separate download/page for it.
Point #6: totally disagree. The documentation absolutely *should* include markup, to illustrate or emphasize or link (but the links should be descriptive so that if one were to print it out, they wouldn’t see “this link” or “here”, but rather a short phrase that flows nicely in an actual sentence). Maybe not embedded comments, but at least comments should generally be allowed (by the way, this somewhat conflicts with his point #8), so that actual users can make corrections or elaborations or questions.
Some things I would add: if it’s not searchable (by search engines or on the site itself), it doesn’t exist. The cleaner the URLs, the better (makes it easier to refer to documentation in email and IM support). Also, licensing: a Creative Commons license can encourage people write better docs than you, and when they do, let you easily include then back in the original.
Richard – I agree on your point about.. er.. point 3.
Point 6 – Markup – I think should have been clarified. I think it depends on WHO the documentation is aimed at. Granted most WordPress users have to have a level of technical understanding but I think any markup is best “hidden” further down the information flow than any task information (for example).
Point 6 – Comments – absolutely not. It may be fine for a Wiki/collaborative site but end user documentation should be clear and unambiguous at all times. You can’t have that if you have other user comments in there. I would suggest that they could be included at the end of chapters or sections but not in the main flow. Too confusing.
Anyway, as a Technical Author I was interested in this (obviously). Question: how many technical authors are helping out with the WordPress documentation?
Matt: +1 though I don’t get the impression that commenters’ corrections (or better usage examples) make their way into the main text. Usually doesn’t matter. There are a lot of great little code snippets that further explain a function or document little weird implementation issues that may not be obvious from the ‘official’ text.
I work for a documentation project that has really great contributions from the comments as well as questions prodding the writers to update the main text to reflect the latest version of the software. Since the documentation writing is fairly distributed (not distributed around the Internet, but rather among many writers), it can be difficult to contact the writers or site maintainers directly. So what happens? They add a comment. Sometimes it gets reflected in the main text, and sometimes not, since it ‘merely’ elaborates on the main text. That’s why I don’t mind it if comments are on a separate–but still public!–page from the main text. That way, if incorrect information is in the comments, then it doesn’t look ‘official’, but still allows for elaborations from people enthusiastic about using the software.
Anyway, off the soapbox for a minute (then quickly back on): what do you mean by markup? Do you mean links? Or styling markup, like bold, italic, etc.? The latter is useful, I think, if you stick to a style when documenting terminology related to the software. Task information, if it’s a step-by-step explanation, then yes, there is such a thing as too many links. There is definitely such a thing as too many links, but why make someone scroll down if the answer on how to follow, say, a subset of the instructions, is a click away?
The assumptions I’m making, of course, are that the documentation is online. The most interesting part about software documentation these days is that if the developers or their documentation-writing colleagues don’t write it, somebody will post a HOWTO on their weblog or wiki. Many things I wanted to implement on””to take a piece of (not open source, but close enough for our purposes) software at random””Movable Type were already documented by people not employed by the company who made the software. And if it wasn’t written up, I tried to figure it out myself and then wrote it up myself. (Embarrassingly, I found my own documentation once when I searched for how to do something.) We can honestly disagree as to whether documentation with anonymous comments enabled is a bad way to document something (not just software, mind you), but effectively, the people who actually use it and figure it out and love sharing how they did it are doing it that way.
Richard you’ve hit on the key “issue” I have with the WordPress documentation. Where is it? From my – still learning WordPress, still new – eyes there is a LOT of good stuff. The problem is finding it.
Agree that, your php.net example is valid but I’d probably LINK to that stuff not include in on the same page, no matter how obvious the split. Examples are always the easiest way to learn. The majority of users won’t actually READ the page, they’ll skip to an example bit of code. If that example is in a comment and isn’t correct… well.. can.. worms.. .everywhere. It’s a no-no in commercial software documentation, I don’t see how it would benefit an Open Source project either.
Ohh and I’m a Technical Author by trade, hence the morbid interest in this topic. I’m currently helping out another web service by starting a Wiki and redesigning the information flow of the main website – from installation to advanced usage you can stagger the information accordingly. Of the few people I know directly that are using and have just switched to WordPress the comments are always: I love it, it’s great but I can’t find how to do x, y and z.
Of course I should put up and shut up, right? Well I will. Once I get this other stuff out of the road.
Gordon,
The road to nowhere is paved with good intentions. As part of the documentation team, I’ve seen ten times as many complaints as I’ve seen volunteers to help. We document people must have masochistic tendancies as we take a lot of criticism and virtually never see any gratitude. I’d love to see some expert help and guidance, but until we actually get some, we will simply do the best that we can as volunteers. Until then, statements to the effect that someone “may” help are simply vapourware.
I’d be interested in what parts you don’t agree with Matt. I’ll happily admit I’ve been less than impressed with the WordPress documentation (and yes I MAY yet offer my time and expertise to improve it!).
To anticipate Matt, here are some of the points I disagree with, after spending a few months on some documentation, both on the software’s official site and a separate, site for the company planning a hosted service around the software:
Point #3: the source code *can* be *part* of the documentation, if the functions and variables are properly documented inside the code. They are useful for developers who see a function and wonder where it’s referenced, etc. Developers are users too.
Point #5: just make a separate stylesheet for the printed version of the documentation. Somehow I don’t think people are likely to download a 100 page document, then print that out. Specific pages, however, absolutely, but you don’t even have to make a separate download/page for it.
Point #6: totally disagree. The documentation absolutely *should* include markup, to illustrate or emphasize or link (but the links should be descriptive so that if one were to print it out, they wouldn’t see “this link” or “here”, but rather a short phrase that flows nicely in an actual sentence). Maybe not embedded comments, but at least comments should generally be allowed (by the way, this somewhat conflicts with his point #8), so that actual users can make corrections or elaborations or questions.
Some things I would add: if it’s not searchable (by search engines or on the site itself), it doesn’t exist. The cleaner the URLs, the better (makes it easier to refer to documentation in email and IM support). Also, licensing: a Creative Commons license can encourage people write better docs than you, and when they do, let you easily include then back in the original.
Richard – I agree on your point about.. er.. point 3.
Point 6 – Markup – I think should have been clarified. I think it depends on WHO the documentation is aimed at. Granted most WordPress users have to have a level of technical understanding but I think any markup is best “hidden” further down the information flow than any task information (for example).
Point 6 – Comments – absolutely not. It may be fine for a Wiki/collaborative site but end user documentation should be clear and unambiguous at all times. You can’t have that if you have other user comments in there. I would suggest that they could be included at the end of chapters or sections but not in the main flow. Too confusing.
Anyway, as a Technical Author I was interested in this (obviously). Question: how many technical authors are helping out with the WordPress documentation?
Gordon, just like with development, we’re all amateurs.
In the past I’ve found the comments on the php.net documentation to be the most useful part.
Matt: +1 though I don’t get the impression that commenters’ corrections (or better usage examples) make their way into the main text. Usually doesn’t matter. There are a lot of great little code snippets that further explain a function or document little weird implementation issues that may not be obvious from the ‘official’ text.
I work for a documentation project that has really great contributions from the comments as well as questions prodding the writers to update the main text to reflect the latest version of the software. Since the documentation writing is fairly distributed (not distributed around the Internet, but rather among many writers), it can be difficult to contact the writers or site maintainers directly. So what happens? They add a comment. Sometimes it gets reflected in the main text, and sometimes not, since it ‘merely’ elaborates on the main text. That’s why I don’t mind it if comments are on a separate–but still public!–page from the main text. That way, if incorrect information is in the comments, then it doesn’t look ‘official’, but still allows for elaborations from people enthusiastic about using the software.
Anyway, off the soapbox for a minute (then quickly back on): what do you mean by markup? Do you mean links? Or styling markup, like bold, italic, etc.? The latter is useful, I think, if you stick to a style when documenting terminology related to the software. Task information, if it’s a step-by-step explanation, then yes, there is such a thing as too many links. There is definitely such a thing as too many links, but why make someone scroll down if the answer on how to follow, say, a subset of the instructions, is a click away?
The assumptions I’m making, of course, are that the documentation is online. The most interesting part about software documentation these days is that if the developers or their documentation-writing colleagues don’t write it, somebody will post a HOWTO on their weblog or wiki. Many things I wanted to implement on””to take a piece of (not open source, but close enough for our purposes) software at random””Movable Type were already documented by people not employed by the company who made the software. And if it wasn’t written up, I tried to figure it out myself and then wrote it up myself. (Embarrassingly, I found my own documentation once when I searched for how to do something.) We can honestly disagree as to whether documentation with anonymous comments enabled is a bad way to document something (not just software, mind you), but effectively, the people who actually use it and figure it out and love sharing how they did it are doing it that way.
Richard you’ve hit on the key “issue” I have with the WordPress documentation. Where is it? From my – still learning WordPress, still new – eyes there is a LOT of good stuff. The problem is finding it.
Agree that, your php.net example is valid but I’d probably LINK to that stuff not include in on the same page, no matter how obvious the split. Examples are always the easiest way to learn. The majority of users won’t actually READ the page, they’ll skip to an example bit of code. If that example is in a comment and isn’t correct… well.. can.. worms.. .everywhere. It’s a no-no in commercial software documentation, I don’t see how it would benefit an Open Source project either.
Ohh and I’m a Technical Author by trade, hence the morbid interest in this topic. I’m currently helping out another web service by starting a Wiki and redesigning the information flow of the main website – from installation to advanced usage you can stagger the information accordingly. Of the few people I know directly that are using and have just switched to WordPress the comments are always: I love it, it’s great but I can’t find how to do x, y and z.
Of course I should put up and shut up, right? Well I will. Once I get this other stuff out of the road.
Gordon,
The road to nowhere is paved with good intentions. As part of the documentation team, I’ve seen ten times as many complaints as I’ve seen volunteers to help. We document people must have masochistic tendancies as we take a lot of criticism and virtually never see any gratitude. I’d love to see some expert help and guidance, but until we actually get some, we will simply do the best that we can as volunteers. Until then, statements to the effect that someone “may” help are simply vapourware.