Create a user guide for content editors

[verythorough]

This is pulled from the docs re-org issue decaporg/decap-cms#598 (comment)

The current docs focus mostly on "implementers" (people writing code to configure and customize Netlify CMS on their site) and a little bit on "contributors" (people making contributions to the CMS itself). So far, they don't provide any guidance for content editors using the CMS UI to add and edit content.

I'm thinking that initially, we can put the whole guide in a single page of the docs, but I suspect we'll want to break it out into a multi-page section when we've decided how we want that to work. For now, I think getting any guidance for editors would be helpful.

Content-wise, I'm thinking this is not a place to explain what’s happening “under the hood,” though we may include links here and there for the curious. Here's a rough outline brainstorm to get anyone started who might like to take this on:

• Accessing the CMS UI: may vary, but describe common use case of website.com/admin
  • troublehooting access?
• UI overview
  • Sidebar
    • editorial workflow - brief description, link to dedicated section
    • collections
      • show existing content
      • create new content
• Content editor
  • Accessed by selecting an existing item or creating a new one
  • Brief explanation of fields and preview
    • required/optional
    • not all field values displayed in preview
    • special widgets like image (link to media library section)
  • Rich text editor
    • Markdown mode
    • Inserting blocks (like image)
  • What “Save” does (depending on whether Editorial Workflow is enabled)
• Media library
  • adding/deleting/searching for assets
  • how to add to content (link to content editor)
• Editorial Workflow
  • getting content into the workflow (by saving changes)
  • moving centent between columns and what that means
  • publishing from the ‘Waiting to go live’ column

[JRPfeiffer1]

I came up with a couple of paragraphs that might be useful as an introduction to the content editor’s user guide:

Netlify CMS is a fast, safe, and scalable content management system that comes with rich-text editing, real-time previews, and drag-and-drop media uploads. Its intuitive workflow makes it easy to manage content from draft to review to publish—across any number of content types.

Because it’s open source, Netlify CMS is supported by a growing community of developers. They love the fact that it works seamlessly with Git—but thanks to the work they’ve done, you’ll probably never have to think about that.

[erquhart]

Thanks @JRPfeiffer1!

@verythorough thanks for putting this together, that outline looks like a solid start.

[tech4him1]

I think it would be a great idea to add "help links" from inside the CMS once this documentation is written.

[jorear81]

I would like to tackle Media Library.

[verythorough]

Great, @jorear81! I think we'll be doing some re-arranging (and changing the media library functionality a bit, too), but until then, this will still be a useful resource for others.

How about we create a "Media Library UI" page in the Reference group of pages for now. We can add more sections and put them into a larger guide later.

[ademuro]

I would love to pick up the remainder of the work for this user guide for content editors. Has anyone else been working on this? @verythorough and @JRPfeiffer1 thank you for the work you have done on this already!

[erquhart]

I don't believe there's any ongoing work on the content side of this, no. Open for contribution 👍

[tomrutgers]

Happy to provide feedback to ideas etc @ademuro

[ademuro]

@tomrutgers yes, please! that would be great. i'll start by spending time getting to know the CMS better and then write up a draft to share with you and @verythorough (if she's interested). would that work? i appreciate any feedback and i look forward to working on this :)

[tomrutgers]

Sure! If you have questions about the CMS join us on Gitter

[pungggi]

I am at your disposal for any translation in german and italian..

[ademuro]

Besides Netlify Identity, I'm wondering what other identity services CMS users might use to access the CMS? For this documentation there is a section on how to access the CMS, but I am not sure how we want to address it since I believe there are a lot of different ways to access it?

[erquhart]

Authentication is really up to the backends. Git Gateway supports Netlify Identity, while GitHub, Bitbucket, and GitLab backends authenticate direct through their respective services (or through custom oauth if you configure it). This page more or less covers it (but is targeted at devs): https://www.netlifycms.org/docs/authentication-backends/

[tomrutgers]

