Knowledge Base Process Change
Hello Vanilla Heroes!
We are excited to officially announce the addition of two new members to the Vanilla Forums team – Troy Kilpatrick and Kevin Higgins! As you may already be aware, Troy and Kevin are Higher Logics talented team of technical writers. They have already begun the enormous task of tackling our Knowledge Base with an eye to ensuring consistency in terminology, tone, and clarity. We are working with them to address the most-visited articles first and then will begin the process of transferring the outstanding issues from the GitHub documentation repo to them as well.
Troy and Kevin are working with key stakeholders across the Vanilla Teams to make sure our Knowledge Base accurately reflects the current state of our platform and as of today, the 4th of April, 2022, they will be the only people authorized to directly edit the Knowledge Base on the Success Community. *
However, this doesn’t mean we can no longer add articles, or make improvements, it simply adds some extra steps.
Steps for Proposing a New Article
- Write your article in a Word doc
- Send an email with the subject line, “Vanilla New {Subject} Article” (where subject is what the article covers, i.e. API, Theming, Pockets, etc.)
- Attach the Word doc to the email
- Attach any images you used in the article to the email
- In the body of the email, make a suggestion as to which category the article belongs
- Send the email to docs@higherlogic.com
- If further input is needed, you can expect to be contacted by Troy, Kevin, or Branwyn
Steps for Proposing an Edit to an Existing Article
- Highlight and copy the relevant section of the existing article and paste it into a Word doc
- Add the article link at the top of the document
- Under the Review menu in Word, select Track Changes
- Make and save your changes
- Send an email with the subject line, “Vanilla Article Edit”
- Attach the Word doc to the email
- Send the email to docs@higherlogic.com
- If further input is needed, you can expect to be contacted by Troy, Kevin, or Branwyn
Footnote: There are a few exceptions that will retain the current editing rights. This includes release notes, Internal Development, Developer Documentation and a few others.
Comments
-
This is awesome! ?
One tiny thing to consider (that maybe you know a workaround for?) is that if you write a KB article in google docs and copy paste to vanilla KB the images carry over, however, AFAIK, if you copy paste from word the images will not carry over. Maybe it's as simple as keeping your screenshots and inserting them again when it gets moved over, but figured I would mention this as it's caused me some frustrations when I didn't keep my screenshots haha.
4 -
I would echo what @shaunamcclemens has said here, I would recommend to add your screenshots as attachments with your email just incase things don't paste nicely.
So happy to hear we have some new team members to help tackle this project!
2 -
Troy and Kevin are already two of my new favourite people.
Is there any way we can propose edits, or point out mistakes without using Word? I feel it's a rather labourious way of pointing out small things. e.g. just send the email, with the info in the body?
2 -
@shaunamcclemens & @SheenaP Thanks for that tip! I added a bullet point to suggest attaching the images to the email itself
@Rhys Let me mull on that. There's a very specific reason we set things up this way. But I'm a relatively creative and resourceful person. I bet I can come up with a solution that meets you half way on this.
2 -
Sounds good...I think this is really adding more credence to the feature request to have a publishing workflow for KB articles
2 -
@BrendanParm 100%. If we had the ability to make revisions and require approval before they went live, that would be amazing.
1 -
an oft requested feature
1 -
This process will definitely help us write out the user stories for this feature which we have scheduled as "Next" and so we are hoping to start working on this after Q2.
Feel free to add insights here https://vanillaforums.productboard.com/roadmap/4250432-vanilla-2022-roadmap/features/12108981/detail or to email them into product@vanillaforums.com and I will add them to our issue.
6 -
Echoing what Rhys said earlier, I feel like there could be a streamlined process for suggesting minor changes to existing articles. It's a bit cumbersome going through all this when you just want to point out a small mistake or sentence that needs correcting (which will likely often result in people not doing it).
Appreciate the efforts to standardize this process, though!
1 -
I was just thinking the exact same thing
0