Guide to Writing a Guide
February 27, 2014 10:01 PM Subscribe
How would I go about setting up an online guidebook that's editable by different people with minimal effort?
I volunteered to help out people in my group set up an online guidebook that would be useful to mostly ourselves but maybe the public as well, like "A [our profession]'s guide to water treatment plants in American cities". We want a couple of general chapters but the main portion of guide is separate "chapters" being a different city with subsections about water sources, financial data, historical information, relevant laws, etc.
How would I go about setting up this guide that's editable by different people with minimal effort (ideally without accounts)? We want to make it public and allow outside people make small edits (so show an edit button somewhere), but I imagine it'll mostly be us making the major additions.
Do we want a wiki? I looked at a few but they all look so wiki-like and complicated to set up. The focus should be the content and not the wiki featuresOr a CMS? Or is there some other more lightweight service we can use? We would like it to have some branding as well. I have some technical know-how and have a computer science friend I can ask for some help (he can try a few things, but hasn't done this specifically before), but I want to be able to specify exactly what to set up in advance.
I volunteered to help out people in my group set up an online guidebook that would be useful to mostly ourselves but maybe the public as well, like "A [our profession]'s guide to water treatment plants in American cities". We want a couple of general chapters but the main portion of guide is separate "chapters" being a different city with subsections about water sources, financial data, historical information, relevant laws, etc.
How would I go about setting up this guide that's editable by different people with minimal effort (ideally without accounts)? We want to make it public and allow outside people make small edits (so show an edit button somewhere), but I imagine it'll mostly be us making the major additions.
Do we want a wiki? I looked at a few but they all look so wiki-like and complicated to set up. The focus should be the content and not the wiki featuresOr a CMS? Or is there some other more lightweight service we can use? We would like it to have some branding as well. I have some technical know-how and have a computer science friend I can ask for some help (he can try a few things, but hasn't done this specifically before), but I want to be able to specify exactly what to set up in advance.
Yeah, what you're describing is exactly the problem that wikis solve. You can make them look nicer if you have some time/effort/money to throw at the problem.
posted by third word on a random page at 10:55 PM on February 27, 2014
posted by third word on a random page at 10:55 PM on February 27, 2014
I'm not sure a wiki is a perfect solution; one nice thing about a "guide" in book form is that you can start at a known point, read an indicated number of pages (so you know how you're progressing and the task doesn't seem infinite), and come to the end knowing you've been given all the information the writers wanted to communicate.
Wikis seem good for randomly accessing, but not are not as organized like a text or guide so they're not as useful for comprehensive review. Also, giving one person the authority to organize the included information (as a book-like thing would allow) could also give the project more cohesion.
Is there some way that wikis can accomplish what I'm describing?
posted by amtho at 11:22 PM on February 27, 2014
Wikis seem good for randomly accessing, but not are not as organized like a text or guide so they're not as useful for comprehensive review. Also, giving one person the authority to organize the included information (as a book-like thing would allow) could also give the project more cohesion.
Is there some way that wikis can accomplish what I'm describing?
posted by amtho at 11:22 PM on February 27, 2014
Sourceforge is a pretty good way of finding out how this could work well - and why it often does not. Some software does have great wiki-based documentation but most does not. To make yours work I'd suggest:
1. Designating somebody as an owner and or editor: that would be you unless others are pressing for the position.
2. Seek out what you consider to be a clear guidebook for something in your domain. Then copy its general layout into sections. Keep the design fairly simple and unambitious: try to envisage the main questions that people would seek to have answered. If you can predict the top 10 then you are laughing.
3. At this point you need to make sure that sufficient detail is populated into the sections. If you have too little your audience will walk away. But once you have a certain amount they will be tempted to elaborate it themselves. That is what you want. This task could be best done be a small editorial group.
posted by rongorongo at 1:45 AM on February 28, 2014
1. Designating somebody as an owner and or editor: that would be you unless others are pressing for the position.
2. Seek out what you consider to be a clear guidebook for something in your domain. Then copy its general layout into sections. Keep the design fairly simple and unambitious: try to envisage the main questions that people would seek to have answered. If you can predict the top 10 then you are laughing.
3. At this point you need to make sure that sufficient detail is populated into the sections. If you have too little your audience will walk away. But once you have a certain amount they will be tempted to elaborate it themselves. That is what you want. This task could be best done be a small editorial group.
posted by rongorongo at 1:45 AM on February 28, 2014
I'd use a wiki and add an index, so the users will have a clear overview of what pages are there and how they're grouped together. This solves the problem that amtho outlines above: wikis can sometimes feel like the information is not structured.
posted by Too-Ticky at 2:25 AM on February 28, 2014
posted by Too-Ticky at 2:25 AM on February 28, 2014
This thread is closed to new comments.
posted by oceanjesse at 10:19 PM on February 27, 2014 [2 favorites]