First, the SMF Documentation Team would like to thank you for offering to help us improve the SMF Online Manual. We appreciate your willingness to give of your time to do so.
There are a few things you should read before you begin. Hopefully, you will find the following information helpful as you embark on the glorious and exciting journey that is documentation.
If you have any questions regarding the following information, please don't hesitate to contact a Documentation Team member. We're here to help you.What exactly are the Doc Helpers?
The Doc Helpers is a group of people who volunteer their time to work on the SMF Online Manual. Sometimes, they correct documents or rewrite them. Sometimes, they update documents or produce new ones to fill in missing documentation. Ultimately, the Doc Helpers help the Documentation Writers keep the manual up to date and error free.What can I do?
The answer is "pretty much anything."
Here are a few ideas to get you started.
- Proofread & Correct a Document
- Update a Document
- Rewrite a Document
- Write a New Document
- Point Out Dead Links
- Assist Other Doc Helpers
If you want to do something that's not on the list, feel free to run your idea past the Documentation Team by posting a new topic
. The first step to working on anything, though, is visiting the Online Manual
and reading through some of the documents.Okay, I know what I want to do. Now what?
The first thing you need to do is let the Documentation Team know what it is. You may do this by posting a new topic
in the Doc Helpers board
. Please tag the beginning of your topic with one of the following tags and include a link to the document in your post (if possible).Tags
- [correction] - Correct typos, grammar, dead links, or any other small issues.
- [update] - Update a document with missing or incorrect information (not a simple correction).
- [rewrite] - Completely rewrite a document from scratch.
- [new] - Suggest a new document for inclusion into the OM.
Large changes to documentation are not made immediately. This would create too much confusion for people viewing the Online Manual. Instead, post a topic
for each document that you want to rewrite or create (with the appropriate tag). It should be posted in the Doc Helpers board
. Once you request a document, wait for a Doc Team member to approve your request. Do not just post a revision.
Once approved, you can post your revisions as replies to the topic. The Documentation Team will review all of your new topics, make suggestions for improvement, accept, or possibly decline your changes. Accepted changes will eventually be moved to live documents (yay!).Corrections and Dead Links
If you are not comfortable creating or rewriting entire documents and would rather fix smaller errors in existing documents, you may also do that. Just start a new topic
in the Doc Helpers board
with the appropriate tag. It's just as important to the quality of the documentation that we eliminate those unnecessary errors. New Doc Helpers may want to start here before moving on to larger assignments.Do I need to follow any guidelines?
The answer is a loud and resounding, "Yes!
" Documentation Guidelines
Check out our Documentation Guidelines
for information about word choice, styling, and hyperlinking in your documents. In order to create a consistent, professional set of documents, it is extremely important
that the guidelines provided in the Documentation Guidelines be followed.Revisions
If you choose to post the original text of the document in your request topic, surround it with [quote][/quote] tags. This will separate the document from the rest of the post and make it easier to see. Once a Doc Team member gives you the okay to work on that doc, you can start making revisions. Your revisions to the document should be posted as replies to your topic (do not edit previous posts
) and surrounded with [quote][/quote] tags, as well.What if I get stuck?
The Documentation Team works with the Doc Helpers to make sure that everyone is happy and progressing at their own speed. Feel free to ask questions, point out issues, and make suggestions in the Doc Helpers board
. If you'd like to talk to a Documentation Team member one-on-one, you may contact them via private message.
Alternatively, Doc Helpers are encouraged to work with each other and help each other out if possible. You have the opportunity both to teach and learn from the rest of the Doc Helpers. Take advantage of it!Do you have any advice?
As a matter of fact, we do! It's good advice, too.
Much of it comes from former Doc Helpers who are now part of the Documentation Team.
- The Documentation Team is in no way obligated to use your documents, corrections, or any other work you may complete. Don't worry, though. Sometimes, our stuff isn't used, either.
- Take as much time as you need. There are no deadlines. We want quality documents, not documents created quickly (which are generally of lower quality).
- Do your research, double check, and triple check.
- If someone corrects or comments on your document, do not take it personally. Accept it as constructive criticism and learn from it. No one is perfect.
- Learn the guidelines for documentation (available in the Documentation Guidelines). Many headaches can be avoided simply by following the guidelines closely.
- If you do not plan to do any work, then please reconsider your Doc Helpers membership. We need people who are ready and willing to help out and learn to write for the Online Manual.
- Stick around long enough, work hard enough, and you may just find yourself with a gold badge as the newest member of the Documentation Team.