User guide topics

[docwilmot]

Continuing from backdrop-ops/backdropcms.org#55 We've agreed and started on user docs This issue will be to suggest, critique and track the topics to be included in the docs

Checked means on BackdropCMS.org, not necessarily completed.

• [ ] Quick start guide
• [x] Modules themes and layouts
• [x] Nodes and Entities
• [x] Understanding Layouts
• [x] Blocks
  • [x] Configuring blocks: examples
• [x] Content types
  • [x] Create a custom content type
  • [x] Add fields to a content type
• [x] Display settings (View modes)
• [x] The Admin bar
• [x] Menus
• [x] Project installer
  • [x] Updating project code (combined with Installer documentation)
• [x] Taxonomy and categorizing content
• [x] Users, roles and permissions
• [x] Views basics
  • [x] Views exercises
  • [x] Configuring Views - advanced
  • [x] Configuring Views
• [ ] Installation
• [x] Themes
  • [x] Color
• [x] Creating content
• [ ] Multilingual
  • [ ] Regional settings
• [x] Configuration Management move to developer docs
• [x] Multisite move to developer docs
• [x] Ckeditor
  • [x] Filters
• [x] Book
• [x] Comment
• [x] Contact forms
• [x] Fields
  • [ ] Date
  • [ ] File
  • [ ] Image
• [x] Pathauto
• [x] Tokens
• [x] Search
• [x] Redirects
• [x] Account settings and emails
• [x] Files
• [ ] Media and images
• [ ] Site reports
• [ ] Maintenance and configuration
  • [ ] RSS publishing
  • [ ] Site information
  • [ ] Date and time formats
  • [ ] Caches
  • [ ] Cron
  • [ ] Updates
  • [ ] URL handling
  • [ ] Performance
  • [ ] Maintenance mode
• [ ] Howtos
  • [ ] Customizing the front page
  • [ ] Creating lists of content
  • [ ] Create an image gallery
  • [ ] Customize the User Registration Form
  • [ ] Create a Blog site
  • [ ] Create a personal site
  • [ ] Members-only site

[tomgrandy]

@klonos - What did you use to create the animated gif above?

[jenlampton]

@tomgrandy it doesn't look like we have a diff module for backdrop yet. Maybe create an issue over at https://github.com/backdrop-ops/contrib/issues and see if anyone is working on it yet (or wants to?). We do have the diff engine (and colors!) in core already, so I think it shouldn't be too much trouble.

[jenlampton]

I'm not happy with the current colorbox module. Giving it a rewrite for backdropcms.org.

[jenlampton]

okay, fixed up colorbox (https://github.com/backdrop-contrib/colorbox/pull/10) and pushed it up. I'm not sure how you're going to add the necessary classes on the inline images, but let's see if we can't get it working.

[tomgrandy]

@jenlampton - Thank you for taking the time to tweak colorbox and push it up. Will give it a shot today to see what I can do.

Also, will post to contrib/issues to see if there is anyone working on a diff module.

[klonos]

@all sorry guys for not being very responsive lately. I cannot even begin to explain how busy I am these days.

It would be awesome to have the diff module ported and installed so we can track revisions without manually typing every change into the Revision Information.

👍 1 million.

@klonos - What did you use to create the animated gif above?

http://blog.bahraniapps.com/gifcam but there's also http://www.cockos.com/licecap that works on OSX

[tomgrandy]

@klonos - No worries. Thanks for taking the time to respond. I posted a request to see if anyone was working on, or thinking about working on, a diff module on github at:

https://github.com/backdrop-ops/contrib/issues/182

Will see if that garners any responses.

Thanks for the licecam link. Worked perfectly!

[tomgrandy]

@wesruv - Can you take a look at the source code for the colorbox-inline link that tries to open with colorbox, but does not display here:

https://backdropcms.org/node/468/

Probably not the easiest way to do this, but if we can get it to work, I can swap filenames in for screenshots to be enlarged with colorbox.

Or if you have a better method of applying CSS to all inline images that need to utilize colorbox, that would be awesome!

I can attach an image via an imagefield on my personal backdrop site and colorbox works perfectly, but the documentation content type on BackdropCMS.org does not have an imagefield so inline images are the only option (which makes sense since a how-to page is bound to have multiple inline images).

[jenlampton]

Could we give you a Style, like we have for the navigation links and submit buttons, maybe?

[tomgrandy]

Style would be fantastic! Just so I have a way to identify those images that should utilize colorbox.

Thanks

[tomgrandy]

@jenlampton @docwilmot @klonos

Rest assured that I am that user who is using BackdropCMS.org for the first time to understand how to install and use Backdrop because that is exactly what I am doing. But the order of presentation is confusing to say the least.

The content is solid and most everything I need to know is already there, it is just the order makes me have to hunt for what I need and that is not good.

Therefore, I propose the following that is not intended to start any heated discussion, but if you wanted a user group to test on, that is me.

So for the good of the cause and the new user, I propose I do the following:

1) The About Backdrop section does not belong in the Handbook but should stand on its own accord as a link above the Handbook link. It is important background information, vitally important to someone looking to adopt, but it is not on how to use Backdrop as one would expect in a Handbook.

