Reorganize the docs with a strong focus on the user

[tomrutgers]

Is your feature request related to a problem? Please describe.
Related to decaporg/decap-cms#598

Short version: Currently the docs are written the way the system works. I'd like to explore the option of reorganize it according to how a user might think.

Describe the solution you'd like
I will provide ideas and examples over time to come up with one. I would love to hear thoughts and feedback.

Developers vs editors vs contributors
In light of https://github.com/netlify/netlify-cms/issues/1340 and decaporg/decap-cms#1038:

The docs (and eventually the entire website) will need to accommodate developers, editors and contributors alike. We should split content based on your profile. Upon entering the docs homepage you should have the option to choose between those three options before getting started. You should be able to easily switch between guides since you can have multiple roles at the same time.

Considerations

• Different areas of the CMS should have their own top level section. (Collections, widgets)
• DRY content. Currently the same topics can be found on different places in the docs.
• Sort the top level sections by things you need to do first, secondly etc.
• Explore flows based on user needs (I need my site to be stored on github, hosted without netlify identity, users should sign in with their email etc)
• Design. The docs are quite different from the Netlify visual identity and the look and feel of the CMS itself. Don't mind too much, but we could try to bridge some gaps.
• Navigation depth. Pages should be broken up in a way that you don't need to navigate by clicking anchor links IMHO.

TL;DR - First ideas put into practice:

[erquhart]

I love everything here, goals are right on target 👍 👍

[tomrutgers]

Before you get started idea
It would be nice to know what you're getting into before you get started. Introduce all the necessary steps before actually undertaking them.

disclaimer: I'm obviously not a copywriter :)

[tomrutgers]

backend flow
I feel we should help developers decide what backend / authentication to use. Maybe a click through flow with configuration as a result? User icon means client login without git account.

Is this flow correct or am I missing things?

[tech4him1]

I really like the "backend flow" idea, but that format is confusing to me. For example, "External Oauth" and "Bitbucket backend" aren't really something the user is thinking of -- that's a CMS implementation detail. We need something more like "Git Gateway" and "Repository access". External OAuth is a "Without Netlify" option -- it should go in the same row you would put "implicit grant" in.

I'm also wondering if "With Netlify.com"/"Without Netlify.com" should be actual table columns -- it's sort of hard to tell what they go with right now. Maybe that's where we could put links to the tutorials -- i.e. a Gitlab (row) -- Git Gateway (row) -- Without Netlify (column) -- link (cell).

Hopefully that makes sense 😄

[tomrutgers]

@tech4him1 That's obviously not communication, yet. I'm just trying to figure out what the actual flows are, before I can start to make an understandable step by step guide. (I want to use github. I need my client to login with email / github account / custom solution etc.)

That being said, I only just now realize how that image could be confusing. It's not actually a table..

We're basically trying to say the same thing. Start by choosing the kind of repository access you prefer. Then decide if you want git gateway, just a git backend or a custom solution. If you choose git gateway you can make use of netlify or not..

[tech4him1]

Ah, OK, i see now. I think "External Oauth" should still be under "GitHub backend", though, since it is just an authentication method like "without netlify"

[tomrutgers]

Ok! That counts for the gitlab and bitbucket backend as well then I assume?

[tomrutgers]

Also: are there any ways for clients to log in with just their email and password other than through git gateway?

[tech4him1]

Ok! That counts for the gitlab and bitbucket backend as well then I assume?

Yes!

Also: are there any ways for clients to log in with just their email and password other than through git gateway?

They can log in to GitHub/GitLab/BitBucket with their email and password, of course, but there aren't any non-OAuth ways in the core package.

[tech4him1]

By the way, this whole thing looks so awesome, thanks for working on it!

[tomrutgers]

Let me rephrase: There aren't any other ways of signing up for a websites cms directly other than git gateway right? For any other option you would need a github/lab/bitbucket account?

[tech4him1]

Exactly. Currently there are no built-in ways other than Git Gateway for which editors do not need a direct repository access.

[verythorough]

