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
• Modules themes and layouts
• Nodes and Entities
• Understanding Layouts
• Blocks
  • Configuring blocks: examples
• Content types
  • Create a custom content type
  • Add fields to a content type
• Display settings (View modes)
• The Admin bar
• Menus
• Project installer
  • Updating project code (combined with Installer documentation)
• Taxonomy and categorizing content
• Users, roles and permissions
• Views basics
  • Views exercises
  • Configuring Views - advanced
  • Configuring Views
• Installation
• Themes
  • Color
• Creating content
• Multilingual
  • Regional settings
• Configuration Management move to developer docs
• Multisite move to developer docs
• Ckeditor
  • Filters
• Book
• Comment
• Contact forms
• Fields
  • Date
  • File
  • Image
• Pathauto
• Tokens
• Search
• Redirects
• Account settings and emails
• 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

[Graham-72]

@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]

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]

@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:

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

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]

Seems right. What do we do next?

[tomgrandy]

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]

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:

[tomgrandy]

Now that I have finished up reading backdrop-ops/backdropcms.org#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:

• 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!

[wesruv]

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" [email protected] wrote:

Now that I have finished up reading backdrop-ops/backdropcms.org#55
backdrop-ops/backdropcms.org#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
#196,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AFWPRBTb5CyzLJaUOIcwE4xXVekxzWGfks5quVAkgaJpZM4I4c22
.

[olafgrabienski]

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]

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]

@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]

@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]

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

[Graham-72]

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]

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:

• docs can be marked for intended audience
• we can have a "browse site-building topics"/"browse content authoring topics" filter that "personalizes" that list for the current viewer.
• perhaps also include a difficulty rating in there somehow? Like allow people to vote by selecting the roles that describe them best and then a 5-star rating (with an optional feedback text field in order to see which parts of the documentation need to be improved).

[klonos]

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]

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]

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" [email protected] 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
#196,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAYSR-vCoaIhRo6wPnhZnTg3xk_MrEFAks5qutYMgaJpZM4I4c22
.

[docwilmot]

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 @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
• @wesruv @klonos create screenshots (you've both volunteered before right?) as we go along. We dont need to wait for them.
• @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.
• Once we've argued enough (a day or two, no more), I'll paste that TOC on the current doc landing page and create the actual links
• We go live once @jenlampton clicks the button. I'd recommend we push live and fix as we go along.

[tomgrandy]

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]

@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]

@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:

[tomgrandy]

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]

@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]

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

[tomgrandy]

@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]

@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]

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]

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

[docwilmot]

@tomgrandy now that we're at 102 comments on this issue, maybe time to take stock? What are we doing right now? Whats left to plan and to do?

One of the main issues I see is that we have 24 really big topics which will each need screenshots; hows that going to work out? I would suggest we tackle a few topics at a time, and you let us know which screenshots you need and we divvy them up; otherwise this will be forever.

re Does this look less busy? #196

Yes it does look better; I think I would side with @olafgrabienski and say the current formatting is too distracting (the black background on the breadcrumb "Navigation style" especially). Your style guide looks great without that.

I think we should next agree quickly on the Style Guide (I vote to nix the navigation background though).

I also would suggest that we make side issues for things like adding Diff and Colorbox and Languages and so on and get these done in parallel or ideally later, as we seem to be bogging down a bit. Lets stick to this issue which is just creating great docs which have been proofread by somebody and ready to post. We can decorate and embellish later IMHO.

In summary, could we limit this issue to:

• do we have all the articles we need
• are they in the proper categories/hierarchy
• do we have proper landing pages for users to browse
• are they proofread and simplified and acceptable to @tomgrandy to mark complete

I think once those are satisfied, we can publish so our users can at last get some docs.
Perfect is the enemy of good

[tomgrandy]

@docwilmot - Didn't mean to muddy the waters. But at the same time, didn't want to have to go back in and change all the screenshots if we were going to use a method that would allow people to see the details of images (duplication of effort).

I will change the Style Guide to keep the text simple.

I will mark complete those pages I have proofread.

I will change the hierarchical order of the pages to match the outline

Feel free to start posting screenshots on pages. Try to keep them at a consistent 600px wide.

As for making side issue, all for it, but don't know this well enough to start them in the right place. If you could make one for diff, I'll make one for colorbox and languages based on the diff that you start.

Other than that, my plan was to continue moving through the context and uploading screenshots as I do what the user guide explains to ensure it is correct with the latest version.

Hope that sounds like a plan.

[docwilmot]

@tomgrandy we all muddied the waters, not you. The summary of my rant above is essentially: lets get the text ready first.

