search

wpsharks / s2member-kb

The s2Member® and s2Member® Pro Knowledge Base
9 stars 4 forks source link

Introduction to s2Member #296

Closed patdumond closed 8 years ago

patdumond commented 8 years ago
KB Article Creation Checklist

KB Article Published @ s2member.com
:page_with_curl: See: Introduction to s2Member

:octocat: View Markdown File | :pencil2: Edit Markdown File

patdumond commented 8 years ago

@raamdev, @jaswsinc: First draft of the first chapter of the s2Member User's Guide, Introduction to s2Member is ready for review. I included s2Member User's Guide: in the title so that I would remember to ask if you thought we should do that for all of these articles. Thanks in advance.

jaswrks commented 8 years ago

@patdumond Woohoo! I love it :-) That is a very nice introduction with great structure and perfect answers to a lot of the questions that people will have whenever they are first introduced to s2Member. Really impressed by your choice of words throughout.

Forgive me for being picky here, but it's just that; me being picky :-) I'm going to try and being extra picky here since this is the first in a series, because my feeling is that my pickiness might help reduce the number of edits you need to make in future submissions.

s2Member is a powerful WordPress plug-in, actually two of them, for turning your website into a private online club or community.

  • [ ] Suggest: "actually two of them (the free s2Member Framework and the Pro Add-on)"

displaying it to only the audience you have chosen for each post, page, or download file on your site.

  • [ ] Suggest title case for: "Post, Page, or File Download", and I'm using the term "File Download" instead of "download file", only because that's more consistent with other documentation we have written.

paste into a WordPress page (or post, if you prefer).

  • [ ] Suggest title case for: "paste into a WordPress Page (or Post, if you prefer)."

The MOP is the page you designate

  • [ ] Suggest title case: "The MOP is the WordPress Page you designate"

use PHP in posts, pages, or text widgets

  • [ ] Suggest title case: "use PHP in WordPress Posts, Pages, or Text Widgets"

and anywhere else in the article where you reference a Post or Page, etc.

2016-04-07_08-30-14

All registered members of your website are WordPress Users with an assigned s2Member User Role. In the free s2Member Framework, you can have users with levels 1 - 4 (plus Level 0 Free Subscribers if you want them). In s2Member Pro, you can have as may user levels as you need.

I suggest title case for some of these user types, and now that we have a list of terms I'd like to see if we can adhere to those terms so that all of your articles are consistent with articles written in the past when referring to various types of users in the software.

and similar changes anywhere else in the article where you reference a User, Member, Role, etc.

without requiring user registration at all with Buy Now buttons

  • [ ] Suggest comma and using: "without requiring user registration at all, using Buy Now buttons"

hosted on Content Data Networks (CDN)

  • [ ] Suggest: "hosted by Content Delivery Networks (CDN)"
patdumond commented 8 years ago

I actually agree with all the "title cases", I tried to use it throughout the document but missed some. I will fix those. All your other "nits" are also fine. :) I'll fix those.

I don't know what is with the redirects. I'll take a look. I don't know why I would have links that redirect to login at s2Member.com: you don't have to log in to see the KB do you?

jaswrks commented 8 years ago

you don't have to log in to see the KB do you?

Nope. It looks to me like those redirects might just be something that Google injected automatically on ya.

jaswrks commented 8 years ago

@patdumond writes...

I included s2Member User's Guide: in the title so that I would remember to ask if you thought we should do that for all of these articles. Thanks in advance.

I think that's a good idea, but I'd love to hear Raam's thoughts on that also. If I think ahead for a moment to a time whenever we have all of these articles plus the full Guide too, then each of these articles that reference that Guide could also contain a link to the full Guide, either at the top or bottom, and so having the s2Member User's Guide: prefix in each title makes sense to me also.

If we go that route, it might help if we setup a Redirect to what will eventually be the full guide (so Pat can link to that), and for now just keep it as a placeholder with a message about it coming soon.

patdumond commented 8 years ago

If I think ahead for a moment to a time whenever we have all of these articles plus the full Guide too, then each of these articles that reference that Guide could also contain a link to the full Guide, either at the top or bottom, and so having the s2Member User's Guide: prefix in each title makes sense to me also.

