Closed Bug 900106 Opened 12 years ago Closed 12 years ago

Ship "How to create a great Teaching Kit" documentation to SUMO

Categories

(Webmaker Graveyard :: General, defect)

Product:
Webmaker Graveyard
Component:
General
Type:
defect
Priority:
Not set
Severity:
normal

Tracking

(Not tracked)

Status:
RESOLVED FIXED

People

(Reporter: matt, Unassigned)

Details

* Let's test this. * Laura: Jacob has been prototyping ways we can use SUMO for our user-facing documentation * since we're working on documentation for stuff like "how to create great teaching kits," thought maybe we could test posting it there * Jacob: can you help us get started? What do we do first?
Hey Matt - adding Michael Verdi to the bug, he's the content manager for SUMO and can get you set up. 1) Create an account on SUMO - https://support.mozilla.org - and tell Verdi your username 2) Verdi will upgrade your account to reviewer status, so you can submit drafts for review, make changes in the review panel, and bring them live when ready. 3) Then follow the instructions here to create a new article - https://support.mozilla.org/en-US/kb/create-new-knowledge-base-article with some exceptions, since there's no "Webmaker" product on SUMO yet ** choose the "administration" category ** This will prevent the article from going live. For everything else you can pick Firefox and just select the first Firefox topic. Once the proper Webmaker topics are created, you can re-check the boxes appropriately. Also - when you submit for review, make a note in the submission comment that it's a draft for Webmaker so the Firefox reviewers don't get confused. I wrote this in mine "THIS IS A DRAFT article for the new Webmaker product on SUMO. Please don't touch, it will be moved soon once the Webmaker product is ready :)" Verdi can help you with anything, he's Verdi on #SUMO in IRC
Hi Michael! My username is LauraHilliger – can you make me a reviewer? Working on the documentation this week :) Thanks!
Flags: needinfo?(mverdi)
Hi Laura, I added you to the reviewers group. Let me know if I can help and check out our knowledge base documentation here - https://support.mozilla.org/en-US/kb/improve-knowledge-base and reviewer guidelines here - https://support.mozilla.org/en-US/kb/article-review-guidelines Thanks, Michael
Flags: needinfo?(mverdi)
SUMO is the cats meow! @Jacob & Matt - would love to talk to you about Webmaker documentation structure. It seems that there IS a webmaker product (must have been recently resolved, and I think we should discuss what the subcomponents should be (e.g. I think events and mentors being lumped together is problematic). Also, I'm not sure how to categorize, or change category pages (i.e. my new article isn't on the "events and mentor help" overview) I seems like there's no need for us to continue using the Mozilla Wiki when we're creating user facing documentation, especially since SUMO has such amazing features, is pretty and has localization infrastructure in place. Or am I missing something in my SUMO excitement? Here's the doc I made. @Matt - I'm sure you have ideas to clean it up a bit? https://support.mozilla.org/en-US/kb/top-tips-creating-great-teaching-kits
* SUMO is indeed where we want to house our user-facing documentation * We're going to continue use this wiki http://wiki.mozilla.org/webmaker/documentation/ for a) more technical documentation. or stuff we don't think general users need. b) staging documentation. writing draft documentation / getting it to a point where it's ready for SUMO. @ Jacob: we need to socialize this more / let staff and community know that we're actively using SUMO. and how they should be contributing to it. Can you do that in next community call?
@ Laura: also: before we ship to SUMO, can I take a pass on the copy?
Hey Matt & Laura Laura: * happy to walk you through SUMO in more detail and have a discussion on topics & possibly sub-topics, perhaps on today's staff call, or at another time just you and I. * Basically Verdi can create topics / sub-topics and they will show up as check boxes when you compose or edit an article. They are easy to administer, and he's happy to help. * I'm not sure why your article isn't showing up in the "Events and Mentors" topic. Usually there's a 15 minute delay or so, but it should be there by now…might have to see what's up in #SUMO channel on IRC * I made a revision to your article to get rid of the keywords. It's not your fault that you put them there, but there's a SUMO policy to only use keywords as a last resort, as they can often hurt search. See more here - https://support.mozilla.org/en-US/kb/when-and-how-to-use-keywords Matt: * I agree on point A that the wiki should be for more technical documentation, or stuff we don't think general users need. * Regarding point B, if possible, we should avoid staging things on the Wiki because you can just as easily stage things on SUMO and it has all the features of a wiki. So it would be better to get revisions and discussions happening in that space since there's a community there already and then you don't have to worry about wiki rot, where things get obsolete because someone forgot to go back and revise/delete an old draft that they used for staging. * Also, the wiki is still good when you need a quick and easy web page without having to code something or request dev help, as long as you set some sort of alarm to go back and update the damn thing :)
+1 Jacob - I don't see the point in writing in etherpad or text editor, shipping to wiki and then SUMO. Wiki as second step seems redundant. @Matt - feel free to revise that doc and then I can do review, and vice versa. Want to set up a co-etherpad session to work out IA for our documentation. Then we can ask Verdi once for a structure and hopefully not have to edit that every other day.
* Jacob: sure. let's do Webmaker documentation however you want. just please a) DOCUMENT the process you want people to follow for creating and sharing documentation. (can you write a blog post or paste a SUMO link or something? what's the criteria for what to post where?) b) make sure it's simple enough for *everyone* to use, and c) communicate it to everyone.
I LOVE SUMO. I FREAKING LOVE IT. @Matt - these are ready for you: https://support.mozilla.org/en-US/kb/top-tips-creating-great-teaching-kits (ErikaD already did copy on this one) https://support.mozilla.org/en-US/kb/pro-tips-webmaker-teaching-kits (not on this one though) @Jacob - I still can't get things showing up under Events/Mentors, and I can't figure out how to have related articles or anything snazzy. It's like every single article is stand alone. Let me know when you have your proposal/documentation of SUMO for Webmaker in any sort of pre-to-be-used state :)
@Laura: I filed bug #905188 and fixed your issue with the "Tips for a successful event" article. The problem was the category chosen in the description field. Apparently it has to be either "How to" or "Troubleshooting" in order to file correctly. The other categories are for internal purposes. ------ I started a Wiki page to explain protocol and best practices for all of Webmaker support here - https://wiki.mozilla.org/Webmaker/Support It's still in the works. I'll probably also start another page for SUMO itself that has a styleguide, quirks, etc. Once the work week ends I'll get back into updating documentation. ------ Related articles are chosen by an automatic algorithm. Not sure how it works, though I've noticed it's been smarter lately. Still, would be nice to have control over it, maybe we can file a ticket with them here - https://bugzilla.mozilla.org/enter_bug.cgi?product=support.mozilla.org ------ I believe Verdi said that "Hot Topics" can be curated, but I need to follow up with him on how to do that. He's usually active on IRC in #SUMO (though haven't seen him there in the last few days, might be on PTO)
(In reply to Jacob [:Jacob] from comment #11) > > It's still in the works. I'll probably also start another page for SUMO > itself that has a styleguide, quirks, etc. Just so you know - we have sumo kb documentation here - https://support.mozilla.org/en-US/kb/improve-knowledge-base The bottom of that article links to everything including https://support.mozilla.org/en-US/kb/how-to-write-knowledge-base-articles which is the style guide. It would be great if you could submit improvements to those rather than creating new ones if that would work for you.
* These look good to me! Going to mark this one as fixed. SUMO is awesome.
Status: NEW → RESOLVED
Closed: 12 years ago
Resolution: --- → FIXED
Component: Community → General
You need to log in before you can comment on or make changes to this bug.