search

backdrop-ops / docs.backdropcms.org

Website for displaying Backdrop CMS documentation and API source code.
https://docs.backdropcms.org/
6 stars 6 forks source link

User guide topics #196

Open docwilmot opened 8 years ago

docwilmot commented 8 years ago

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.

Graham-72 commented 8 years ago

@docwilmot How do you envisage we should structure our comments so that we can organise any debate? Could perhaps the first person to contribute a comment (or addition or amendment) on one of the above items start a new issue for that specific item? Issue backdrop-ops/backdropcms.org#55 has served us well but has become unwieldy and it would be a shame if this new issue were to be a catch-all.

docwilmot commented 8 years ago

I'd say if you have recommendations about the list itself, or the process, then post here (or start a new issue if you feel it may generate some discussion or is ultimately resolvable), but if youre critiquing a particular doc, then post a new comment issue, link to this, and tag it documentation.

Edit: I meant post a new issue, not comment

tomgrandy commented 8 years ago

@docwilmot - The api.backdropcms.org has an audience, but not the one I’m looking to narrow in on.

The main BD User Guide: https://backdropcms.org/user-guide seems to be aimed at the site builder primarily and overlaps with skills the site user needs to know as well.

The handbook’s Developer Guide: https://backdropcms.org/requirements (beginning here) are still needs of the Site Builder and carries over into the Site Developer category

Not trying to muddy the water, but I see four distinct audiences here:

Would you agree? Are there other audiences we are not addressing?

I might be stating the obvious, but want to define the audiences first.

docwilmot commented 8 years ago

Seems right. What do we do next?

tomgrandy commented 8 years ago

Next would be to identify how to separate the four so, as they visit the backdrop.org site, they can easily identify what they need by what role they identify with. Should there be a User Guide for a Content Editor, a Site Builder, and a Site Developer as well as an overview for Site Evaluators? Though we may know these roles by title, would your new user be able to self-identify by role? If not, is it worth considering labeling them something different or guiding them to an area by identifying their particular need?

docwilmot commented 8 years ago

The developer docs should stay on the API site in proximity to the generated API info; that seems logical.

It may be best to guide the others by their need; particularly, we should plan the landing page at https://backdropcms.org/user-guide in a format which asks what you want to do, and link to the individual docs or subsections of the docs. Perhaps link from the landing page to sub-landing-pages as well.

See the Wordpress landing page for example: 351d9ae2-bf57-11e5-8fe5-f7aa04d2d881

tomgrandy commented 8 years ago

Now that I have finished up reading https://github.com/backdrop-ops/backdropcms.org/issues/55 it looks as if June 15-17 were stellar days for documentation! Much of this seems to have been hashed out before and there have been many iterations of documentation floating with some of it landing on B.org.

Top down, given that this is a small group and to ensure that any documentation that goes on the site is concise, complete, and current, you have a conundrum on your hands: either so simple that documentation is not helpful or so instructional that it must be constantly updated to maintain relevance.

However, in my opinion, if you want to draw in new people, you need a little investment in handholding to make them converts.

Looking through the documentation that has been created, a great deal of work has already done and now it is a matter of how to present it in a logical fashion.

I do like the idea of starting simple and growing in complexity as you have shown above in your WP example. Screenshots are a must, but they can get dated as well. Videos are wonderful, but again, they get outdated but there are multiple learner types out there and a growing group are YouTube learners.

As a newb, I would probably need to know in this order:

ADOPTER NEEDS:

GETTING STARTED

CONTENT EDITOR

SITE DEVELOPER / BUILDER

DESIGN/UX TEAM

CONTRIBUTORS

ADVANCED DOCUMENTATION

Just a few thoughts before eating lunch!

wesruv commented 8 years ago

Let me know if any graphics are needed to explain something in docs, I can whip up some stuff.

On Sep 27, 2016 1:19 PM, "Tom Grandy" notifications@github.com wrote:

Now that I have finished up reading backdrop-ops/backdropcms.org#55 https://github.com/backdrop-ops/backdropcms.org/issues/55 it looks as if June 15-17 were stellar days for documentation! Much of this seems to have been hashed out before and many iterations of documentation floating with some of it landing on B.org.

