Make the Developer guide more visible

[olafgrabienski]

when I was looking for the update/upgrade procedure just now on the new backdropcms site to make sure I had my terminology correct I didn't find it

The above support request on Gitter was about the important page https://backdropcms.org/upgrade. The page is part of the "Backdrop Developer guide" which is indeed not easy to find: It's only linked in the sidebar of the About page.

I guess, with the "User Guide" in the main menu, one would expect to find also the more advanced docs there. We could do the following for a better visibility:

• Rename the "Backdrop Developer guide" to "Developer Guide", if an own name is still needed (see in contrast my suggestions at the end of the post)
• Move the Developer Guide in the "User Guide" section, and place it alongside
• Link from relevant sections of the User Guide to the Developer Guide and viceversa

Actually I'm not sure if we should keep the Developer Guide and the User Guide separated at all. Why not integrate them? This is the structure of the current Backdrop Developer Guide:

• System Requirements
• Installation Instructions
• Upgrading Backdrop CMS
• Upgrading from Drupal 7
• Submitting Pull Requests

At least the first three items are important for a lot of users, not only "Developers" in the narrow sense, and should be integrated in the User Guide in my opinion.

[klonos]

@olafgrabienski I believe that we should be able to handle this much better (as in have more options) soon as we enable the main navigation to be rendered as drop-down menus. But, yeah, I agree that separating these tasks/topics from the user guide is not ideal. There are tasks that could very well belong to both the user guide and the dev guide. As a matter of fact, if you look at the screenshot of the "Sidebar Navigation" section in https://backdropcms.org/user-guide , you will see that a previous version of the sidebar block with the topics index included "System requirements" and "Installing Backdrop" in the User Guide.

I think that we should eventually have a single "Documentation" user guide with 3-4 main sections that progressively go from beginner to advanced topics. I envision these sections to be:

• Documentation -- Using this Guide -- Install Backdrop --- System Requirements --- Installation Guide --- ... -- Build your Site --- Add & Edit Content --- Create User Accounts --- Create User Roles --- Manage Permissions --- Create Menus --- Add Custom Content Types --- ... -- Extend --- Installing Modules --- Installing Themes --- Installing Layouts -- Contribute --- Register --- Donate --- Report Bugs --- Improve Documentation -- Develop --- Code Repositories --- Coding Standards --- Apply for the Contrib Group --- Creating Themes --- Creating Layouts --- Creating Modules --- Creating Pull Requests

...something along these lines that has a logic "evolution" from User to Site Builder to Web Dev.

[olafgrabienski]

if you look at the screenshot of the "Sidebar Navigation" section in https://backdropcms.org/user-guide , you will see that a previous version of the sidebar block with the topics index included "System requirements" and "Installing Backdrop" in the User Guide.

Good catch! Btw, do you know if there is an archived version of the old homepage (design)? Thinking about changes on the new homepage design I asked myself sometimes how the situation was before the relaunch and couldn't remember exactly.

[Graham-72]

Because we are developers of websites we tend to fall in to the trap of assuming that the first thing our users need to know is how to install Backdrop. Although this is true for many, I have long been an advocate of providing basic instructions telling a user how they can edit or add to content if they have been given responsibilty for looking after a website somebody else has built with Backdrop - the simplest and most basic situation.

Please make sure that this is always the first part of our User Guide.

[olafgrabienski]

@klonos Re structure for the User Guide: it was already discussed in the issue "User guide topics", cf. for instance backdrop-ops/docs.backdropcms.org#196 and following. I'm not sure if the current state of the User Guide on https://backdropcms.org/user-guide reflects that discussion and/or if it was changed after the relaunch.

[olafgrabienski]

@Graham-72 You're right, we shouldn't assume that all users share a developer or site builder view. In my opinion it's however not the best approach to start with topics about editing or adding content. That said, they should be immediatly highly visible.

[tomgrandy]

@olafgrabienski - Yes, in backdrop-ops/docs.backdropcms.org#196 I did attempt to create an order that included the developer guide in the documentation / user guide, that included everyone from novice to advanced. The User Guide went through several other iterations based on comments in other tickets, but never got to the point where developer documentation was included.

So, it is correct on the new site as I had arranged the topics based on the most recent discussion, but could be added to as @klonos has described in breaking the contents into sub-sections.

[klonos]

Yes, as I said, once we have drop-down menus in the main nav (so that we can have a single "Documentation" menu item*), we'll then be able to improve the structure of the entire guide.

So we can add only* the 2nd level, main topics:

• Documentation -- Install Backdrop -- Build your Site -- Extend -- Contribute -- Develop

[tomgrandy]

@klonos - Works for me!

[klonos]

@tomgrandy although I see your point in having the content creation come first, having installation come after that simply does not make sense to me since in order to start using Backdrop you need to first install it. Some installations will be less "manual" (hosts providing "single-click" solutions etc.), so some people might already be handed a ready-to-use vanilla site. These people can always skip the "Install Backdrop" section and go straight to "Build your Site" 😉