I love this! It's just the sort of organization I've been wanting to implement for over a year, but haven't had the time or design resources to make it happen. Great work!

As we get the structure and organization more fleshed out, we've had a handful of tech writer contributors recently who would likely he happy to work on the writing portion.

[tomrutgers]

Any ideas on how to get started / develop this more / etc @verythorough? Happy to work on this, but I feel I could use some input from someone that knows the docs through and through 😇

[erquhart]

Pretty much any maintainer will know the docs well, that includes:

• @verythorough - specifically focused on docs
• @tech4him1
• @talves
• @Benaiah
• @erquhart

[tomrutgers]

Right. It would be nice to know your needs / ideas/ problems with the docs so we can start working on some outlines to get going.

[talves]

This is definitely going to need some thought and might even take some iterations for layout to best benefit beginner vs advanced users. I like where you are going with the idea @tomrutgers

A good question is do we write the docs like a tutorial as you did above or write tutorials that link to the docs that are laid out in sections that make more sense? Where I am a little weary in the tutorial layout is that we end up updating the same information in multiple places when there is a change to a common section. Granted, I have not given this a ton of thought. I am glad you are bringing it to the surface.

[erquhart]

Ah, I thought you needed to know who to ask when you had specific questions. Honestly, we just need an approachable and complete set of docs. As someone new to the CMS, you're actually in a fantastic place to help guide that process because you're running into the areas where we're lacking firsthand.

This doesn't cover all of it, but for sections like Backends, Widgets, etc, I've been imagining having a page per thing, e.g.:

- Backends
  - Some kind of intro
  ...probably a few other things here, followed by:
  - GitHub
  - GitLab
  - Bitbucket
  - Git Gateway
  - Test Repo

[tomrutgers]

@talves I don't think writing the docs as a tutorial is a very good idea, no. More like a tutorial? Yes. The layout in the second image is meant as a 'before you get started' page. It would be good to know what steps you need to undertake to get your cms going. Set up the config, add a backend, define a collection and add widgets to it. Need something else? Customization ftw. I think decent code snippets / examples are good enough tutorials for most people. Specially if we add different scenarios for the same type of example.

That being said, your comment gave me a bit of an idea. It might be nice to have something like this: decaporg/decap-cms#1167 in a sidebar. Maybe not the real deal (entire config builder) but an informative distillate. By selecting different options you could see your config getting build in a sidebar or something. It would help a lot with understanding what the impact of every decision is. I have no clue how complex that would be to build and maintain, but I guess you do.

[tomrutgers]

[erquhart]

NICE!!

Can you share more about what you're thinking for that right sidebar? Interactive or just display?

[tomrutgers]

Preferably interactive. Not sure how yet, but it could be nice to have examples at the end of each section. Like.. an explanation of using widgets followed by a simple form:

Add your first widget
select: widget input: name

Same for collection type, backend and auth, media folders and so on. The idea is that if you visited all the sections in the docs you've had the chance to try all possible settings. We could put in a big ol' button that links to the visual builder in the bottom to complete your config to do nesting etc.

Alternatively we coud do a display as well, which can be your side tutorial. In the docs all the examples get added to the sidebar the further you browse through the docs. If the page contents are about backends for instance, the sidebar shows where in the config those settings need to be. Each example gets added on scroll / visit /... Might be easier to build and maintain, but I'd prefer the interactive way :)

[dopry]

As a supporting story. I'm onboarding an editorial team right now. I'd really like to link them to an existing Netlify CMS documentation site that explains to users how to do basic tasks on the site. Unfortunately, all of the online documents are developer centric.

Here are the key topics we've encountered.

1. UI Overview
2. Creating Content (In the UI it might make sense to rename this from collections to content for editors)
   2.1. Linking Images using the editor (currently requires a switch to markdown mode)
3. Using Editorial Workflow
4. Troubleshooting Publishing. (Netlify Deploys, it would be nice to bring build status into the UI)

[tomrutgers]

@dopry Have a look here: https://github.com/netlify/netlify-cms/issues/1340

[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.