Top down, given that this is a small group and trying to ensure that any documentation that goes on the site is concise, complete, and current to the most recent version of BD, you have a conundrum on your hands: either so simple that documentation is not helpful or so instructional that it must be kept updated to maintain relevance.

Looking through the documentation that has been created, there is a great deal of work already done and now it is a matter of how to present it in a logical fashion.

I do like the idea of starting simple and growing in complexity as you have shown above in your WP example. Screenshots are a must, but they can get dated as well. Videos are wonderful, but again, they get outdated. Most of the above WP outline I would never read.

As a newb, I would probably need to know in this order:

ADOPTER NEEDS:

  • What is BD?
  • Why should I choose BD for my organization?
  • What advantage is there to using BD?
  • What features are included with BD on install?
  • How can I extend BD?
  • BD showcase...
  • Video Overview

GETTING STARTED

  • Download and Install of BD
  • Converting D7 Sites to BD
  • Installing Modules
  • Installing Themes

CONTENT EDITOR

  • Logging In
  • Creating Content
  • Admin Bar
  • BD Video Lessons (Keeping it super general)

SITE DEVELOPER / BUILDER

  • Creating Content Types
  • Working with Layouts
  • Blocks
  • Users, Roles, and Permissions
  • Taxonomy
  • Menus
  • Forms
  • Images
  • File System
  • URL Alias
  • URL Redirects
  • Building a View
  • BD Video Lessons (Very Specific)

DESIGN/UX TEAM

  • How To Create a BD Theme (Best Practice)
  • How To Create a BD Layout (Best Practice)

CONTRIBUTORS

  • How to port a module to BD
  • How to create a BD module
  • BD Video Lessons

ADVANCED DOCUMENTATION

  • Terminology
  • Backdrop API
  • Coding Standards
  • Writing Secure Code

Just a few thoughts before eating lunch!

— You are receiving this because you are subscribed to this thread. 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/AFWPRBTb5CyzLJaUOIcwE4xXVekxzWGfks5quVAkgaJpZM4I4c22 .

olafgrabienski commented 8 years ago

I see four distinct audiences here:

Evaluators who want to know what BD has to offer them, Site Users who need to know the basics of how to create content in BD, Site Builders who need to know how to install BD and create a site, and Site Developers who need to know how to install, customize, convert, and upgrade a site.

In my opinion, it's not easy to distinguish between Site Users (or Content Editors) and Site Builders. If a prospective Content Editor (for instance a blogger) installs Backdrop him/herself, he or she may do some basic site building before posting content.

Another issue to consider: When Site Users / Content Editors use a page which was built by a Site Builder, we don't know how the site was customized. Example: the Site builder replaced the content types "Page" and "Post" with custom ones. Ideas how to manage that?

jackaponte commented 8 years ago

Jumping in briefly to say--as a site builder who primarily builds sites for site users/content editors who never do site building, I think that the audience distinctions are important to preserve there! Luckily we can certainly anticipate and account for overlapping audiences in our approach here.

tomgrandy commented 8 years ago

@olafgrabienski - Like you, I am someone who wears many hats when it comes to creating new sites for my company. So the overlap is a worthwhile concern as are customizations in naming conventions that a site builder / developer may choose for the content types. Therefore, it is important that we keep the documentation general to a point.

For example, if we identify a Page as a Content Type and use it as the basis for describing how to create a new Content Type, it is somewhat implied that Content Types are unlimited in their customizations and naming. Page is just one sample Content Type that is preloaded.

@jackaponte - Would you agree that the audience distinctions need to be preserved, but not necessarily named in our documentation? As we write the documentation in a hierarchy from simple to complex, we may have the roles in mind as we write. For example, when we are documenting the basic fields to be populated in a Page, we are considering the user as a Site User. These audiences help us keep their distinct needs close together in the documentation to keep them from having to wade through documentation that does not pertain to them to find the next step.

Therefore, I'm proposing we that we not use the named audience type in the subtopics, but keep them in mind when grouping topics for that audience.

For example instead of:

CONTENT EDITOR

Logging In Creating Content Admin Bar

The documentation would read:

CREATING CONTENT

Logging In Creating Content Admin Bar

Though as writers of the documentation we recognize who the audience is: Content Editors.

Make sense?

@jenlampton @docwilmot - In the past has documentation gotten bogged down in the details such as these? Would it be better to forge ahead so there is some documentation out there instead of promising that it is coming soon?

