sherlock-holmes
June 11th, 2006, 06:44 PM
Folks,
I am an avid user of the howtos section of this forum. They play an integral part in trouble shooting as well, apart from getting something to work the way we want. I am sure thousands of people here end up using many of those at one point of time...
So, I feel, it is important to have certain things to keep in mind while making one:
Please:
1. Use proper subject title. Begin the title by the word "HOWTO" or its case variants.
2. Include a short introduction of what the how to is about and what the application does for you. This has two significant effects. [a] easy to obtain using search since there are more words relevant to the idea, [b] to help a beginner to understand why he/she should use that how to. for eg, I dont know whats the significance of VNC server is and a short introduction (or a link following a brief intro) to that application at the beginning helps me a lot. this expands our knowledge base too.. even for the author...
3. Include all the commans inside a "------" environment, how ever trivial that command is. This helps to locate the specific commands easily and that way we dont miss any of them.
4. Number each heading according to their significance. It is not necessary to number each and every command or action.
5. Provide cross-references in the howto so that the reader can navigate efficiently. [the people in this forum are very professsional and appreciative that they appropriately acknowledege any information gathered from other sources.]
6. Provide links to related howto's or tricks at the end of the article. See how that helps in linking several useful information.
7. Use of color/ intalics etc appropriately. Too many colors should be avoided as much as possible. Use these amazing functionalities wisely.
8. Use the PHP tags for outputs/ copy-pasting long documents. Use this facility. This helps a reader to scroll inside the reading pane without tavelling a lot between the top and bottom.
9. Some suggestions on the headings, title, content etc....
(a) bold fonts for the headings.
(b) appropriate tags for commands, quotes, outputs (php) etc..
(c) edit the how to as necessary. Please do not forget to include the date where you edit the document. This avoids some confusion as you read thru several posts where there are some corrections mentioned and the debates and such..
Make a professional document wiki-ready :D
Please provide comments and suggestions in this thread. Thank you for your time.
I am an avid user of the howtos section of this forum. They play an integral part in trouble shooting as well, apart from getting something to work the way we want. I am sure thousands of people here end up using many of those at one point of time...
So, I feel, it is important to have certain things to keep in mind while making one:
Please:
1. Use proper subject title. Begin the title by the word "HOWTO" or its case variants.
2. Include a short introduction of what the how to is about and what the application does for you. This has two significant effects. [a] easy to obtain using search since there are more words relevant to the idea, [b] to help a beginner to understand why he/she should use that how to. for eg, I dont know whats the significance of VNC server is and a short introduction (or a link following a brief intro) to that application at the beginning helps me a lot. this expands our knowledge base too.. even for the author...
3. Include all the commans inside a "------" environment, how ever trivial that command is. This helps to locate the specific commands easily and that way we dont miss any of them.
4. Number each heading according to their significance. It is not necessary to number each and every command or action.
5. Provide cross-references in the howto so that the reader can navigate efficiently. [the people in this forum are very professsional and appreciative that they appropriately acknowledege any information gathered from other sources.]
6. Provide links to related howto's or tricks at the end of the article. See how that helps in linking several useful information.
7. Use of color/ intalics etc appropriately. Too many colors should be avoided as much as possible. Use these amazing functionalities wisely.
8. Use the PHP tags for outputs/ copy-pasting long documents. Use this facility. This helps a reader to scroll inside the reading pane without tavelling a lot between the top and bottom.
9. Some suggestions on the headings, title, content etc....
(a) bold fonts for the headings.
(b) appropriate tags for commands, quotes, outputs (php) etc..
(c) edit the how to as necessary. Please do not forget to include the date where you edit the document. This avoids some confusion as you read thru several posts where there are some corrections mentioned and the debates and such..
Make a professional document wiki-ready :D
Please provide comments and suggestions in this thread. Thank you for your time.