search

decaporg / decap-website

Source of Decap website and docs
https://decapcms.org
3 stars 91 forks source link

Create a user guide for content editors #2

Open verythorough opened 6 years ago

verythorough commented 6 years ago

This is pulled from the docs re-org issue https://github.com/netlify/netlify-cms/issues/598#issuecomment-332564210

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:

JRPfeiffer1 commented 6 years ago

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 commented 6 years ago

Thanks @JRPfeiffer1!

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

tech4him1 commented 6 years ago

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

jorear81 commented 6 years ago

I would like to tackle Media Library.

verythorough commented 6 years ago

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 commented 5 years ago

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 commented 5 years ago

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

tomrutgers commented 5 years ago

Happy to provide feedback to ideas etc @ademuro

ademuro commented 5 years ago

@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 commented 5 years ago

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

pungggi commented 5 years ago

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

ademuro commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

erquhart commented 5 years ago

You said that so much better lol, thank you

ademuro commented 5 years ago

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

ademuro commented 5 years ago

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 commented 5 years ago

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:

login

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)

registration
verythorough commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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[bot] commented 4 years ago

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.