jackaponte commented 8 years ago

@tomgrandy, thanks for your detailed reasoning above!

Therefore, I'm proposing we that we not use the named audience type in the subtopics, but keep them in mind when grouping topics for that audience.

After reading your post, that sounds right to me.

In the past has documentation gotten bogged down in the details such as these? Would it be better to forge ahead so there is some documentation out there instead of promising that it is coming soon?

I agree that we should definitely avoid making the perfect (which is subjective and therefore unachievable) the enemy of the good--we can always edit and reorganize existing documentation later!

tomgrandy commented 8 years ago

@jackaponte - You are welcome and thanks for the feedback!

Graham-72 commented 8 years ago

I had a look the other day at the section called 'Quick Start Guide' https://backdropcms.org/user-guide/quick-start and added some screenshots.

I think this section is just about what is needed to get new site-editors started.

Almost certainly it would need to be supplemented by some website-specific documentation, produced by the site designer/developer. For example, the site might use a theme that makes it look rather different.

klonos commented 8 years ago

Luckily we can certainly anticipate and account for overlapping audiences in our approach here.

We can organize topics in an order that seems more reasonable as a workflow and have an "audience" taxonomy tag that is a multi-select checkbox. That way:

klonos commented 8 years ago

For example instead of:

CONTENT EDITOR

Logging In Creating Content Admin Bar

The documentation would read:

CREATING CONTENT

Logging In Creating Content Admin Bar

I think that task-based documentation is better than audience-based too. The intended audience should be a documentation property (tag) - not defining the order/categorization of topics. It could be used for filtering topics. ...OR, we could offer two ways to browse documentation: one by tasks and one by audience.

klonos commented 8 years ago

I agree that we should definitely avoid making the perfect (which is subjective and therefore unachievable) the enemy of the good--we can always edit and reorganize existing documentation later!

It is the enemy of done - not of good 😄

jenlampton commented 8 years ago

audience info should be hidden. People don't often self-identity, and if they do they are likely to draw the lines in different places than we do (for example, @docwilmot and @klonos still claim they are not coders). Audience labels could end up causing more harm than good.

Audience should be important for us to think about while building, but should not be important for those using the docs when we are done.

On Sep 28, 2016 3:03 PM, "Gregory Netsas" notifications@github.com wrote:

I agree that we should definitely avoid making the perfect (which is subjective and therefore unachievable) the enemy of the good--we can always edit and reorganize existing documentation later!

It is the enemy of done - not of good 😄

— 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/AAYSR-vCoaIhRo6wPnhZnTg3xk_MrEFAks5qutYMgaJpZM4I4c22 .

docwilmot commented 8 years ago

Would it be better to forge ahead so there is some documentation out there instead of promising that it is coming soon?

Yes. Yes, indeed. We already have several docs which are reasonably ready to publish IMHO. I would suggest next steps:

tomgrandy commented 8 years ago

Audience should be important for us to think about while building, but should not be important for those using the docs when we are done.

@jenlampton - I agree that audience is important when approaching each topic area for it will guide the terminology used there to ensure that readability is recognized. Since there is so often an overlap in what we do (some wearing all hats) in smaller shops, it would be difficult to separate the titles. However, a hierarchical order of difficulty can be adhered to.

tomgrandy commented 8 years ago

@tomgrandy @jackaponte and anyone else go over the existing docs once more to ensure no glaring errors. Document (anywhere) any errors (we can fix immediately) any omissions (missing topics) (perhaps just add to the checklist in the first post) any recommended improvements to the text

I'll go through the documentation and install Backdrop following the step-by-step and look for anything that is missing. I have installed it, but not with documentation, so will do so from scratch with my newb hat on. then go through the how-to portions to see if there are errors.

@tomgrandy propose a landing page TOC and any sublanding page in the style of the WP with annotations to show which docs your headings should link to. We'll argue about it briefly.

Will put this together for discussion purposes and, hopefully, publication.

Let's do this!

wesruv commented 8 years ago

@docwilmot @klonos re:graphics

I specifically mean graphics that are used to describe abstract concepts, e.g. if we wanted a diagram that explained the flow of content from how it's stored in a node to view mode display settings to template... or something 😛

Like these things I just made for a Lullabot article: vh

viewport-height

vmin

vmax

tomgrandy commented 8 years ago

