Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

How does help get propagated, both seeds and updates? (What do doc maintainers need to know?) Question

+2
−0

I know this is buried in Discord somewhere, but for better findability:

There is a seeds script (where?) that takes new help topics and propagates them to communities on a network. Where do those help topics need to be deposited? (We're using a separate docs repo to create them and then they get pulled into the qpixel repo, IIRC.)

I know that updating help topics is not as straightforward. How do we propagate changes now? Is there anything that doc-team members working on updates should be aware of, beyond reducing the number of updates (batch changes)?

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

0 comment threads

1 answer

+1
−0

I can only really answer the first part of the question -- how help topics get initially:

From a software development position, it doesn't really matter what happens to the articles in the docs repo. What matters for deployment is having the help articles added to the seeds.

To do so, you need to do the following:

  1. You need to get a HTML version of the article. If you've previously written it in markdown, you need to convert it. I'm mostly doing it manually, but there are countless websites and tools for it, for example https://markdowntohtml.com.

  2. You need to find an URL slug for the article. This is, what will be in the URL as /help/[slug]. This should be mostly alpha-numeric, plus _ and -.

  3. You need to create a file for the body of the article. This file must be placed under db/seeds/posts/[slug].html. Write the HTML version of the article into that file.

  4. You need to add a seeds entry for the article. This one needs to be appended to db/seeds/posts.yml. What you need to add follows the following template:

    - post_type_id: <%= HelpDoc.post_type_id %>
      title: [post title]
      body_markdown: $FILE posts/[slug].html
      body: $FILE posts/[slug].html
      doc_slug: [slug]
      help_category: [category]
    

    In this template, replace [post title] with the title you want the help article to have, [slug] with the aforementioned slug and [category] with the name of the help category (posts with the exact same category name will be grouped into one category).

    This template creates a classical help post. These can be edited by community moderators. If you want to have a policy document, which can only be edited by administrators, replace HelpDoc with PolicyDoc in the first line.

This should be all you need to create a help topic. To make sure, I recommend to run db:seed locally before you push the commit to production, because modifying seeded posts is a bit harder... :D

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

Sign up to answer this question »