The other stuff doesn't have to be parked, but let's leave them as secondary since we could have a perfectly good user guide without images, colorbox, diff and else.

For example @klonos could create the screenshots you need at full size and store them labelled in GDocs in folders corresponding to the articles, until Colorbox is ready, then himself or you and/or someone(s) else can insert them then. Same with Diff: @jenlampton can just make sure that revisions are enabled, until Diff is ready, then she can install and plug it in.

But for now we just fix the text.

Hope you understand what I mean?

[olafgrabienski]

@klonos Thanks for the editor role. Just tested it quickly, works fine so far!

[tomgrandy]

@jenlampton - Having no success getting inline images to open in Colorbox.

Works great with attached images Manage Display / Image / Format = Colorbox

Not working on the inline images. Since most of what I will be doing is multiple inline images in a page of instructions, am scrapping the idea of utilizing Colorbox at this point.

Sample here:
http://stockpotstudio.com/colorbox-test

Seemed like a good idea.

[jenlampton]

There may need to be some colorbox/ckeditor integration we need to add.

[tomgrandy]

@jenlampton - As mentioned in today's meeting, please change the "previous" and "next" navigation link at the bottom of each page stay at the top level and not go into the secondary-level Deep-Dive sections.

[tomgrandy]

@jenlampton - Also, you currently have Status tags of Incomplete and No Known Problems. Do we want to have tags like "Beginner" and "Advanced" as Gregory pointed out in today's meeting?

[jenlampton]

@tomgrandy Level field added, see: https://backdropcms.org/user-guide/creating-new-content-type Working on the next/previous links now.

[jenlampton]

@tomgrandy next/previous links modified to ignore child pages: https://backdropcms.org/user-guide/content-types

[tomgrandy]

@jenlampton - Adding "Introduction" or "Advanced" tags to all pages and the Next / Previous links are so much more logical for moving through the basic documentation. Big thanks!

[tomgrandy]

Only two more sections to go and the User Guide is complete. Would someone be willing to review and put any necessary screenshots (500px wide) on this page:

https://backdropcms.org/user-guide/project-installer-and-updates

This is one that doesn't seem to follow the current version or is missing in the version I have installed.

Thanks!

[jenlampton]

Yeah, if your filesystem is not writable you won't be able to install
modules.

---

Jennifer Lea Lampton
Jeneration Web Development
Backdrop CMS & Drupal
www.jeneration.com

On Thu, Nov 10, 2016 at 4:56 PM, Tom Grandy [email protected]
wrote:

Only two more sections to go and the User Guide is complete. Would someone
be willing to review and put any necessary screenshots (500px wide) on this
page:

https://backdropcms.org/user-guide/project-installer-and-updates

This is one that doesn't seem to follow the current version or is missing
in the version I have installed.

Thanks!

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#196,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAYSR7UfaEHmhdRGpoPqY7cy7w-5EXeWks5q870pgaJpZM4I4c22
.

[tomgrandy]

Filesystem is writable and I can install modules easily (love it).

I'll go through the project-installler-and-updates again, but something doesn't match.

Oh, and @jenlampton , you might want to remove your phone number from the comment above.

Unless you want it there.

[tomgrandy]

I see where the page falls through the cracks for me.

It is an excellent description of "how" the project installer works at the beginning, in great detail, that a person who needs to know "how-to" would not be looking for.

Would it be okay for me to rewrite the page with the "how-to" install modules, themes and templates without explaining the magic behind scenes:

The explanation of what is happening, though impressive, is confusing if this is aimed at someone who is new to CMS and Backdrop in particular.

It would make a great deep-dive, but not a how-to.

Make sense? Here I was looking for a Project Installer. That term does not appear anywhere in the admin bar, hence the confusion that I didn't have it. I did, however, find that Project Installer (the module) is enabled by default. I now understand why I was confused.

[jenlampton]

Yes, please go ahead :)

• Please excuse brevity and typos. Message typed with my thumbs from an Open
  Source OS.

On Nov 10, 2016 5:55 PM, "Tom Grandy" [email protected] wrote:

I see where the page falls through the cracks for me.

It is an excellent description of "how" the project installer works at the
beginning, in great detail, that a person who needs to know "how-to" would
not be looking for.

Would it be okay for me to rewrite the page with the "how-to" install
modules, themes and templates without explaining the magic behind scenes:

"Installer is closely coupled with the several core and remote components
and requires online access to work. The main remote service is BackdropCMS’
Project Browser Server which communicates with Installer and serves lists
of available projects for download. The following diagram illustrates the
connections between the components required for a working Installer."