Nice work! Screenshots are excellent for what already exists (especially as animated gifs to show quickly where something is located or how to do a simple task. However, abstract concepts would require graphics and by what you have shown above, you have the mad skills to make it happen!

tomgrandy commented 8 years ago

@docwilmot or @jenlampton

Do we follow a particular style guide with regard to text used on the website? AP, Chicago, Gregg ??

Also, have you adopted styles for use of capitalization in Titles and Callouts?

Lastly, are we using American English, British English, or International English?

My Virgo attributes are showing, I know, but want to make sure I don't have to backtrack here.

docwilmot commented 8 years ago

I vote that we allow @tomgrandy to make this decision on our behalf. Especially since I have no idea. 😄

tomgrandy commented 8 years ago

@docwilmot - That is mighty kind of you! I think I'll refer to the AP Style Guide if I have a question regarding use since it is the standard for journalists worldwide.

Also, I'll create what is called a House Style Guide as I go. A House Style Guide documents the styles adopted for a particular website so it maintains consistency across the board.

Also, let's use to American or International English since those seem to be adopted by most international corporations with regard to their web content.

I'll post a link to the House Style Guide as soon as I have enough listed.

Two examples, based on reviewing how other sections on the website were created, are:

Titles

  1. Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions.
  2. Lowercase articles (a, an, the), coordinating conjunctions, and prepositions.

Sample: “Add-ons: Modules, Themes, and Layouts”

Callouts

  1. Capitalize first letter and proper nouns.

Sample: “Handbook for help with how to install Backdrop CMS”

tomgrandy commented 8 years ago

@docwilmot - Question regarding the Quick Start Guide followed by the User Guide.

There seems to be a great deal of repetition between what is presented in the Quick Start and then presented again in the User Guide sections. It is confusing to read and then re-read the same later in the documentation. Would it be better for flow to keep the content listed once in the order presented?

IMHO, much of the Quick Start material should be presented in the section(s) it pertains to so not to cause confusion to the reader.

docwilmot commented 8 years ago

I feel the quick start is meant as a comprehensive but very low level overview. A pamphlet, rather than a booklet or a thesis. @Graham-72 particularly liked this.

tomgrandy commented 8 years ago

Got it! Just wanted to ensure we weren't being overly repetitive.

klonos commented 8 years ago

@docwilmot @klonos re:graphics ...

I'm all for graphics @wesruv 👍

I vote that we allow @tomgrandy to make this decision on our behalf. Especially since I have no idea. 😄

I vote yes to that too. Especially since I don't have any idea + no time either 😄

Titles

  1. Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions.
  2. Lowercase articles (a, an, the), coordinating conjunctions, and prepositions.

Sample: “Add-ons: Modules, Themes, and Layouts”

Callouts

  1. Capitalize first letter and proper nouns.

Sample: “Handbook for help with how to install Backdrop CMS”

👍 ...plus may I add that we should use proper capitalization for acronyms and also respect the capitalization that a certain product uses. So, "AJAX" (not "Ajax" or "ajax"), "jQuery" (not "Jquery" or "jquery") and "GitHub" (not "Github" or "github").

klonos commented 8 years ago

...I would also say use italics for words withing sentences that are specific named parts of the UI. For example:

Go to the Manage blocks page and click the Add block button on the Header region ... click the Save configuration button.

...but:

To add menu items to the primary navigation menu of your website, use the Admin menu at the top of the page and navigate to Structure > Menus > Primary navigation > Add link

...or:

To edit a page or post, click the Edit option available in the primary tabs section below the page title.

Notice how the "primary navigation menu", "Admin menu", "primary tabs" and "page title" are not in italics. These are actual things (parts of the UI) that we refer to, but there is no such text (as a label for example) in the page that the user can see. For example, if the user uses their browser search function (Ctrl+F, F3 or Command+F) to search for "page title", there will be no result returned. On the other hand:

To customize the page title of your website, go to Structure > Layouts > Default layout > Manage blocks, then click the Configure button available in the Page title region.

...this time, the "Page title" part is in italics because it is an actual labeled thing on the page.

klonos commented 8 years ago

...eventually, I would like us to switch those italics to have it so that the documentation text that is referring to UI elements like admin menu links, dropbuttons and form submit buttons is styled to resemble the style of those elements. Something like this:

backdropcms org-awesome_docs-ui_elements_text_styled

klonos commented 8 years ago

...some might find this too flamboyant, but it would solve the problem of the documentation getting too "wordy" (because it is meant for beginners). As users progress to more advanced level of knowledge, they can simply skim through the documentation and scan for the parts that stick out 😉

jenlampton commented 8 years ago

These styles should already be options in the rich-text editor. Feel free to try them and see how it feels.

On Oct 1, 2016 6:34 PM, "Gregory Netsas" notifications@github.com wrote:

...some might find this too flamboyant, but it would solve the problem of the documentation gets too "wordy" (because it is meant for beginners). As users progress to more advanced level of knowledge, they can simply skim through the documentation and scan for the parts that stick out 😉

— 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/AAYSRx6DAB0k9YpeIeUS5_lMI_lo5bd0ks5qvwoegaJpZM4I4c22 .

klonos commented 8 years ago

These styles should already be options in the rich-text editor. Feel free to try them and see how it feels.

That is so cool! I didn't realize that has already been implemented. Thanx 👍

tomgrandy commented 8 years ago

Excellent editorial guides, @klonos ! Thanks @jenlampton for pointing out the styles are there.

olafgrabienski commented 8 years ago

I would like us to switch those italics to have it so that the documentation text that is referring to UI elements like admin menu links, dropbuttons and form submit buttons is styled to resemble the style of those elements.

Personally, I don't like the styles referring the UI elements:

I'd suggest to keep italics (most elegant), or to use bold (more clear imo). Following a short comparison:

jenlampton commented 8 years ago

The styles are less important if we also have a screenshot. We just shouldn't require people to actually read the all the text. If we can tell the story with a screenshot instead of styled text, that's fine. If we don't have a screenshot, we just need to make sure people can still find the information they need by scanning.

olafgrabienski commented 8 years ago

I'd like to give feedback to the new structured documentation if needed, but I'm not sure about the current status of the content-related tasks. Any updates?

serundeputy commented 8 years ago

508

tomgrandy commented 8 years ago

I've been editing the documentation for spelling, grammar, punctuation, and usage errors. My plan is to then go through step-by-step as a newb and see if the documentation makes logical sense in the order it is presented and take screenshots to be included as I move through it. Not there yet, but do want to get it done as soon as possible.

tomgrandy commented 8 years ago

@serundeputy - Are you referring to 508 Compliance?

Section 508, an amendment to the United States Workforce Rehabilitation Act of 1973, is a federal law mandating that all electronic and information technology developed, procured, maintained, or used by the federal government be accessible to people with disabilities.

serundeputy commented 8 years ago

yes

tomgrandy commented 8 years ago

I see Colorbox is a module that is available for Backdrop. Do you have it enabled on the Backdropcms.org site? It would be ideal for the screenshots I put in the User Guide to be clickable to open a larger version since some of the text in a screenshot gets rather small.

Something akin to this: http://www.alessioligabue.it/colorbox-image-load

tomgrandy commented 8 years ago

Also, are you documenting changes made to pages with notes in the Revision Information? I went through and looked at some revised pages, but do not see notes as to what was changed.

docwilmot commented 8 years ago

@tomgrandy we dont have colorbox, but it would probably be a good idea. That would be @jenlampton though. And revisions weren't on (except maybe on random nodes) since this was just the initial build. Now that you're actually revising, perhaps we should.

tomgrandy commented 8 years ago

@docwilmot - Thanks! Agree Colorbox would be nice to see screenshots better.
@jenlampton - Please advise if Colorbox is possible to allow for users to click on images to enlarge. @docwilmot - I have started to note what changes I've made to the User Guide in revision info.

jenlampton commented 8 years ago

Please advise if Colorbox is possible to allow for users to click on images to enlarge.

Yes, this seems like a reasonable request. I'll look into it on Thursday :)

klonos commented 8 years ago

...Also, are you documenting changes made to pages with notes in the Revision Information?

Related: https://github.com/backdrop/backdrop-issues/issues/1465

...for starters, we could port https://www.drupal.org/project/diff and install it on b.org, but ideally we should implement something like this in core (this is vanilla WordPress by the way):

wp-browse_content_revisions

tomgrandy commented 8 years ago

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. I've been putting general comments in and when I alter content, I paste that into the RI for reference.