Guides, Guides, Guides and a Guide on Guides!
Open in chat • 2 posts (analysis)
• Page 1 of 1
Guides, Guides, Guides and a Guide on Guides!
Brend » Sun Mar 04, 2012 4:11 pm
I've started work on the first few Guides!
Since we're a bit new to this whole 'writing' guides thing, I've scoured up an example of a set of guides that is both well written and light to read: http://help.github.com/. Unfortunately the content matter is rather technical, but the idea should be clear even if you don't follow the text.
Feel free to post links to other good examples (we'de rather have a few good and clean examples than a whole list of mediocre ones though).
I've gleaned some ideas from the github help:
Images
Make sure any images used are bordered. Our black theme has the tendency to blend any image into the site, but we want instructional images to stand out.
Center your images. Images should be in the middle of the page. In the wiki you can do this by adding a space before and after the image name (see Wiki Syntax: Images and Other Files).
Make sure the image contains clear highlights. Take a look at http://help.github.com/post-receive-hooks/, http://help.github.com/send-pull-requests/ or http://help.github.com/be-social/.
Don't hesitate to ask for help in getting the right pictures. A good picture tells more than a thousand words, so we might do well to get them right.
Guide Titles (and wiki names)
Make the guide title short and voice it like a call to action. For example, use "Create a Race" instead of "Race Creation Guide".
make the wikiname as short as can be done without losing meaning. For example, use guides:race instead of guides:race creation. We won't create another guide on races anyway, and if we do it will probably be on a more advanced (and therefore more specific) topic.
Reviews
While working on a guide, do not forget to tag it with:
And when you're done, leave the WIP and ask for a review on the forum. Two pairs of eyes see more than one, and it's so easy to overlook your own errors or your own ambiguous phrases.
Since we're a bit new to this whole 'writing' guides thing, I've scoured up an example of a set of guides that is both well written and light to read: http://help.github.com/. Unfortunately the content matter is rather technical, but the idea should be clear even if you don't follow the text.
Feel free to post links to other good examples (we'de rather have a few good and clean examples than a whole list of mediocre ones though).
I've gleaned some ideas from the github help:
Images
Make sure any images used are bordered. Our black theme has the tendency to blend any image into the site, but we want instructional images to stand out.
Center your images. Images should be in the middle of the page. In the wiki you can do this by adding a space before and after the image name (see Wiki Syntax: Images and Other Files).
Make sure the image contains clear highlights. Take a look at http://help.github.com/post-receive-hooks/, http://help.github.com/send-pull-requests/ or http://help.github.com/be-social/.
Don't hesitate to ask for help in getting the right pictures. A good picture tells more than a thousand words, so we might do well to get them right.
Guide Titles (and wiki names)
Make the guide title short and voice it like a call to action. For example, use "Create a Race" instead of "Race Creation Guide".
make the wikiname as short as can be done without losing meaning. For example, use guides:race instead of guides:race creation. We won't create another guide on races anyway, and if we do it will probably be on a more advanced (and therefore more specific) topic.
Reviews
While working on a guide, do not forget to tag it with:
- Code: Select all
---- dataentry [wip] !wip ----
Description_wiki: List of things that need to be fixed still (such as images etc.)
User_nspage: your username here
----
And when you're done, leave the WIP and ask for a review on the forum. Two pairs of eyes see more than one, and it's so easy to overlook your own errors or your own ambiguous phrases.
Brend » Sun Mar 04, 2012 6:10 pm
2 posts (analysis)
• Page 1 of 1