Apart from custom solutions, there are two ways to log in:

• With a user name / password (Only available with Netlify Identity)
• With external auth
  1 Github
  2 GitLab
  3 Bitbucket
  4 Google OAuth (Only available as external provider with Netlify Identity)

[erquhart]

You said that so much better lol, thank you

[ademuro]

Thanks, Shawn and Tom! I'll post my draft in this comment thread today.

[ademuro]

Here is a draft of the content editor guide:
https://paper.dropbox.com/doc/Draftbrainstorm-for-content-editor-guide-Netlify-CMS--ATh5LipS_NmO75sa8c9HqblzAQ-KemvQi07ln8itRhaZ1Gbd

Please feel free to make edits and add comments as you please! Let me know if you have any questions or concerns. Thank you!
Also, the Accessing the CMS/Identity section is pretty bare right now because I have two questions:

1. The first time a user visits the CMS using external auth, will they be sent an invitation email?
2. Are all CMSes located at mysite.com/admin or can the URLs differ?

[tomrutgers]

I'll take some more time to comment your draft later. First response: This is looking great already!

1. I'm not sure about the Google workflow, but with Github and Bitbucket it means getting invited to a repo.
2. mysite.com/admin/ with the trailing slash. But yes.

Do note that you can set up Git Gateway to use both username and password and external auth at the same time. A login screen can look as crazy as this:

Accessing the CMS

If your site uses Netlify Identity, invited users will receive an email with a confirmation link. Open your email, click on the link, and be directed to your site within seconds. Follow the login prompts to set up your account.

As you might have noticed that screen has a 'Sign up' tab as well. With this option enabled in Netlify Identity (screenshot) you don't have to be invited. Otherwise the workflow is the same (follow a confirmation link)

[verythorough]

Regarding decaporg/decap-cms#2, yoursite.com/admin/ is by far the most common route for logging in, but it's not guaranteed.

The degree of possible variability in the login process makes documenting it difficult. It's impossible to document every conceivable possibility, so I see two alternatives:

1. Tell the user to contact their "site administrator" for login instructions. This will likely be part of the process for most users anyway.
2. Document the single most common procedure, with a note that configurations may vary, and users should contact their site admin for details if the instructions don't match their experience.

I think 1 is shippable, but 2 would be more complete. For the "single most common procedure," I would match what's in the quick start templates (and be sure they match each other).

[tomrutgers]

To be honest, the users that need guides like these probably won't sign in using GitLab anyway. Netlify Identity + Git Gateway (username + password) is the most common practice if I have to take a guess.

[dopry]

I think getting something shippable our and revising based on feedback as good. It would be nice to have a document or anchor for each login flow. As a site builder, I can link my clients to the correct content in our hand-off documents. I would prefer pages for each flow that varies like that so I don't link a user to an in-page anchor and then they scroll elsewhere and get confused.

I only think this is really important for login as it's a user's first impression. Where the optionality can be explained in the documentation such as Workflow and editing I think it is fine to keep inline. It might make make sense to break our Media handling by the back-end. Cloudinary is definitely very different at least visually than managing media in Git.

@ademuro's document looks like a great start.

[cassandraoid]

Are there any docs for content editors I am missing (I see this is an old issue)? Going to be using the project for a new site and want to be able to reference my editors to something :) looked through the docs but seems to be targeted toward the devs.

[erquhart]

Hey Cassandra - you're not missing anything, this just hasn't happened yet. I'm going to take a quick run at docs improvements next week, I can try to cook up at least a guide if you can mention any specific areas that you're hoping to see user docs for.

[verythorough]

Hi @cassandraoid!! Until we do gets these into the proper docs, @ademuro's draft above is a start: https://paper.dropbox.com/doc/Draftbrainstorm-for-content-editor-guide-Netlify-CMS--AfCBZPzCD2vc54VzU0oVv7gqAg-KemvQi07ln8itRhaZ1Gbd

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.