2) You have a User Guide and a Developer Guide in two different places and some of my needs overlap both, especially installing Backdrop. The two should merge with a hierarchy ordering from the simple to the complex such as:

Installing Backdrop

• System Requirements
• Installation Instructions

followed by

The Basics:

• How to Log In
• Admin Bar
• Content
• Comments
• Contact Form
• Search

Visual Aspects of The Site:

• Themes
• Layouts
• Blocks
• Menus

Customizing Content:

• Content Types
• Fields
• Taxonomy
• Views

Extending Functionality

• Modules
• URL Aliases
• URL Redirects

User Management

• Creating Users
• Identifying Roles
• Customizing Permissions

Developer Tools

• Upgrading From Drupal 7
• Backdrop Upgrades
• Submitting Pull Requests
• Developer Documentation
• Backdrop API

^^ Everything in the Developer Tools section is something I would probably pull in another person to work on, Everything above that is what I need to know to build and manage a site on my own.

Be kind. I'm not trying to muddy the waters here, but rather make them clear as the water around a Caribbean island where I wish I was now that winter is descending soon.

[tomgrandy]

@jenlampton @docwilmot @klonos @wesruv

Also, check the site out the BackdropCMS.org site on mobile with regard to where the menus end up (bottom).

Granted, we are probably all looking at the site on dual monitors, but if Backdrop is mobile friendly, don't want your flagship site dumping the menu.

I think you should choose either the l-drawer off the Handbook link or the l-sidebar inner, but not both for mobile navigability and desktop for that matter for when both are opened main content real-estate is squeezed.

Wordpress Codex is built in tables https://codex.wordpress.org/ and tables don't play nice on mobile.

However, https://learn.wordpress.org is mobile friendly with a menu that is operable.

(Is this where I am invited to no longer work on documentation?)

[jenlampton]

One correction to your thinking: the handbook and the user guide are separate concepts with no relation to one another.

The handbook is a document someone new to backdrop can read (every page) front-to-back to understand the what/why of backdrop. Not the how.

The how of Backdrop is in the user guide. The user guide will have its own place in the menu (under support) separate from the handbook. The documentation will be too extensive and feature-rich to be considered a handbook. It's a reference guide.

Ignore the about section and everything in the handbook while we are working on the user guide, and we can revisit the handbook next, if you are up for it :) (no pressure!) Some links may be duplicates only because we had no user guide before now. Those could be deleted / redirected as necessary, but don't let them confuse the point of the handbook.

I like your suggestions about reworking the order of the user docs. It Looks great to me!

The mobile navigation is a bit of a hack, and could use reworking in general. We have some work to do :/

On Oct 14, 2016 6:09 PM, "Tom Grandy" notifications@github.com wrote:

Also, check the site out on mobile with regard to where the menus end up (bottom).

Granted, we are probably all looking at the site on dual monitors, but mobile rules and having the menu at the bottom makes it hard to navigate.

Should choose either the l-drawer off the Handbook link or the l-sidebar inner, but not both for mobile navigability.

Wordpress Codex is not acceptable on mobile https://codex.wordpress.org/

However, https://learn.wordpress.org is mobile friendly with a menu that is operable.

FWIW

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub backdrop-ops/docs.backdropcms.org#196, or mute the thread https://github.com/notifications/unsubscribe-auth/AAYSR6Sn8wg36MKlwBx-vwzYyRGxTv1Mks5q0CeugaJpZM4I4c22 .

[tomgrandy]

@jenlampton - Thanks for the clarification. I was confused by the overlap of "how" content that appears in the Handbook pop-out menu (ie - User Guide, Developer Guide).

If you are okay with me repurposing parts that have already been written in the categorized order I presented, I'll copy them into the hierarchical flow from simple to difficult in the User Guide.

