User guide for new users #55
Comments
|
This is an excellent list and if we can produce a guide like this it will be very useful to someone setting out to build a site using Backdrop. What I have in mind as a guide for site editors would be very much a subset of this. My users (for whom I have built sites) would run a mile, probably to Wordpress (!) if I gave them this to read. I have just caught up with this blog - http://www.istos.it/en/blog/learning-drupal/how-i-finally-convinced-my-dad-switch-wordpress-drupal - which sounded very familiar to me, though of course things have moved on since that was written, and Backdrop is a great deal more user-friendly than Drupal 7. (Thanks guys!) Can we pick out the parts for the non-techie user? |
|
@Graham-72 Can we have a similar outline of what you need for the non-techs among us? I see no reason why we cant have layers of documentation as you say. |
Code "snippets" are generally a dangerous thing. The most common kind of snippets are for executing raw PHP (which is more difficult in Backdrop because we don't have a PHP filter). We definitely don't want all users to be able to post snippets, as it quickly turns into a bog of insecure code. Perhaps we could do something like maintain a feed of Gists or some other off-site resource?
With most sections, I can tell what's going to be in them based on the title. What sort of "general" advice would live in here? Could we make this more clear in its title?
I think it's important to include this topic, as the admin bar is the primary navigation tool for administrators, but each of the sub-topics don't seem like they'd be worthy of their own page. Overall, I think it looks like a great outline. Some sections are definitely going to need sub-sections (e.g. any of the recipes) but I think it would be great if we could find a way to separate those from the book outline itself, like a table-of-contents specifically for each recipe. |
I understand "code snippets" to mean howto samples, like: NOT the "put this in your node content" type of stuff. Snippets were very helpful for me in figuring out what to do when...
Meaning, use proper white space, use appropriate fonts, dont use grey text on greyer backgrounds etc. design advice. But I suppose that may either be out of the scope of this effort, or not a priority. Would be a nice addition for an absolute newbie, to prevent some of the OMG websites out there.
OK. |
|
My first thoughts on the content of a basic guide: Using Backdrop CMS 1 Outline of what Backdrop CMS does 2 Controlling content 3 Navigation 4 Comments 5 Basic administration 6 Opportunities |
|
@Graham-72 your list seems more an intersection than a subset, dont you think? How about if the guide was as comprehensive as my list but we tagged each article by who it could apply to (owner, admin, editor etc)? And/or tag by complexity (basic > advanced > guru > quicksketch) ? |
|
@docwilmot yes I agree my list hasn't turned out as a subset. I think what I have in mind is a booklet that I would hand to a new user as an introduction, and would avoid including extra layers of complexity that some might get interested in later i.e. the guide you have outlined. When I say booklet I do really mean something that could be printed on paper - horrors! Maybe I should go ahead and write something that might interest a publisher ? :-) [How does one add smileys in GitHub?] |
|
|
+1 to all the wonderful work going on in this issue! |
|
I teach an introductory web development class at Berkeley. On the last class of my last session, I had my students download and spin up Backdrop on Pantheon to see what their experience was. They were able to get it installed and running just fine, but when the installation process finished they had no idea what to do next. It was a little painful for me to watch them click randomly on menu items that don't have any effect until you have some content. So...why don't we give them a subset of @Graham-72 / @docwilmot 's outline as a single default node? Just the TOC/outline, linked to online text. That way beginners would have something to dig into, and experienced people could just delete or re-purpose the node. |
|
@cellear because on 99% of Drupal sites that node would be deleted. I'm all in favor of improving the first-time experience, but I don't think filling the site with about-to-be-trashed content is the way to do it. An overview page that's not a node - maybe. But certainly not a node. @docwilmot for the issue of tour module in core, see backdrop/backdrop-issues#89 |
It did. That was the link above. |
|
But that's the point! It seems to work ok for WordPress. When you start a new WP site, it creates a node that says this:
I'm proposing we do something similar, though I figured as long as we were making a page, it might as well point to something useful. The WP example page, while better than Drupal's Nothing, assumes a familiarity with jargon that it probably shouldn't. (It assumes the new user is making a blog, which seems to unnecessarily box them in.) So yes, make things easier for beginners, even if it doesn't help the gurus. Isn't that a core Backdrop principle? |
|
(I'd like to cross-reference this: backdrop/backdrop-issues#519 but I'm not sure how to.) |
|
I like the idea of the tour module though, as with videos, I like to be able to navigate (either forwards or backwards) to revisit particular points in an explanation. Is this possible? I have made a start at writing text for the basic guide I envisage. I have produced a first part as a PDF but GitHub doesn't seem to accept these, so I have put it on my webserver at http://www.oliverweb.net/BackdropEditingGuide_Draft.pdf I must emphasise that I am writing this for the non-technical user who is suddenly challenged with the task of editing a website, either for themself or for a small organisation - a situation that I have met on a few occasions with Drupal sites. Of course we also need a clear technical guide that makes it as easy as possible for someone to set up and run a website using Backdrop. |
|
edit: I was starting to post here about the content for a default node, so I moved my comment over to backdrop/backdrop-issues#519 (comment) instead :) @cellear My point was just that I think we can find a better place for this information than someplace that is likely to be deleted before it reaches the eyes of those that need it most. @Graham-72 this documentation you started is very impressive! I think we do need to be careful about making assumptions about the size of the development team. I'm not done reading this yet, but I've already discovered mention of both a "Site designer" and "Systems administrator" but in the case of a small dev shop many these roles may be the same. |
@jenlampton My thoughts exactly! |
This simple sentence has cost me a good week. I checked, and found that Joyride version used in D8 doesnt do backward navigation; this feature requires either a patch or updating to the latest Joyride. BUT the previously standalone Joyride plugin has now been integrated into Zurb's Foundation, and to use the latest code requires some more hacking and/or including the full Foundation js into the tour module. Thats tough. So a few Google hours of search found "Hopscotch" by Linkedin which has the following advantages:
So, therefore, I've adopted the existing Joyride module to use Hopscotch. See https://github.com/docwilmot/hopscotch. Still rough, please review and test. My aim now, would be to build tours in tandem with the docs. Comments welcome. |
|
Going to go back to writing docs again, but will start with the developer docs as thats already on the way. @Graham-72 I've made a folder on Google Docs here. Maybe we could start the user docs with what youve already got, if you dont mind? I've mad a checklist out of the first post; create a new Google doc for one of the checklist items and go ahead. |
|
@docwilmot thanks for creating the folder on Google Docs - excellent idea. I have put the current version of my embryo User Guide in there and will shortly resume work on it. I am intending to use the new admin styles for screenshots. Also, use revised terminology for 'article' and 'basic page'. |
|
@docwilmot I wonder whether we could have a third subfolder in Google docs for useful notes and tips for Backdrop developers? For example, I am gradually learning how to do different things with PhpStorm and GitHub. I have to write notes for myself in order not to forget things and these might be useful if collected together. Also various tips have been written by you, Nate and others in these issues, and it could be helpful to record them in one place. What do you think? |
|
Where would we put user docs? |
|
On backdropcms.org? |
|
Figured, but it would need building and styling. |
|
Not just a downloadable PDF? |
|
No, has to be searchable, categorized, version-filtered help. |
|
Yep, good idea. I set up all Documentation pages to show the book navigation in the right sidebar: |
|
@docwilmot it looks like some of the documentation is in documentation nodes, and some is in book nodes. Was that intentional? |
|
Thanx @jenlampton 👍 |
|
...not much experience in using the Book module, but part of the index (what seems to be the level of the current page and below) is duplicated at the bottom of the page as a Also, as a note/todo: we should set up automatic paths for books and book pages. |
|
Another great point. I have created backdrop/backdrop-issues#1976 to add a UI for book navigation display preferences, but short-term I can take it out in the theme layer. |
|
I decided to leave the navigation (up / next / previous) but delete the tree. What do you think? |
|
oops. |
Wasn't intentional. I forgot that the "Add child page" link defaults to using the Book content type. I used that link several times. Will manually transfer to documentation content type and delete the Book pages. |
I'll see if I can fix that for you... edit: should be fixed. Give it a try now? Also, sorry about that. Hate to make more work for you! :) |
I think we should leave the tree in place as it was. Especially since our docs are likely to be long form, it may be best to have the tree at the end rather than scrolling back to the top to find it. Unless you can fix the position of the block. And also, certain people (me) are used to it right there. |
|
Do we have a documentation-page on creating documentation? I would like to take some notes as I am doing a review :) so far... I looooooooooove it!!!! :) |
haha, well of course there are 3 of us and we seem to all have 3 different opinions :) |
|
I like what I am seeing now, with the book navigation tree in a right hand column and with forward,backward, up links at the bottom. Works well on my tablet too. |
👍
...no, no. I like the |
|
...I think it would be nice if we could make the index at the right be sticky somehow. That would keep it within the users' view and they could scroll independently from the main documentation text. |
|
Whats the consensus on the name of the Layout UI page? I had issues deciding which while writing the docs.
Also how do you feel about grouping some of the definitional docs under a single group, e.g.:
Or leave as is? Also, would be good to have some way to report inaccurate docs, or to request new docs. Forums? Also: noted the "Status" select list for docs completeness, great idea. Should we consider docs without images yet complete? |
|
I think that the most "accurate" way to call things would be: "Layouts list" for Now, this is to refer to things in documentation. But we need to be consistent in the UI too (I will file a separate issue against the backdrop repo for that, once we reach consensus here). Rationale:
Now, there are things going on in that page that do not quite fit in the "manage blocks" realm...
Point is that using "edit" for that page was an easy way out of these dilemmas and so is using "Layout UI". On the other hand, "Manage layout blocks & regions" although accurate, is too long. Even if we omitted the "layout" part and called it "Manage blocks & regions", it's still long. I left "Layouts settings" and "Layout settings" for last for the obvious reason that it will be easy to confuse the two. The fact that the second word ("settings") starts with an "s", which is the same letter that "Layouts" ends with, will make it "silent" when one talks fast. Any good ideas on that? |
|
Related: we still don't know what to 'officially' call these pages either: Here's the latest proposal: |
|
Starting a new topic at backdrop-ops/docs.backdropcms.org#196 to discuss the docs themselves as this discussion is getting a bit long at 105 comments. |
Calling it the "Configure blocks page" will probably also conflict visually with the "Block configuration form". Too many of the concepts are similar so I propose to not try to be too technically correct and call it something unique like "Layout designer" or "Layout Builder". |
|
Just saw this. Sticky tree on the side sounds appealing, can be tricky to implement though. Did a little bit of Googling, this seems like a good option, the "Scrollable Sticky Element" demo is particularly witty, and would be an issue we'd have. |
|
This continues on backdrop-ops/docs.backdropcms.org#196 |
Moving from backdrop/backdrop-issues#808
We need to create a well-thought and organised user guide for the site owner / site editor / site admin type. Current proposal is to create a new section of backdropcms.org for this purpose. The section should be organized however is needed to make it clear and understandable.
This new section will be linked from the Handbook, in the user guide area.
Google docs: https://drive.google.com/folderview?id=0B5vNMqFUUd-SfjV0Z1hZUUlrc2N5anRwM2lDNm0zOUlRVThkZ3VEZ1I1UXJnT3N5dG10TjA&usp=sharing
The text was updated successfully, but these errors were encountered: