Comments on: How To Document Your Open-Source Tool

By: matt

matt — Sun, 06 Jan 2008 17:41:19 +0000

Interesting thoughts. I will take them in consideration! :) What would be interesting to discuss is "What documentation to write to help developers hack the software / build a developer community?" ; what kind of diagrams to draw, etc. even if it obviously is very dependent of what the software is doing...

Current score: 0 (to vote for this comment, please visit the site)

By: notImportant

notImportant — Sat, 26 Feb 2005 21:41:15 +0000

Hi there,Your font size is too small to read, even on a 800x600 screen.Regards...

Current score: 0 (to vote for this comment, please visit the site)

By: Ethan Reese-Whiting

Ethan Reese-Whiting — Thu, 17 Feb 2005 14:48:21 +0000

For a good breakdown of the document-creation process, check out "The Complete Idiot's Guide to Technical Writing." Sure, those little orange books may generate a natural aversion at first, but don't let the word "Idiot" in there fool you. They should really be retitled to "The Straightforward Guide to....." The tech writing guide discusses important concepts as consistency in wording, active voice, and text formatting.For example, if you are going to use "click" to mean move the cursor to a button and click the mouse button, use that each time in the document. Don't say "Click PRINT" in one area and "Select PRINT" in another if you're referring to the same action both times. Such redundancy is all but beaten out of us in high school English classes, but it is a blessing to the reader of technical documentation who may already be confused (hence why they're looking at the documentation). No need to muddy the waters up even more by changing terms on them.Also, be consistent with formatting such as text. If you use Times New Roman to write most of your document, but use Garamond when writing out code in the text, don't use Garamond later for headers or such.These are just a couple of the concepts that go into solid technical writing.

Current score: 0 (to vote for this comment, please visit the site)

By: Gordon

Gordon — Mon, 31 Jan 2005 16:47:07 +0000

Ohh yes. And DO give terminology and consistency some thought and try and drive things back into the software (hint: never use a verb to name a control).

Current score: 0 (to vote for this comment, please visit the site)

By: Gordon

Gordon — Mon, 31 Jan 2005 16:46:13 +0000

I think that, to kick start any sort of collaboration that is worthwhile, you do need a set of user docs initially. That way you at least have a common starting point instead of a melee of different topics and writing styles and ... oy!Not 100% sure I agree with Point 5. Very few users will download and print an entire manual, let alone read one. The option to print relevant topics is probably higher up the priority list for most people.Navigation and location are also key. Early on there is a habit for people to store information all over the place, it fast becomes a "you need to know where to look to find it" problem.I'd probably go as far as to suggest some sort of content specification is produced, listing all tasks and concepts that need to be covered - sometimes it can help focus the developers minds as well and you can weed out extraneous functionality.

Current score: 0 (to vote for this comment, please visit the site)

By: Jeffrey McManus

Jeffrey McManus — Mon, 31 Jan 2005 12:18:47 +0000

I didn't suggest that the project should somehow withhold its work because the docs aren't perfect, although I guess my post was a little light on concrete suggestions for actions to take to resolve these problems.Why limit documentation contributions to power users? Why not create a framework that makes it easy for anybody to contribute to the docs? My sense is that the tools for helping distributed workgroups create documentation isn't even close to the level of maturity of developer tools in general. Wikis, while nice, aren't it. Mailing lists and message boards, while vital, aren't it either.

Current score: 0 (to vote for this comment, please visit the site)

By: Mary

Mary — Mon, 31 Jan 2005 12:01:17 +0000

What about the power-users who complain that they want the product now and they'll wait on the documentation? I don't think its fair to hold it back for the benefit of the newbies who ignore the warnings that there's no/little documentation. Plus, then you get the benefit of those power-users contributing to the docs.Just a thought.

Current score: 0 (to vote for this comment, please visit the site)

By: TM

TM — Mon, 03 Jan 2005 05:54:41 +0000

Thanks for the suggestions. It's great to have someone else saying the same thing.

Current score: 0 (to vote for this comment, please visit the site)

By: TM

TM — Mon, 03 Jan 2005 05:54:40 +0000

Thanks for the suggestions. It's great to have someone else saying the same thing.

Current score: 0 (to vote for this comment, please visit the site)