I'm always up for a challenge and if you all like what I do with the User Guide, then we can take a look at the Handbook which should, as you pointed out, give the new user a full background of the what/why and leave the how out.

When all menus are opened, it is a mess to know where to go next.

Didn't want to step on any toes. Figure it is better to ask ahead of time than to ask for forgiveness after the fact.

[klonos]

Also, check the site out the BackdropCMS.org site on mobile with regard to where the menus end up (bottom).

Yep, I've filed https://github.com/backdrop-ops/backdropcms.org/issues/292 some time ago about that.

(Is this where I am invited to no longer work on documentation?)

😄 I doubt that this will ever happen for either you or anybody else. At least not for making suggestions and having a constructive conversation about improving the website and documentation.

[klonos]

I like your suggestions about reworking the order of the user docs. It Looks great to me!

Same here. I might have a few suggestions/opinions of my own, but no time to elaborate on that right now. Other than the Handbook vs User Guide (on which matter I'm with @jenlampton by the way), everything else seems like a very reasonable improvement to me. Go ahead!

[tomgrandy]

Thanks @klonos for your feedback and encouragement.

I look forward to hearing your suggestions/opinions whenever you have time.

[klonos]

Didn't want to step on any toes.

You are not stepping on any toes - you are helping a big deal.

Figure it is better to ask ahead of time than to ask for forgiveness after the fact.

We do both in Backdrop-land. If something is well-intended, it simply does not matter.

[tomgrandy]

@quicksketch - I'm assuming you are running a caching server. What is the refresh on that?

[olafgrabienski]

@tomgrandy - Do you intend to write a section about using Backdrop in other languages (localization)? Didn't saw it in backdrop-ops/docs.backdropcms.org#196. In my opinion we should add such a section, and I'm interested to help.

And regarding your outline proposal: Would such a section fit under "Basics" or better under "Extending functionality"?

[quicksketch]

@quicksketch - I'm assuming you are running a caching server. What is the refresh on that?

It should just be following the Backdrop cache settings, which I believe is a 5 minute cache.

[tomgrandy]

My apologies for being AWOL lately. Have been extremely busy at work trying to get a couple sites launched and wanted to get them finished so I could come to BadCamp without workplace baggage following me.

So, it doesn't look like I made my "by BadCamp" self-imposed deadline of getting the User Guide completed. Will work on it tonight and on my way to BadCamp if Frontier's onboard WIFI is decent.

Hope the summit went well today.

[tomgrandy]

@olafgrabienski - I know next to nothing about Backdrop in other languages and welcome the help. Would extend the audience of those who don't create sites in English only. And with regard for if it best fits in Basics or Extending Functionality, I'm thinking Extending Functionality might be the place.

[tomgrandy]

@docwilmot @Graham-72 @jenlampton @klonos

Sitting in an airport waiting for my flight to San Francisco so have been working on the site.

Would like to use a standardized Style Guide. Please look over the this page and see if it fits what you have in mind for keeping the documentation similar:

https://backdropcms.org/user-guide/website-style-guide

It doesn't really belong with the /user-guide/ but I can't change the URL.

Thanks!

[docwilmot]

Looks good. Re callouts, we could use different classes of callouts, like "pro tips" vs "important!" etc. These would need to be styled differently. Should this style guide reflect that? Hope you understand.

[tomgrandy]

@docwilmot - I was referring to just the text field "Callout" on the documentation page which doesn't look like I can add classes to the field. Are you referring to using Callouts within the body itself to draw attention to differentiated levels of difficulty?

[docwilmot]

Ok didn't realise. I'm sitting in a healthcare conference on my phone myself, so didn't check. But yes, that's what I meant. I think there were styles in ckeditor for callouts off that sort already, I think. What's your opinion on those?

[tomgrandy]

@docwilmot - There is an item in the Styles menu named "Callout" but it doesn't do anything that I can tell. Perhaps @wesruv can shed some light on that one.

[olafgrabienski]

@tomgrandy Alright, I'll try to write about using Backdrop in other languages. (Due to my modest English language skills it'll need some proofreading.) Currently I'm pressed for time, can't start immediatly but will come back to it soon.

And how would the collaboration work technically? Do I need a particular role on b.org to edit the User guide?

[tomgrandy]

@olafgrabienski - I would be happy to copyedit anything you put together. As for what role you need, do you currently have access to edit the backdropcms.org site?

Also, would the accepted term be Multilingual Sites?

[olafgrabienski]

@tomgrandy Re edit access: No, I don't think so.

@jenlampton May I get a role on backdropcms.org that allows me to edit the User guide?