Those were my thoughts exactly, but I will defer to whatever you and Raam decide.

patdumond commented 8 years ago

@jaswsinc wrote:

Nope. It looks to me like those redirects might just be something that Google injected automatically on ya.

Yep. All the URLs are fixed and I've created a task to check all the URLs in the master document. Thanks!

patdumond commented 8 years ago

@jaswsinc and @raamdev: I've made the changes requested by @jaswsinc.

[x] URLs corrected [x] "hosted on Content Delivery Networks (CDN)" changed to "hosted by" [x] Suggest comma and using: "without requiring user registration at all, using Buy Now buttons" - change made [x] Terms & title case changes made & task added to make corrections in master document

I'd appreciate this being reviewed quickly as I am honestly a little anxious to start seeing these articles published. ;) I've been working on them for a long time.

jaswrks commented 8 years ago

Thank you Pat! :-) Keeping em' coming. I'll be approving and publishing this week.

Quick question, this article ends with ". I..."... and if I recall there was more to the article. Did it get cut-off somewhere along the way?

patdumond commented 8 years ago

No. I saw that when I converted the markdown back to Word, but I double checked and there was nothing following in the original. Thought I had pulled it out here. Will do that first thing in the AM. On Tue, Apr 12, 2016 at 19:05 jaswsinc notifications@github.com wrote:

Thank you Pat! :-) Keeping em' coming. I'll be approving and publishing this week.

Quick question, this article ends with ". I..."... and if I recall there was more to the article. Did it get cut-off somewhere along the way?

— You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub https://github.com/websharks/s2member-kb/issues/296#issuecomment-209141641

raamdev commented 8 years ago

@patdumond writes...

I included s2Member User's Guide: in the title so that I would remember to ask if you thought we should do that for all of these articles. Thanks in advance.

@jaswsinc writes...

I think that's a good idea, but I'd love to hear Raam's thoughts on that also.

My suggestion is that we do not use "s2Member User's Guide:" as a prefix in all of the KB Article titles. Here's why:

I suggest that we leave "s2Member User Guide" out of the title and instead add a new tag to each one called "s2Member User's Guide" (you can use the slug s2member-users-guide in the tags: section of the YAML Markup—instead of s2guide—along with any other relevant tags). That way someone who is reading an article that is part of the Users Guide can simply click the "s2Member User's Guide" tag that shows up at the top of the article (underneath the title) to immediately see a list of all articles that are part of that guide.

@patdumond writes...

This s2Member Knowledge Base Article (KBA) is the first in the series of articles which will comprise a complete User’s Guide for s2Member. The User’s Guide will be published both as a PDF document and as a KBA incorporating all of the individual KBAs in this series.

@jaswsinc writes...

If we go that route, it might help if we setup a Redirect to what will eventually be the full guide (so Pat can link to that), and for now just keep it as a placeholder with a message about it coming soon.

My feeling on this is that we should leave out that initial paragraph and not put in any placeholder links until the guide is published in PDF format. The reason I say this is that once all of the KB articles + a PDF guide have been published, we'll want to come back in and update all of the KB Articles anyway, to include things like lists of related KB Articles that are part of the guide, etc. We could also place a fancy box that stands out from the rest of the article pointing people to the full PDF guide.

It makes more sense to me that we do that as one single project, once all of the KB Articles have been published, rather than trying to do it now when we don't have all the information we need.

Trying to get all that stuff into the articles now, before that part is even done, just adds confusion for readers. Also, if we did add a message about an upcoming PDF guide, then we should be setting up a mailing list where people can be notified about the guide when it's released, etc. Since these are being published as KB articles and not blog posts that get mailed out to thousands of people, the latter doesn't make sense to me.

plug-in

Please use 'plugin' instead. While dictionaries still list 'plug-in' as the term, the term that is more widely used is 'plugin' (see WordPress.org).

patdumond commented 8 years ago

@raamdev: I will follow your recommendations on the use of s2Member User's Guide and leaving out the "this article is part of...* paragraphs. Your reasoning is very sound. :)

I will also replace plug-in with plugin

patdumond commented 8 years ago