The above is confusing if this is aimed at someone who is new to CMS and
Backdrop in particular.

It would make a great deep-dive, but not a how-to.

Make sense? Here I was looking for a Project Installer. That term does not
appear anywhere in the admin bar, hence the confusion that I didn't have it.

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

[olafgrabienski]

@tomgrandy Good to hear of the progress! At the moment, it makes no sense to update my page on Using Backdrop in different languages than English, because it's already difficult to install Backdrop in other languages, see backdrop/backdrop-issues#2329.

I however want to come back as soon as possible to the topic but was wondering if the relevant page of the user guide has been deleted. Can't find it anymore.

[docwilmot]

@tomgrandy had a look at the progress so far, great work, hats off to you sir.
Do we need to consider section anchor links for the long pages? In case someone needs to link to the Contexts section within Deep Dive: Advanced Layout Options for example. We have some really long pages.
Is there anything we/I need to do to help finish?

[tomgrandy]

@jenlampton - I'll remake the page and put the background information on a deep-dive page if someone wants to peek behind the curtain.

@olafgrabienski - Sorry to hear the Backdrop in different languages isn't quite ready for prime time. I did delete the page out of documentation so an empty page wasn't appearing in the menu now that the User Guide is about to go live. Don't have the option to put something in an unpublished state. When you get it working, let me know and I'll put a new page back in. Thanks!

@docwilmot - Thanks! I'll take a look at the length of pages and see if I can break them up a bit. If not, anchor tags would be a good option. The Deep Dive pages are probably more apt to need something like this. I'm hoping to finish the guide this weekend so it can be released to the wild. Once I have it in what I think is a finished state if you wouldn't mind giving it a review for anything I may have missed and if you are willing to put the anchors on pages you feel are too long that would be awesome.

[klonos]

Oh, and @jenlampton , you might want to remove your phone number from the comment above.

Unless you want it there.

Yeah, don't think she noticed your comment @tomgrandy and I don't think she wants it there, because IIRC it was @quicksketch that was faking to add that to a node or something during the BADCamp training and from her reaction, I gather she was not into it 😄 ...removed that for you @jenlampton (but feel free to add it back in case you had it there intentionally)

[klonos]

...not sure I can make time for proofreading before you guys get to publish the docs, but I'll do that anyways at some point. Will also try to make time for screenshots, but cannot promise.

@tomgrandy had a look at the progress so far, great work, hats off to you sir.

...second hat off here 👍

I like the status indicator for incomplete documentation, but I think that it would be great to have a way for people (the regular, unregistered site visitors that read through it) to provide feedback in the form of "requires update" or "inaccurate" or even "typo" along with a short text like "I see no xyz button like the screenshot in the documentation". If that came out as an email to say @docwilmot, @tomgrandy and myself (the "documentation squad" + the "screenshot guy") so that we can take action, then that would be great ...I mean if the rest of the gang does not object to receiving such notifications and provided we get some decent anti-spam measures in place.

[tomgrandy]

Documentation is now live on BackdropCMS! Very cool.

I'm still not 100% sure that I like the images maintaining a width of 600px because they are hard to read. Does anyone else think that is the case? If so, I can try bumping them up to 700-750px but then the question becomes how much real estate are we willing to dedicate to representing the interface or is it good enough as is?

It would be easy for me to blow through documentation and resize to a consistent width that is easier to read since we cannot click to view the image.

If anyone else doesn't have additions / corrections, should we close this issue?

[docwilmot]

Congratulations Backdrop!
Well done @tomgrandy
Have completely abandoned colorbox?

[jenlampton]

Colorbox is still on the table. We should figure out how to set that up for contrib anyway.

[alexfinnarn]

I'm not sure where to put this, but in backdrop-ops/backdropcms.org#55, PHPStorm was mentioned. PHPStorm is a HUGE part of my DX and helps me catch a lot of bugs before I even run the code.

In backdrop/backdrop#2244 (comment), the multiline comment vs. docblock is easily noticable and the IDE helps to generate the docblock if one doesn't exist.

There is also a place to define code syntax standards. I often times select all and then automagically reformat things to Drupal's standards.

https://www.jetbrains.com/buy/opensource/ Apache Foundation licenses.

[jenlampton]

@alexfinnarn we have a few PHPstorm licenses available for contributors to Backdrop for free. Anyone who is interested should email [email protected] for a license key! (Though this is not really relevant for this issue -- on user guide topics, since those docs are for non-coder instructions)

[oadaeh]

Also, as an FYI, NetBeans can do the same things Alex said PHPStorm does. I suspect many IDEs can, if properly configured.