[tomgrandy]

@olafgrabienski - My mistake. You mean localization of Backdrop making the CMS administration in other languages, correct?

[tomgrandy]

https://backdropcms.org/user-guide/backdrop-other-lanuages

[olafgrabienski]

@tomgrandy Yes, localization. Btw, typo in link: "lanuages"

[olafgrabienski]

@tomgrandy Had a quick look at the Website Style Guide. Sorry to say, but I'm still not convinced of the styles which mimic the UI. As I said in backdrop-ops/docs.backdropcms.org#196, these styles aren't very readable in a text. What do you think about it?

[tomgrandy]

@olafgrabienski I do like the italics best. With screenshots, I can ensure that most of what people are reading is better understood by combining text explanation with images. Currently, the User Guide uses many styles and would like to agree that we use either use the UI-type styles or we don't. Whatever needs to be consistent across the board. If we can get some agreement that would be ideal so I can correct it as I go through putting screenshots in place.

[tomgrandy]

@olafgrabienski @jenlampton Here is a page that uses only text, italics, bold, links, and screenshots to explain what options are available on a Content Form. Does this look less busy? https://backdropcms.org/user-guide/content-form

[docwilmot]

You forgot to post the page?

[klonos]

@olafgrabienski with regards to being able to edit documentation, I just granted you the "editor" role which should give you permissions to do that. Let me know if that works for you.

With regards to proofreading, I will do my bit as time permits and with regards to the multi-lingual topics of the User Guide, I can also help.

Now, as for the styles, sorry but I am with @tomgrandy and the others on that one. I think that having the text that refers to buttons and navigation for example resemble the respective default admin UI elements helps a great deal. Especially for people that do not need to read the fine lines and are simply looking for something to quickly go through. This way, the entire, detailed literature is there for beginners, but the more advanced users that are looking for quick tips can get the info they need in a fast read through.

[klonos]

@jenlampton, now that we have a small number of people editing the documentation nodes, should we prioritize https://github.com/backdrop-ops/backdropcms.org/issues/240 ??

[klonos]

...also, should we add some more options in the "Status" field of documentation nodes? I was thinking a "Needs proofreading" and "Needs screenshots" for starters. Also, perhaps convert it into a checkbox list instead? ...or replace it with a taxonomy term field that has tags similar to the issue labels here on GitHub?

[tomgrandy]

@docwilmot - Sample page = https://backdropcms.org/user-guide/content-form

@klonos - Great idea for Status field and thanks for setting up @olafgrabienski !

@olafgrabienski - Languages, geez. Looks like you or someone corrected it for me.

Just got into my house for Bad Camp tomorrow. Long day. Need sleep. Will write more tomorrow.

[olafgrabienski]

@klonos @tomgrandy Thanks for your replies and setting up the role on b.org. I'm more or less offline this weekend, will try and answer monday or tuesday.

[tomgrandy]

Whoa! Diff Module is now available in Backdrop as of Oct 22?

@Graham-72 / Thanks! Will put it on my sandbox and see if we can use it on B.org for tracking changes to documentation. Would make me feel a lot better about having a history of what was changed in case someone wants it returned to a previous version.

[Graham-72]

@tomgrandy - sorry, a bit premature, there is a problem with my porting, and in trying to solve one thing I have introduced another problem. Rather embarassing and a bit frustrating after seeing it start to work!

[tomgrandy]

@Graham-72 - No worries! Got my attention there. Already installed and scratched my head a bit. Will uninstall and wait for your new and improved version. Still, thanks!

[klonos]

@Graham-72 👍

[tomgrandy]

@jenlampton As I put the screenshots into the User Guide, can I have access to enable an image to use Colorbox as a style? I can do it on my sandbox, but don't have enough permission to customize it on BackdropCMS.org.

Could we give you a Style, like we have for the navigation links and submit buttons, maybe?

Will be traveling tomorrow and could be working in the airport while I wait.

[jenlampton]

can I have access to enable an image to use Colorbox as a style? I can do it on my sandbox, but don't have enough permission to customize it on BackdropCMS.org.

Tell me what you need @tomgrandy. What did you do on your dev site so you could use it?

[wesruv]

There is an item in the Styles menu named "Callout" but it doesn't do anything that I can tell. Perhaps @wesruv can shed some light on that one.

@tomgrandy It sounds like we want to style callouts so they have a little more visual dominance than the rest of the copy? If there's a link with an example I can whip something up! Or let me know if I'm not understanding the question?