Anyways, I am happy to discuss this further and can be convinced otherwise. What I would like to see though is the styling of the user guide pages to better match the rest of the site by having a distinct title section with the same background color and possibly "subtitles" (like we have on the themes/modules/layouts pages), since these can be good for both SEO (I believe) as well as serving the purpose of a "What you'll learn by reading this" summary.

[tomgrandy]

@klonos - I think it was @Graham-72 who brought having content creation precede the installation instructions a few comments above. I agree with you that there is an order and Install should be at the beginning and if the user wants to skip it, they can.

Wordpress Support is similarly structured with install help first.

Agree with keeping layout consistent throughout the site to include subtitles. There is a "Callout" for each section, but it doesn't match the themes/modules/layouts page you reference above.

[Graham-72]

in order to start using Backdrop you need to first install it

My point is that it may have been someone else that installed it, as I do for my clients. Though thinking about it, they (my clients) would be scared by a handbook that included all the development guide technical detail, so they need some different form of User Guide.

[jenlampton]

The only distinction between the User Guide and all the stuff on api.backdropcms.org is that there should be no instructions on how to code in the user guide.

I hear the complaint that the API and dev docs are now hard to find... How about adding a top-level navigation link to the API site? maybe something like "Developer documentation"?

[olafgrabienski]

How about adding a top-level navigation link to the API site? maybe something like "Developer documentation"?

Good idea, but has also a few possible drawbacks:

• There are already eight main menu items, one more might feel like 'too many'. (Saying this without having done a usability research.)
• The name "Developer Documentation" is very long and would probably cause header design issues on smaller desktop screens or tablets. Maybe call it "Dev Docs" instead?

[jenlampton]

There are already eight main menu items

this is temporary. I think the approved menu has only 4?

Maybe call it "Dev Docs" instead?

or we shorten it only on smaller screens?

[olafgrabienski]

Do you know which ones will be the four items of the approved menu?

[jenlampton]

These ones: https://github.com/backdrop-ops/backdropcms.org/issues/312#issuecomment-269830153

[jenlampton]

We could also call it "Developers" and point to this page: https://backdropcms.org/developers

[olafgrabienski]

@jenlampton Thanks for the link! Didn't know of it, was not following the ops queue back then.

With the improved menu it's totally different, we'll have User Guide and Developer Guide as direct neighbours:

SUPPORT (https://backdropcms.org/support) -- Get Help (same link as above) -- Resources -- User Guide -- Developer Guide (https://backdropcms.org/developers) -- Service Providers -- Ways to Contribute -- Forum

So I guess, this issue ("Make the Developer guide more visible") will be solved with the new menu. When will it be implemented?

[jenlampton]

When will it be implemented?

Soon, I hope! I was thinking about working on it today, but now that @wesruv is back on the scene I want to give him a chance to look it over, since he's already themed the drop-down navigation, it will likely be faster for him.

That said, we could add the link now and remove it once the new menu goes in.

[olafgrabienski]

We could also call it "Developers" and point to this page: https://backdropcms.org/developers

That said, we could add the link now and remove it once the new menu goes in.

Yes, I agree!

[jenlampton]

done :)

[olafgrabienski]

:-) ... but now:

With the added item, the menu doesn't have enough space on all screens. When the screen is between 768px and about 990px the menu is displayed in two lines.

[jenlampton]

I think that's okay, temporarily. It doesn't look broken. Do you think this is better or worse than not having the link?

[olafgrabienski]

Undetermined. We could even finetune the CSS to fix the mentioned screen size but as you say: it's temporary, and it's okay.

[ghost]

I'd like to re-open this issue as I don't believe the original problem is fixed...

I was looking for documentation for upgrading a site from Drupal and it took me a while to find https://backdropcms.org/developers in the sidebar of the About page (not somewhere I'd ever consider looking for that).

There's a lot to read above, so I mainly just skimmed it, but was it decided where to move this page/section to make it more discoverable? As it is now it's practically hidden...

[olafgrabienski]

@BWPanda - Regarding the upgrade from Drupal, there is a "Upgrade from Drupal" section including a button on the home page. That said, I agree that the developer notes are still hard to find. To improve the situation, I suggest to put a link to the dev notes as a menu item in the "Support" dropdown, right below the "User guide" item.

[oadaeh]

I will jump on this recent bandwagon to say that I feel like information for developers is scattered and not well organized. I would never consider looking for developer documentation in a page/link labeled User Guide. I generally start by going to the link labaled API Documentation and blindly poking around until I find what I want or give up. Having a Developer Guide link beneath the User Guide link is an excellent idea, but then that page needs to be complete and organized, so everything can be found from one place within one or two clicks/taps.

[jenlampton]

I think this issue has been resolved since we moved all the documentation over to https://docs.backdropcms.org/. If there are still issues that need to be addressed, let's open (and fix) them in the docs queue: https://github.com/backdrop-ops/docs.backdropcms.org/issues