How to create documentation that people will read?
-
make them PDF, and provide a PDX (PDF index) with them, so that people can make search on all those documents directly...
[VisualCalc][Binary Guide][CommDialogs] | [Forums Guidelines]
Isn't it very heavy? Authoring PDF document AFAIK is not as simple as updating Wiki pages.
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Make a new page for it.everyone can read it online and it's easy to update. :-D
Undeniable:More information,more abilities,more energies,more time! http://www.blogjava.net/tidelgl
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Last week we started a series of meeting to address this very topic. We plan to create a database containing all of the documentation for the system. It will be accessed and administered through a web front end. For printability, reports will be created to show the same data in the same format as is seen on the web. (Edit) The web application will provide the ability to provide key words that can be searched on. The content of the document itself is not searchable, but, that could change. We recently revamped our internal Intranet to use a fully database driven menued structure; entries on the Intranet can have key words that are searched. One of the developers created an HTML editor within the Intranet that can be used to edit content directly, including having embedded pictures. (End Edit) Tim
modified on Thursday, September 4, 2008 9:09 AM
-
Last week we started a series of meeting to address this very topic. We plan to create a database containing all of the documentation for the system. It will be accessed and administered through a web front end. For printability, reports will be created to show the same data in the same format as is seen on the web. (Edit) The web application will provide the ability to provide key words that can be searched on. The content of the document itself is not searchable, but, that could change. We recently revamped our internal Intranet to use a fully database driven menued structure; entries on the Intranet can have key words that are searched. One of the developers created an HTML editor within the Intranet that can be used to edit content directly, including having embedded pictures. (End Edit) Tim
modified on Thursday, September 4, 2008 9:09 AM
And what about search engine?
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Liberally sprinkle pictures of fast cars and celebrities throughout. Seems to work for most magazines, why not start a new trend! Also, declutter the techno speak, use straightforward terms and keep points short and snappy. Remember that not everyone who will read it is a tech-head!
------------------------------------ Hungrþverrir lét herjat hríðar gagls á Skíði (the hunger battle-birds were filled in Skye with blood of foemen killed)
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
I believe for sharepoint (wiki template) there's a tool that allows you to take it 'off line'... sort of like a compiled help I guess (never done it myself) it's also searchable. In fact most of PM is moving towards sharepoint because it centralizes everything, issue tracking a knowledge base (wiki), shared documents, etc ...
V.
Stop smoking so you can: Enjoy longer the money you save. Moviereview Archive -
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Forget all of that; the only way to make a user read documentation is to implement hgtthoip, and even then you shouldn't expect more than a 2-3% success rate. * Hold a Gun To Their Head Over IP.
Today's lesson is brought to you by the word "niggardly". Remember kids, don't attribute to racism what can be explained by Scandinavian language roots. -- Robert Royall
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Which is why the source as documentation movement is so strong. You want a developer to read a document, put it in his or her project so they don't have to leave the IDE to look for it, update the document through source control. IMHO, there is nothing worse than several sources for documents. Everyone just states mater of factly, its on our sharepoint site. Or why didn't you see the change we updated it? As if I can check 15 sharepoint sites daily for updates. Also, mass mails for updates don't work either. Technical people only need to see relevant updates. I delete all mass mails without reading ... anecdotal evidence suggest in 10 years I have never gotten an important one.
Need software developed? Offering C# development all over the United States, ERL GLOBAL, Inc is the only call you will have to make.
Happiness in intelligent people is the rarest thing I know. -- Ernest Hemingway
Most of this sig is for Google, not ego. -
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
I like .CHM files myself. For developer documentation maybe XML summary etc tags that work with intellisense.
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
If there isn't a book I can sit on the pot and study, there's no documentation, period. Online help in any form is unusable for anything but reference lookups after the user has mastered the basics.
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Isn't it more important to ask how you can create documentation that people will want to read? All these other goals are fine, but if you don't have documentation that people want to read then it's completely pointless.
Deja View - the feeling that you've seen this post before.
-
Hello, We are trying to change an approach to our documentation for developers. We have hundreds of Word documents describing parts of the system, but they are hard to browse, hard to quickly find the information you need, and most of them are "write once" document, i.e. they quickly get outdated. On the other hand, we have a small Wiki site that seems to be often accessed and updated. But it would be too easy to decide in favour of Wiki since we identified the following requirements to our documentation: - Printable - Easy to author/update - Easy to navigate - Searchable - Portable (e.g. you should be able to take the documents with you) So far we are trying to choose between Wiki and set of Word documents (with hyperlinks). In case you have experience with a documentation framework that satisfies the requirements above or you know the tools that can solve these requirements, I'll be greatful to know. Thanks in advance
Вагиф Абилов MCP (Visual C++) Oslo, Norway If you're in a war, instead of throwing a hand grenade at the enemy, throw one of those small pumpkins. Maybe it'll make everyone think how stupid war is, and while they are thinking, you can throw a real grenade at them. Jack Handey.
Hi Vagif, imho the "right strategy" is to work "backwards" from what your users require and want using a "scenario" driven approach. Scan, study, the user feedback you have now (including "praises" as well as "complaints"); ask some of your most frequent "support users" for feedback, and for ideas about what type of documentation they need. Consider and compare the needs of new users (FAQ ? orientation ? basic how-to ? getting started ? source-code examples ?) with needs of those who are competent daily users of your application or system. imho after evaluating users' needs, then make the techncal choices about delivery vehicles and what tools you need to create and manage the documentation required. best, Bill
"The greater the social and cultural distances between people, the more magical the light that can spring from their contact." Milan Kundera in Testaments Trahis