@raamdev, @jaswsinc: Changed plug-in to plugin. Removed s2Member User's Guide from title. Removed first paragraph referencing the User's Guide.

Is there a way to reference a tag in the article, so that users unfamiliar with the KB interface can be told that they can click on the tag to see all the articles in the series? Something like

This article is part of a series of articles making up our s2Member User's Guide - click here (link to bring up all tagged articles, if possible).

Thanks in advance.

raamdev commented 8 years ago

@patdumond ...

Is there a way to reference a tag in the article, so that users unfamiliar with the KB interface can be told that they can click on the tag to see all the articles in the series?

Oh, that's a great idea. :-) Yes, you can use the following link (it won't work until we actually publish a KB Article with this tag): http://s2member.com/kb/kb-tag/s2member-users-guide/

I'd add the following, in italics, as the last paragraph of the introduction to each KB Article:

This article is part of the s2Member User's Guide, a series of articles that cover the fundamentals of using s2Member.

(The reason that I say it should be the last paragraph of the introduction to each KB Article is that the very first sentence of each article has larger text than the rest, so putting that as the first sentence in an article would unnecessarily emphasize it.)

patdumond commented 8 years ago

@raamdev: Thanks! Makes sense to put it in the last paragraph as well, because they would be more likely to read the other articles if they've read the current article all the way through.

jaswrks commented 8 years ago

👍 Thumbs up on those ideas. Great conversation. Outstanding points made. Nice!

jaswrks commented 8 years ago

@raamdev I'm leaving this for you to approve. Looks great to me.

raamdev commented 8 years ago

@jaswsinc Looks great to me.

@patdumond I don't see the "This article is part of the s2Member User's Guide" line as the last part of the introduction, but otherwise this looks fantastic to me.

2016-04-14_07-04-44

raamdev commented 8 years ago

@patdumond Also, you did not update the YAML markup with the updated title; note that the title that actually gets used on s2Member.com when the article is published from from the YAML markup at the top of this GitHub issue.

Also, please use s2member-users-guide for the tag in the YAML markup, not s2guide (you can keep using the s2guide label for the GitHub issues—that's fine). And if you could also add any other relevant tags to each KB Article, that would help people find the article when searching for related things. For example, I would also add pro-forms and shortcodes as tags to this article, so that would give you pro-forms, shortcodes, s2member-users-guide.

patdumond commented 8 years ago

@raamdev: Made these changes:

raamdev commented 8 years ago

@patdumond Thank you. For future reference, the s2member tag is not necessary in the YAML markup. I've removed it from your two most recent articles, but wanted to let you know for future ones.

raamdev commented 8 years ago

@patdumond Please note the following fixes:

When including shortcodes in your articles, the shortcodes must be escaped when they're not inside a code style or a code block. For example, if you're linking to a shortcode in your article like this:

[[s2Member-Summary /]](http://s2member.com/kb-article/s2member-summary-shortcode-documentation/)

You must escape the shortcode by adding an extra pair of brackets around it: [s2Member-Summary /] becomes [[s2Member-Summary /]]. So the above example should look like this in your article:

[[[s2Member-Summary /]]](http://s2member.com/kb-article/s2member-summary-shortcode-documentation/)

Keep in mind that s2Member.com is itself running s2Member, so if you don't escape the shortcodes, s2Member will try to parse them inside the article.

You can review this commit for the changes I made related to shortcodes: https://github.com/websharks/s2member-kb/commit/a66d5bbd868a28a9342696bade31ec09cabf9c21

I also noticed several areas where your Markdown formatting was incorrect, which resulted in bad output when the article was parsed for s2Member.com:

**NOTE: This shortcode requires **_s2Member Pro_.

should be:

**NOTE: This shortcode requires _s2Member Pro_**.

and

**NOTE: This shortcode requires _s2Member Pro_**.**

should be:

**NOTE: This shortcode requires _s2Member Pro_**.

See this commit for what I fixed: https://github.com/websharks/s2member-kb/commit/ce3311561d812f21d1966fd35adacc13a6d02144

patdumond commented 8 years ago

@raamdev: Duly noted. I've copied those notes to my KBA prep notes. Thanks.