Proposal: Create and promote new "Quick-start guide" pages

Is the plan to use the same system that we used in the User Guide, for authoring and revision control? This system offers:
- Docs are written in AsciiDoc (which uses a flavor of markdown for headings etc. and is otherwise plain text)
- From that source, you can produce ebooks (PDF, ePub, Mobi) and also import into nodes on drupal.org
- We also have a contributors guide (written the same way), which includes several topics for project managers
https://www.drupal.org/docs/user_guide_guidelines/index.html

If you do plan to use the same scripts/system as the User Guide, I would be happy to be involved as a project manager or tech support or whatever you need.

If you don't plan to use the same scripts/system, you'll need to figure out another way to have revisioned, curated docs on drupal.org.

And either way, I would strongly suggest that you focus on content oversight first. A key reason that the User Guide (a) got written at all and (b) turned out as well as it did, in my opinion, was because Joe and I figured out what each topic needed to cover before we let people start writing the topics (of course, some topics were modified, added, and/or removed as we figured out the limitations of our initial decisions). This project will also need to have someone, or a very small number of people, in charge of deciding on what topics need to be written, and what exactly should be in them. These people will be open to hopefully (but not always) constructive criticism as they enforce their decisions.

Also, a comment about visibility of the "preferred" docs vs. the existing wiki...

I would really really really welcome anything we could do to promote the User Guide, as well as any other planned documentation, over the existing wiki-style documentation. We did try to get the User Guide promoted, linked to, etc. when it was done... but obviously, many people who could benefit from it still don't know about it.

Maybe one thing we could consider is to change the page titles and page markup, so that the non-curated docs have "Wiki" both in the page title (which will show up in search results) and as part of the page header? As things are now, the User Guide is being imported into drupal.org into the same exact content type as the existing docs, so it's pretty hard to differentiate.

Another thing we could consider doing is moving some of the docs off to a subsite. For instance, we could have wiki.drupal.org, which would help to make it clear that the free-for-all docs are a wiki. But moving those docs, which have lived on drupal.org for years, would be problematic, especially since now each Project on d.o can have an associated Guide. But we could consider making a separate docs.drupal.org, and putting the curated/preferred docs there? Just a thought...

+1 subscribe. :)

I think this is a great idea. And would also be interested in being involved in helping to get it done.

Another thing that might be worth adding to the list of deliverables for this initiative would be some kind of documented process for how to go about getting another one of these official guides started. For example; I think it would be great to have a "one pager" Hello World for module developers sometime down the road. And maybe the Migrate module team wants to add an "official" migration one pager. As I'm writing this I'm realizing maybe what needs to be discussed within this initiative is what parameters need to be met in order for something to be promoted to "official". I think that taking the time to figure this stuff out will help encourage others to submit their ideas for more official guides in the future. Which seems like a good thing.

I think that #7 is an important aspect of the Content Oversight part of this project, which again I think is most likely the most difficult part, given that we have the toolchain already figured out and working.

Regarding Github, there is nothing to stop anyone from mirroring a project between Github and Drupal.org Git now. IMO, though, the issue tracker is way better here, and I think the primary place for managing the project and tracking issues etc. should be drupal.org. If people want to write docs on Github and use pull requests, though, sure!

Great ideas all around! I especially like "Official" guides such as "Official Composer Guide". Imo, this is the/a missing ingredient for helping everyone feel confident with their approach and working towards the same outcomes. When something becomes "official" people can confidently expect good results, and if those results don't happen they can confidently file an issue.

I'm happy to help with this in anyway I can.

I also like the idea of "official" one-page start guides. I started learning Drupal right around when D8 was coming out but most of the documentation was essentially: "You know how you did it in D7? Here's how it works in D8", which didn't help me since I wasn't familiar with D7. The hardest thing to figure out has been "am I doing this right?" because there are so many different ways to do it that I don't know if something is "best practice" or really more of a hack.

I think having an "opinionated" docs that would give someone a good starting point would be really helpful. One possibility could be that there are multiple options for those quick-start docs that would base around some generic and common starting points. These could either be based on the type of site you're working on or the type of work you're looking to do. I'm a front-end designer, I'm not really looking for a local environment that gives me ultimate custom control over the server and stuff. I just want something quick, reliable and easy to work with. Someone else who wants to do back-end development will have a different requirement. If both of our needs can be covered together, great! But I'm not sure how possible that would be.

I'm happy to help as well. I'm new to contributing to anything on here so I'm not sure what it'll entail, but I'm glad to help others starting out if I can!

Your conclusion about lacking in 'best practises' would also be my first suggestion, so I'm happy to see this in the proposal. You might take that one step further. I would like to see documentation which starts with a plan (can be simply a website design or page design) and then elaborates on the best way (or multiple best ways) to implement it.

For example, to create a news overview page you could use a view, create a module with a route and custom output (with a template), use a module to create a block, create a custom block and connect your module to it etc. What is the best way to go and why? I see a lot of tutorials working with views, but I often have issues with views if my design just has that one thing that is not easily implemented using views without residing to a custom module. All these tutorials use default listings with default fields and default pagination. I need real-life examples.

We don't let Drupal dictate what our UX/design team produces. We can build everything in Drupal 8, but sometimes I'm wondering if other implementations might be better. It would also help in educating new people that are not familiair with Drupal yet.

Regarding that last idea in #12, I think that would fit better in an initiative called "User Guide Volume 2: Advanced Site Building with Examples" (snappy title TBD) rather than in this particular initiative. This initiative is about short, concise, single Best Practice guides, not tutorials with alternatives (which fit better in the User Guide type of format).

Agreeing with #7 and yeah the whole "official" versus wiki really is a problem. And while a good number of the developer docs are in fact quite good, I find they miss a lot of fundamental concepts or simple, isolated examples. They are often written for people who already understand, or who already understand some other equally complex topic.

I don't know if a separate site solves the issues (I've wanted to see docs or wiki as a separate one) but it certainly is very difficult to tell where you are in the docs and what is available. I find myself lost in there all the time, even with the newer content type changes and topic maintainers.

> The goal is not to replace or supersede the existing Drupal User Guide

I think having multiple classes of documentation is going to be confusing. Actually, it already *is* confusing -- e.g. in @grasmash's http://matthewgrasmick.com/compare-php-frameworks:

I decide that I should follow the link. This takes me to Chapter 3. Installation of the Drupal 8 User Guide which is a completely different set of docs. I think to myself, "this is weird, but I'm going to go with it."

Looking at the matter from another angle: if we had no docs at all, if we were starting from absolutely nothing, would we choose to have 'official' docs AND wiki docs? What would be the point? Would it help users? would it help documentation writers?

Replacing or reworking existing things is hard. It's easier to just say, 'hey let's leave that steaming pile of mess over there, because cleaning it up is too hard, deleting it completely will cause an outcry, and start fresh over here'. But in the long run it doesn't fix the problem. It's a bit like the xkcd cartoon about the competing standards: we end up with n+1 sets of documentation and users are even more lost.

So I think that part of the goal is flawed.

The proposed process, though, I agree with.

I think we're right to be thinking about moving to version-controlled docs. Our release cycle almost forces that on us anyway, as we need docs to be updated every time there is a new minor release (with new features, deprecations, etc), and using nodes and books on d.org just doesn't allow us to do that.

Another massive benefit of version-controlled docs is that (as has been proposed elsewhere) we could choose to enforce documentation patches as a requirement for code patches.

But there are big questions to consider about what we do with the existing docs, and what happens to contrib docs. 'Nothing' is not good enough an answer.

Here's some excellent top-down documentation, presented by the Symfony console component: https://symfony.com/doc/current/console.html

What makes it excellent?

• Thorough but breezy overview.
• It has sub-articles that can clarify 90% of use cases, including how to write tests.
• It's versioned.
• It reminds you that you're looking at the 4.x version, and maybe you need to see the 3.x version.
• It doesn't have a comment section.
• Easy navigation to the other components offered by Symfony.
• It's maintained through a review process.

Here's the same documentation as an .rst file (Markdown) in a github repo: https://github.com/symfony/symfony-docs/blob/master/console.rst

Here's a pull request against it, still awaiting review: https://github.com/symfony/symfony-docs/pull/9304 Note that this PR is being reviewed by @fabpot, who you can't describe as an unpaid volunteer.

The most important part of this scenario is the 'not an unpaid volunteer' part. The rest follows from it. If someone is in charge of doing this - even as a volunteer, but hopefully paid - then they should have the leeway to build a process and a toolchain that works for them.

> have a place for user-generated docs (wiki) and a place for official "top-down" docs (official).

It doesn't make sense to me.

- I am a user of Drupal and I want to read about a topic. Which docs site do I search in? If I search on Google, where does it take me?
- I want to improve the docs. Which set of docs do I submit a change to?
- I am writing a patch for core. Now I have two sets of docs I should update.

As much as I have a preference for web-editable docs, I don't think they can keep up with our 6-monthly release schedule.

A side note: we don't have wiki docs, and we never have. We have web-editable docs, which are currently publicly-editable. They're not a wiki, because in a wiki, structure is part of the content. Wikis are much easier to manage than what we have on d.org, where making structural changes is really fiddly (within a single book structure) or possibly requires admin access (to move pages between books).

> It has sub-articles that can clarify 90% of use cases, including how to write tests.

I've actually found Symfony documentation to be rather lacking overall. The overview articles such as the one linked to are well-written and well-presented, but as soon as you want to do something a little bit more complicated there's nothing. The API docs are of the 'repeat the name of the method back to you' variety -- they're atrocious.

The API docs are of the 'repeat the name of the method back to you' variety -- they're atrocious.

Yah, but we've already licked that, FTMP: https://api.drupal.org/api/drupal

The challenge with 'official' docs is: What are we documenting? API docs might be OK to be a little more of a maze, but if you're teaching someone to place a block, then that's not good enough.

I want to contribute to this initiative. Subscribing!

I like the example from #17, and I think something like that could be a good example for the use-case here. In particular, the model of highly curated, opinionated, top-level page with a baseline of information. And the ability to guide people into other, more specific, and possibly not as complete, documentation. I would guess that a lot of people will get what they need from the first page, and won't click much deeper. Though should they want to, the information is still there. This would be a much more helpful experience than things we have now like the "Setup a localhost" guide which lands you on a page that contains huge list of possible ways to go about it and you're immediately overwhelmed.

From #6

but I think it's maybe better to "promote" curated docs w/ active maintainers vs. "demote" wiki docs into some kind of ghetto

It seems to me like the biggest issue isn't really "official" vs. "other", so much as it is about just not having a good information architecture to guide people into the documentation in small steps. Instead we have a tendency to drop them into the deep end. These curated pages could make a great first level, and help to guide people further in. They can be managed with Git instead of as nodes. I don't think separating things really solves any problems. There's a need for the existing content, I mean, it wouldn't exist if there wasn't. There's also a need for well written, opinionated, pages to help people get started. I think a lot of this can be solved with IA/UX changes.

Your zen koan for today:

"Official"

Why are there quotes around official?

Those are some loaded punctuation marks. Let's rename them from scare-quotes to scape-quotes.

> These curated pages could make a great first level, and help to guide people further in. They can be managed with Git instead of as nodes. I don't think separating things really solves any problems.

Are you suggesting we somehow mesh together the git-managed docs pages with the node-based docs pages, so the git ones are the major topics and introductions, and the node-based ones go beneath?

I like that idea a lot!

I have no idea how we'd implement it though!

It's also worth remembering that we currently have curated node-based guides which are made up of small sets of nodes (using OG to structure them IIRC), AND the older node-based guides (which use book module). The book docs were meant to be migrated into the OG docs but that hasn't entirely happened yet.

I don't think it's technically viable/possible to put AsciiDoc-based pages/guides (which are imported into Nodes using the Feeds module, from time to time, to refresh the content) and native node-based pages/guides into the same guide structures. I think the best option is to cross-link.

I also wouldn't call the new OG-based docs "curated", in the same way that the User Guide is curated. They do have maintainers, but they are still basically free-for-all. They don't:
- Have pre-planning as to what needs to be covered and what should be left out
- Have separation into concept/task topics or at least short one-subject pages
- Go through an issue/patch/review/commit process to make changes
- Have versioning (many are separated for Drupal 7 vs. Drupal 8, but no versioning for minor Drupal versions)

And by the way, the Feeds import of the User Guide imports it into the OG-based docs content types. There is a node field that identifies them as being from AsciiDoc source, which lets us change the page slightly (there's an Edit AsciiDoc Source link for instance, rather than edit the node, and a block explaining where the source comes from with a link to the project).

> I also wouldn't call the new OG-based docs "curated", in the same way that the User Guide is curated.

Yes, you're right. The difference between them was clear in my mind, but it was a bad choice of words, sorry.

So we have:

- curated AsciiDoc-based docs
- maintained OG-based docs
- unmaintained book-based docs

> I don't think it's technically viable/possible to put AsciiDoc-based pages/guides (which are imported into Nodes using the Feeds module, from time to time, to refresh the content) and native node-based pages/guides into the same guide structures.

I hadn't realized that the AsciiDoc-based docs were going into nodes. I assumed you were using something that just reads the git source, like readthedocs.org.

But if all 3 types of docs are nodes, then surely they can be arranged into any structure we like? Maybe not with OG, but with something else.

The AsciiDoc imported nodes are imported with the structure of the AsciiDoc book they come from (chapters/topics like the User Guide).

Since this structure can change in the AsciiDoc source, and Feeds can delete/add/modify nodes when they are re-imported, what I'm saying is that it would be technically difficult to manage putting imported AsciiDoc nodes and Drupal.org managed nodes under the same Guide. It might be possible, but it would make the re-import (which needs to happen from time to time to get content updates) difficult. Feeds really needs to have full control over those imported nodes.

Thanks everyone for your comments so far. I'm doing my best to incorporate all of your feedback in the Documentation Initiative plan.

Current priorities

I met with @eojthebrave (the other active member of the Documentation Working Group) during DrupalCon Nashville. After reading all of the feedback on this thread and discussing, we have the following priorities:

• Improve the information architecture for existing documentation.
  • Tackle #2828874
  • Rename "Community Documentation" to something that clearly indicates wiki-style editing workflow, reflect clearly in UI. E.g., "Community Wiki". Name still TBD.
• Work with the DA to implement UX changes to documentation pages. E.g., drop downs for selecting documentation version.
• Generate "Official One Pagers"
  • Draft clear guidelines for "One pager" documentation.
  • Finalize list of planned one pagers.
  • Draft/publish new documentation.

That is not a final list. We will continue to incorporate community feedback given here in this thread, and iterate on the priorities accordingly.

Topic Discussion

Let me try to weigh in on a few of the topics in this issue (I wish the issue queue was threaded!).

Relationship between the proposed Official Docs and Community Docs

It looks like there is a bit of disagreement in about the relationship between the proposed Official Docs and the existing Community Docs, but the discussion is headed for alignment.

@joachim, I agree. We should not relegate the Community Docs to a documentation ghetto. But, we also can't rewrite them all or delete them all. We'll need to take an approach that allows us to improve things gradually.

I'd like to suggest the following:

• We elevate the Drupal User Guide to Official status by implementing various UX changes to drupal.org.
• We identify Community Documentation that is clearly duplicative of Official Docs and deprecate those specific Community Docs. This should resolve the issue of "multiple classes of documentation [being] confusing." The scope of Official Docs should not overlap with the scope of Community Docs.
• We draft Official One Pager documentation.
  • These will be clearly scoped and will follow guidelines so that they has all of the benefits of Symfony Docs that @mile23 pointed out. I.e, they will be thorough but breezy overviews that address 90% use cases, etc.
  • As we draft these docs, we will cross link relevant Community Docs as @jhodgdon suggested and API docs as @mile23 suggested. These can be referenced throughout, and also in the footer as supplemental resources.

Tools & Process

After speaking with @eojthebrave and @mixologic, and after seeing the code and build process that @jhodgdon wrote for the Drupal User Guide (great job!), it seems like the best path in the short term is to push forward with the established AsciiDoc formatting and toolset.

However, I'd like to suggest that we steer people toward using GitLab as the default way to contribute to the Drupal User Guide and the new Official One Pagers. The issues can stay on D.O.

This plan seems to jive well with the recent announcement (during a session) that Drupal.org is moving its architecture to GitLab. We're essentially going to end up on GitLab either way, I'd just like to get a headstart.

Great (mostly)! The only thing I disagree on is Github/Gitlab. I am one of about 12 maintainers/committers we have for the User Guide (we have Joe and myself for the English content, and about 10 language groups also working on translations, some of which have a couple of committers). I have tried once in the past to maintain git repos in sync between drupal.org and Gitlab, and I am not willing to do it for this project -- it is too painful, and with all the committers we have, all I see is it being difficult. Once drupal.org adopts Gitlab for all its processes, great! We'll definitely adapt then, but for the User Guide project... not now.

If whoever is the Maintainer/Committer for the one-pager docs wants to have their source code in one place and issues in a second, or maintain the synchronization between the two spots, that's fine, but please don't ask the User Guide to change at this point.

Also I'd like to say that if we need adjustments to the Feeds etc. (for instance, to import the User Guide into a different content type than what it is now), I'm here to help. And I think I said it before, but I'd be happy to set up the tecnnical end (scripts, feeds, etc.) for the new project, and possibly as a writer (although probably not if it's Github based)... but I don't want to take on the content maintainer role on that project (not that anyone has suggested I should. :) ).

@jhodgdon Thank you!

Once drupal.org adopts Gitlab for all its processes, great! We'll definitely adapt then, but for the User Guide project... not now.

Ok, that's completely reasonable.

I'm here to help.

I'd like to take you up on your offer! There are a lot of low level implementation details to discuss, perhaps we should set up a time to talk?

Can I suggest that instead of setting up a time to talk, you could start by looking at the documentation:
https://www.drupal.org/docs/user_guide_guidelines/index.html
This is the Contributor's Guide for the User Guide project. Chapter 3 is the Project Manager's guide, where we attempted to collect all of the information about how to set up a new, similar project.

Additional documentation (more technical) can be found in the README files in various directories of the User Guide project's Git repo (that Guidelines document is also in there).

When you're ready to set up the project, honestly I think the most efficient thing would be for me to set up a scaffolding (scripts and a few other files) and hand it over, and then be available for questions that aren't already answered in the documentation.

Before it's time to do that, you'll need to think about these questions:
- Are you planning to have these documents translatable (I hope the answer is yes)?
- Will you make e-book releases peridodically, so people can download a "book" containing these guides, in PDF and ePub format (I hope the answer is yes)?
- Will you use your own templates or ... maybe the Task template from the User Guide? I think you won't have Concept topics, just Tasks, or something like that? Mixing concepts and tasks in individual pages makes them (a) longer and (b) more difficult to understand, structurally.
- Will you want to use our Contributor Guide (we could edit it to point to both projects), or have your own?
- The User Guide has a set of automated tests that also make automated screenshots for all languages... will you be doing something similar?

> that clearly indicates wiki-style editing workflow

Please don't call them 'wiki' anything. See my earlier comment on why they are not a wiki.

Yeah, that is kind of why we settled on "Community documentation" the last time we went through this discussion... We wanted a title that indicated "This is documentation that comes organically from the community, with minimal planning and oversight". It was more polite to call it "Community documentation" than "Huge pile of disorganized spaghetti". ;}

I'm one of the contributors to the "Huge pile of disorganized spaghetti" ;-) Many of us try to make concise (and very accurate) documentation - probably pretty close to the suggested "Official One Pager". The problem is there isn't a common understanding and many like to include every single edge case or to cover every mini step ... Anyway, I just wanted to ask about the relation between official one pagers and official documentation (like the user guide). How do you avoid duplication? It's not clear to me. An example would be nice.

I don't mind the proposal, but I think we would have gotten far with the recent move to guides and guide maintainers, if there was clearer guidelines for the format and scope of the guides. What I really like about the proposal is that changes are reviewed.

Sorry, probably I shouldn't have called the existing documentation spaghetti -- obviously, much of it is quite good. The problem is that it's hard to differentiate the old, outdated, and/or wrong information from the great information. And, it is definitely difficult to navigate and search.

Presumably we will make cross-links between User Guide pages and these new opinionated one-pagers. One example is in the issue summary about installation. The User Guide provides many options. The one-page guide will provide one option. They should link to each other. In the User Guide topic template, we already have a page for making links to related information -- it's not on every page, but many pages have links to good blog posts or existing drupal.org documentation.

> Anyway, I just wanted to ask about the relation between official one pagers and official documentation (like the user guide). How do you avoid duplication? It's not clear to me. An example would be nice.

> Presumably we will make cross-links between User Guide pages and these new opinionated one-pagers. One example is in the issue summary about installation.

The example is here:

https://www.drupal.org/docs/8/install/step-5-run-the-installer

I'm concerned that this isn't very good. You're reading what you think are some comprehensive docs and you get shunted to another set of docs.

Isn't that one of the problems that was raised in that blog post where someone ran through the installation steps through the eyes of a newbie?

I can't shake the feeling that every time we try to improve / fix our docs, we try to come up with a Big Grand Idea that will make everything better, and involves flashy new stuff. That happened with the maintained guides, and now we have a mix of the old book pages and the maintained guides and those still aren't fully functional and don't have all the content yet.

I think this tweet summarizes my concern here: https://twitter.com/DelilahSDawson/status/987320872057925633 We're looking for big solutions, when the other, simpler, but much more boring and less exciting and frankly laborious solution is just: knuckle down and clean up and improve the documentation.

> I can't shake the feeling that every time we try to improve / fix our docs, we try to come up with a Big Grand Idea that will make everything better, and involves flashy new stuff.

I agree, and I'd like to avoid trying to achieve something overly ambitious. That's why the "one pagers" really only introduce 3 or 4 new pages of documentation total. The rest of the proposal is to improve the documentation's UX in minor but impactful ways.

> knuckle down and clean up and improve the documentation

The trouble with knuckling down and cleaning up the docs is that they're bound to atrophy again. Without an editorial process, improving the "web-editable" Community docs will always be an uphill battle. We need more controlled format. Documentation by committee has not been successful.

The point of duplication is an important one, and I think it will require more discussion.

> How do you avoid duplication? It's not clear to me. An example would be nice.

I'd like to actually deprecate duplicate pages. We shouldn't have 3.4. Running the Installer in the Drupal User Guide and also a Step 5: Run the installer. There should really only be one page on Drupal.org that provides this information.

Perhaps after we establish a format for "Official Documentation," we can gradually migrate the Community docs into that format and deprecate the duplicative pages?

Yes, it would be great to eliminate docs on drupal.org that duplicate pages in the User Guide. We can presumably delete them and put in a redirect to a URL within the User Guide. Doing it is pretty easy; the harder task is to make a list of those pages and where they should be redirected to. As you both have agreed: cleaning up the existing documentation is the problem.

But I don't have a problem with having an expansive, show all the alternatives, tutorial-formatted page or pages in the User Guide, that also link to a snappy, opinionated, one-page guide as part of this initiative. For instance, in the User Guide we might discuss the alternatives for setting up a local development site, and link to the snappy one-page "Here's what we think is the best way to do it" page. And that page might link back to the user guide in the "If this doesn't work for you" section.

I've posted an update https://www.drupal.org/project/documentation/issues/2828874 including a mockup of a new documentation landing page, which may clarify some of the open topics in this thread. Community Docs vs Official Docs, for instance. You can imagine how we'd deprecate both 3.4. Running the Installer in the Drupal User Guide and Step 5: Run the installer after creating a "Getting Started" section.

Once we have this established, we can also do work "knuckling down" and cleaning up community docs. I think we really need to sort out the IA there, but given that each community docs section has its own set of maintainers, I suspect there will be a lot of communication and collaboration overhead. We can't just go in and start re-organizing guides willy nilly.

If the User Guide needs a revision, to remove or revise pages, we can do that. But I don't think any of its pages should be marked as "deprecated". As I understood this initiative, the User Guide was supposed to be part of the Official Documentation, right? It just serves a different purpose (tutorial) from this initiative (one-page topics).

Anyway, if you think there are problems in the User Guide, please file issues in the User Guide project. Thanks!

> As I understood this initiative, the User Guide was supposed to be part of the Official Documentation, right? It just serves a different purpose (tutorial) from this initiative (one-page topics).

Oh christ, so we're going to have FOUR sets of documentation kicking around:

- old community docs
- maintained OG docs
- User Guide
- Official one-page topics

And the poor reader is going to be shuttled around from one area to another with redirects and 'helpful' links?

That sounds like a total mess. As a newbie user, my first thought would be 'Why can't you all put this in one place?'

Re: #36 from @grasmash:

> I agree, and I'd like to avoid trying to achieve something overly ambitious. That's why the "one pagers" really only introduce 3 or 4 new pages of documentation total. The rest of the proposal is to improve the documentation's UX in minor but impactful ways.

and comment #39 from @jhodgdon:

If the User Guide needs a revision, to remove or revise pages, we can do that.

Why not add these "quick start one pagers" to the User Guide? Either as a separate chapter "Quick Start Guides" or as additional tutorials in existing chapters?

If the User Guide uses best practices for process, curation, and tools, why not use that as as starting point for improvements?

Adding the one-page guides to the User Guide, either in their own chapter or interspersed, would be fine with me. If we're providing information in the User Guide that is leading people down less optimal paths, we should also remove that... but if it's just someone's opinion that one course of action is often (not always) better than another, the User Guide normal pages would probably want to stay as they are. (These new things are supposed to be opinionated and snappy, not comprehensive and tutorial-like.)

Anyway, if it's really only 3-4 of these pages, that seems easier than adding a completely new project. Plus, they'd most likely get translated by our existing translation teams. Win-win!

We can also add a new maintainer or two to the User Guide project to oversee the content of the quick start guides. Alternatively, Joe and I can continue to do the actual commits, but we can get sign-off from a designated person/people before we commit changes to them.

Yeah... A separate chapter could help to resolve that problem of separating the Quick Start Guides from the User Guide. But either way. :)

@joachim make that 5 sets of information, you forgot the "Resource Guides" https://www.drupal.org/resource-guides :)

Moving forwards, perhaps a diagram showing the 5 various "silos" of documentation in a tree and how each section could possibility overlap/duplicate other sections? I'm happy to spend time to graph something out.

If someone wants to assign me a ticket for nuking "User Guide" style information from "Drupal 8 documentation", that would be cool.

Is there somewhere I can see a current "status" of the plan that's evolving here instead of reading all 50 or so comments? Maybe like an "outcomes" wiki somewhere? Happy to start providing elbow grease

Oh yeah, those Resource Guides. Those were added by the Drupal Association a few years back, without consulting the Documentation Working Group or the community, and without coordination with the rest of the documentation. Just a little bit of history.

And yes, this does need an issue summary update.

We have a lot of really good documentation, and a lot that just simply needs to go. It's better to have slightly incomplete information than wrong information.

#2966481: Nuke the entire "Resource Guides" section

My personal feeling on the situation is that we just need to iron-first it a bit and start culling information and pushing people towards whatever you decide is right/best place depending on the two scenarios "Site/content administrator" and "Developer", Certainly writing more documentation should not be the focus, we already have a lot of good documentation and that absolutely needs to be the priority

We need to be a bit careful about deleting documentation pages. Sometimes they have been around for decades, so they may be bookmarked, linked to, etc. So, we usually want to put redirects in place, rather than deleting pages outright.

If you'd like to start an issue and collect a list of pages that should be deleted, along with a list of where their URLs should be redirected to, that would probably be helpful. Maybe start with pages that are duplicates of User Guide content? Thanks!

> Oh yeah, those Resource Guides. Those were added by the Drupal Association a few years back, without consulting the Documentation Working Group or the community, and without coordination with the rest of the documentation.

Correct me if I am wrong -- I may be, I was out of circulation for a while with family stuff -- but my impression is that the same thing happened with the user guide!

One minute we were recruiting maintainers for the OG-based maintained guides, which were going to gradually replace the old community docs. And then the User Guide pops up out of nowhere!

No, quite the opposite actually. The User Guide was an initiative that was introduced by the Documentation Working Group as a proposal, which was then discussed and approved by the community, and then worked on by the community. Much like this initiative to create Quick Start Guides (assuming it is approved). The history can be found from links on the User Guide project page.

> The User Guide was an initiative that was introduced by the Documentation Working Group as a proposal,

So was the shift to OG docs not a DWG proposal? Because the OG docs and the User Guide seemed to land at a similar time, and to me at least as an OG guide maintainer, it felt like work was being duplicated.

Which is the same problem we are in danger of creating here: we have multiple silos of documentation (and 'silo' is a good word for it, thanks @dgtlmoon), and to readers, that's just silly, confusing, and a general PITA.

We should only have different silos if there is a clear, distinct case for them in terms of *audience* and *purpose*.

So not deleting the book-based community docs because it'll cause outrage -- not a valid reason. Not absorbing the User Guide into the new proposed One-page docs because a lot of hard work went into it -- not a valid reason. We need to be as dispassionate about our docs as we are about source code (much like on Wikipedia, where you submit content and accept it will be rehashed, mangled, and possibly just deleted).

So, we have to answer the following questions:

- what are the different audiences and purposes of our documentation?
- which of those needs does each current or proposed silo satisfy?

Then, based on each silo's purpose, we can start to think about the technology to use for it.

I *thought* that the major advantage of git-based docs was that they are versionable, in the sense that they let us show a version of the docs for each major version of core, but now I think about it, if they are imported into OG nodes then I don't think they do that:

> I don't think it's technically viable/possible to put AsciiDoc-based pages/guides (which are imported into Nodes using the Feeds module, from time to time, to refresh the content) [...]

How does a new node structure get created every time a new branch is created?

I have to run... but a few notes:
- We are currently only displaying the current 8.x branch of the User Guide on drupal.org. The branch structure is there in the project. When we get to Drupal 9 and Drupal 8 is still supported, then we'll probably want to have both the 8.x and 9.x branches of User Guide on drupal.org. When we update the D8 branch of the User Guide, we overwrite the previous nodes.
- This is consistent with only one 8.x branch of Drupal 8 being supported at a time.
- The OG nodes were a DA initiative that was done by them without much input from the Documentation Working Group in the design process. After the fact, the Docs Working Group got behind the proposal.
- The User Guide -- when we put it on d.o the DA staff decided it should go into the existing OG docs nodes structure.
- I am not against deleting certain pages of existing "community" docs if they are duplicated elsewhere. I just think we should put in redirects from URLs that we get rid of to the better content that we're deleting them for.

Sorry to chime in again, I've discovered another silo of content that is also out of date https://www.drupal.org/marketers apparently "DrupalCon Nashville is happening now".

My feeling right now is that there's some kind of institutionalised problem going on here, the problem is a lot bigger than just a few sections that need a little "tidy up".

Fact: We don't even know how much content and documentation is out of date and/or misleading on Drupal.org.

I can't help get the feeling that when @jhodgdon moved my issue about the resource guides to another issue queue that this was indicative that we just don't have the power and the complete picture of what is really going on the with the documentation - and the real issue at hand here may be an organisational failure in general from the top down.

In my view - the issue about the resource guides is also documentation and should be covered by this issue.

We build CMS's for a living, but we can't seem to control what's going on with the content management on Drupal.org

The OG nodes were a DA initiative that was done by them without much input from the Documentation Working Group in the design process. After the fact, the Docs Working Group got behind the proposal.

yes - exactly - there is some kind of bigger picture issue going on here, with either the web-admins or even Dries not being aware of the enormity of the issue at hand.

The only issue I see with this current issue 2956879 is that we should be thinking about Content as a whole, and documentation is a part of that, there's a lot of overlapping text between "Content" and "Documentation" on Drupal.org.

I know I know... this is a little scope creep, but it really is where it's at I think.

PS: Been trying to graph out more content silos that I find but the google diagrams seems a bit limiting to one sheet size :(

Sounds like we need a dedicated issue

We need a dedicated person, whose job it is to make decisions about this, who gets paid.

@webchick I agree with @Mile23, someone needs to be responsible and get paid for their time that someone who is able to herd-all-the-cats from the weird documentation that comes out of the DA and align it with the documentation/text in general that's coming out of drupal.org

we all need to wake up to the fact that without this, Drupal will never be accessible as any other big opensource project and will never have the quality of documentation as good as other opensource projects, the state of documentation and text in general coming out of drupal.org is a huge inhibitor for Drupal 8 uptake in my opinion (That's what I hear from working "in the trenches" with hundreds of other developers)

The confusing amount of silo'ed documentation, various "industry" pages, overlapping user_guide / docs etc don't give the 100,000's of programmer hours the respect they deserve - they also mostly work completely voluntarily, albeit some are backed by companies/employee/freelancer/etc

I believe the next step should be to not start picking at the little pieces, but raise awareness of this huge problem as high as possible in the Drupal "chain of command", can we get Dries on board? how do we do this? what's the right forum for this? (I don't want to just post comments on an issue somewhere and then it's forgotten about)

I've created a meta issue to redirect the discussion about identifying the big picture pain points to hopefully relieve this issue from out-of-scope conversation.

[meta] Identify and Address Documentation Pain Points

Perhaps this issue would get less Big Picture discussion with a better title? If you don't like it, feel free to change it back...

Yeah, well I thought the main purpose here is to create/promote these new guides, and if also promoting the User Guide is part of the issue summary, that's probably not the main purpose of this issue, is it?

Is (or should) this issue centered around the question of what should be promoted as "official"? Should it also facilitate discussion on what standards that "official" docs should adhere to?

> All of that is entirely out of scope for this issue, however, which is intended to be a "quick fix" achievable in <= 6 months, squarely aimed at solving the most urgent part of the problems: a) that people literally cannot figure out how to install Drupal right now without spending 30+ minutes in documentation dead-ends, and b) these and other "official" docs that have an actual curation + maintenance process behind them and thus are probably the first place they should be looking are not differentiated enough from those that lack said curation/maintenance process.

Ok, I've been widening the scope here a bit too much, sorry.

I get that there's a pressing need for *something* that's a quick fix.

> We can still have (and must have, in order to progress... we certainly can't eat the entirely elephant at once) a hugely positive impact on documentation without solving all of its problems up-front.

No, I don't think this proposal is a positive. I reluctantly agree that it is *necessary*, because people simply aren't able to find docs for things they want to do, and we really have to fix this *fast* because it is losing us potential users and contributors. But this is creating yet another documentation silo. Even if it's a good silo full of good stuff, that is still a large negative aspect to it.

> So far, the only documentation we have that I'm aware of that meets this criteria is the Drupal 8 User Guide.

Not quite -- as @jhodgdon said above:

> We are currently only displaying the current 8.x branch of the User Guide on drupal.org. The branch structure is there in the project. When we get to Drupal 9 and Drupal 8 is still supported, then we'll probably want to have both the 8.x and 9.x branches of User Guide on drupal.org. When we update the D8 branch of the User Guide, we overwrite the previous nodes.

One resource that was brought up in the meta issue was the Examples for Developers project. @Mile23, who is a maintainer of that project pointed it out and I think it's an interesting example and possibly a candidate for "promotion", for the following reasons:

1. It has maintainers and is already hosted on drupal.org.
2. There is a peer-reviewed, clear process for updates and new content (through the project's issue queue)
3. It is a downloadable resource via its project page: https://drupal.org/project/examples
4. It is browse-able on api.drupal.org: https://api.drupal.org/api/examples
5. It is version-controlled. And there are separate repositories of examples for Drupal 7 and 8.

@Mile23 also pointed out that a project having code examples is a huge plus -- if a developer evaluating the project could readily see that there were abundant and maintained code examples, it would be perceived as an incentive to try out the project.

At Drupalize.Me, we see it as a highly valuable resource. We use the code examples in our module development tutorials and contribute to the project as a team.

I see as a short-term possibility, promoting the resource on a quick-start page for devs and as a long-term possibility, establishing a best practice of community-contributed documentation for developers to use code examples from this project or contribute back to it in the process of producing docs on a subject not yet demonstrated in Examples for Developers.

Actually, you have a valid point! While Mile23 provided this link (https://api.drupal.org/api/examples), I'm not sure how one would actually navigate to that page.

From api.drupal.org, under "Further information" the project is listed ("Examples project (sample modules)"), but the link goes to its project page (https://www.drupal.org/project/examples).

Unless I'm missing something, I think a tab or some other navigation element would be great to add.

Oh wait, I found the path but it's really convoluted!

1. https://api.drupal.org/api/drupal/8.5.x
2. Heading: Further information > All topics
3. At the VERY bottom of the page, click on "Other topics" which takes you to https://api.drupal.org/api/projects
4. Then click Examples for developers which takes you to https://api.drupal.org/api/examples

Whew!

We used to have links from the landing pages for Drupal 6, 7, etc. to the Examples project on api.drupal.org. The links for D7 seem to be broken, and we should add one for D8. This is easy to do -- the landing pages for 6, and 7 are in the Documentation project and 8 is in Drupal Core. Just needs issues/patches.

I would also note that the Examples project home page on drupal.org does not link to api.drupal.org's Examples pages. Maybe it should?

Anyway, that sounds like we need 3 issues... I will create them soon...

My mistake -- there is a link on the Examples project page to the api.drupal.org pages for Examples.

So, the Drupal Core 8.x landing pages for api.drupal.org do link to the Examples project page. While they don't link to the api.drupal.org landing pages for the Examples project, I think that linking to the project page might actually be better -- it has an explanation of what the project is for, and links to many different ways to look at or download the examples.

The Drupal 7 landing page needs to be fixed. Turns out there was already an issue:
#2857775: Some links in core @mainpage are incorrect

Not related to the latest example comments ;-)

I have read this issue and many of the other issues related to Drupal documentation. I'm happy to see that many want to improve the situation.

However, I'm not sure that introducing "Quick-start guides" is the solution. I still think that the introduction of Documentation guides was a good move. Each guide should have a maintainer and you can't freely create guides. Many guides are rather quick, but some are too elaborate of course. What is/was missing is:

• A workflow - so only maintainers can approve/reject a change
• Review of changes - comes naturally with work-flow
• A proper standard for guides. (We have standards for module READMEs - why not for guides.)
• Maintainers that actively maintain ... Maybe related to the lack of workflow / review.
• And of course the Guides aren't versioned - or they kind of are, but only for Drupal 7 vs 8.

I also think that we are creating yet another silo if we create these quick-start (QS) pages.

We need a dedicated person, whose job it is to make decisions about this, who gets paid.

But that dedicated person should act according to the DWG roadmap or something so we avoid any more silos.

Finally, I think examples helps moving the disucussion further: If you start at https://www.drupal.org/docs/8/ it's not too hard to find https://www.drupal.org/docs/8/update (if the goal is to update core). How would we serve the needs for people wanting to update using QS pages? (Or maybe I misunderstood and these pages are just for starting up with Drupal things - not maintaining them?) I guess the solution is to select one option as the QS option and move the rest to the User Guide?

@hansfn -- I think you make some good points regarding Guide workflow improvements.. Would you be willing to make them into a separate issue in the "drupal.org customizations" project https://www.drupal.org/project/drupalorg and then add that as a Related issue on #2968619: [meta] Identify and Address Documentation Pain Points? I can also make the issue but I think you articulated the idea well. Thanks!

I have to agree with @hansfn , I don't feel like another silo is what we need - we already have a lot of very solid quick-start sort of information in other existing documentation - and every new silo means it has to be maintained.

I vote for moving this issue to "Postponed" for now, and revisit it once the pain points are resolved?

I would also note that the Examples project home page on drupal.org does not link to api.drupal.org's Examples pages. Maybe it should?

It does... It could probably be more prominent.

Also anyone who wants to be a co-maintainer or needs something specific can just ask. Some folks in this discussion have been co-maintainers since before I owned it. :-)

The API site docs for Examples is dictated by what we can do with annotation in a project. I might not know enough to make it better, so if anyone has any suggestions ping me and/or make an issue.

Quick-start then more in-depth docs is a well-used pattern across many software sites. "Quick-start" also takes the form of prominent "Install", "Getting started", or other top-level navigation links. It implements a common UX pattern and provides a class of information seen on many open source software sites. Its purpose is to help increase adoption and provide a positive evaluator experience.

The proposal here in this issue means to fill a gap that I agree does exist: the gap between landing on drupal.org/home and in-depth, multi-use-case documentation. I agree this gap can and should be filled by quick-start guides that can get someone up and running far enough to be able to evaluate the project and move on to more in-depth, comprehensive resources. These more in-depth comprehensive resources could be the User Guide, Community Guides (which could continue to evolve and improve).

This meta issue is meant to be a place where information can be gathered and organized and then individual issues (that can actually be accomplished in a reasonable timeframe) are created from that. To postpone this issue in favor of that meta issue is completely contrary to its purpose.

In short, *no*, I do not think this issue should be postponed in favor of the meta issue.

Not sure where else to shoehorn a mention of https://www.drupal.org/node/2969396, which needs some top-level doc love. It's in INSTALL.txt, but not anywhere else I can find: https://cgit.drupalcode.org/drupal/tree/core/INSTALL.txt?id=573702f66cdf...

Would it be appropriate to put it in the installation section of the User Guide -- i.e., is it ready for use by relatively novice users? If so, please file an issue in https://www.drupal.org/project/user_guide -- thanks!

Shazam.

Are the "quick start guide" pages landing pages with links to _existing_ documentation, or entirely new documentation to be written covering topics already covered in other silos?

RE #82, see Proposed Resolution section of this issue's summary:

Add new, opinionated "one-pager" guides that provide a single, recommended way to accomplish common tasks:

• Official Quick Start Guide (download & install Drupal)
• Official Configuration Management Guide (export, import, update, deploy)
• Official Composer Guide (install, update, extend, maintain, troubleshoot)

Ok I think I understand the difference now

I think what would really help is to copy the first excellently written opening paragraph from here https://www.drupal.org/docs/user_guide/en/preface-audience.html to here https://www.drupal.org/docs/user_guide/en/index.html

Problem a little bit for me was that as someone who landed on the "user guide" home page, it was not immediately clear who the audience for the document was.

The "user guide" should be fairly non-technical right? and quick start is for people getting under the hood and doing a few more advanced things right?

My only final caveat here...

From the user guide preface..

at installing, administering, site building

So, my question is, what exactly is different about having one page "quick start pages" that cover installation... and the existing INSTALL.txt, and the existing installation instructions at https://www.drupal.org/docs/user_guide/en/installation-chapter.html

I mean, installing any CMS is kind of atleast tricky things, I don't understand the rationale of trying to squeeze it into a "single page"..

So I believe the proposal to have a quick start page also has an impact on the audience for the the existing user guides

I'm still not sold on this concept sorry :(

To look over the fence at our neighbours, I see that wordpress just have a single silo for all installation text, no need for people to think about which of a handful guides applies to them, they just do it

https://codex.wordpress.org/Installing_WordPress

Re #84, I like the idea of adding some audience information to the top level page of the user guide. I've opened a ticket in the User Guide project to do so #2971701: Add info about audience to top level user guide page. Thanks for the suggestion.

Regarding INSTALL.txt vs. https://www.drupal.org/docs/user_guide/en/installation-chapter.html vs. "quick-start", vs etc.

I think part of it might be that these different pages have different audiences. (Though, even that could certainly use some help as is).

My current understanding is that the quick start installation guide is I believe intended to be more for technical evaluators. Someone who wants to quickly get Drupal up and running on their localhost so that they can do some experimenting and evaluating, and then likely at some point trash it and move on to a more complete development environment setup if they decide to continue using Drupal. At which point they are likely ready for a big long list of different possible environments and ways to install Drupal so they can pick and choose the one that works best for their workflow.

The user guide is for someone who is maybe less technical, and is also beyond the evaluation phase and has decided they want to invest time in understanding Drupal more fully. It introduces the current best-practices for installing hopefully with enough information to help you make a choice about which you want to use, and instructions that can probably get you up and running in most scenarios. But, you might still decide that you need more detail about a specific environment or approach.

I think INSTALL.txt currently falls somewhere in-between these two. But it's hard to discover. :/ And we could better define who it's for which would help inform what it should contain.

And the big silo of documentation about EVERYTHING installation related in the community documentation is a place where all of the details not covered elsewhere can be. We can probably do a better job of linking back up to things like the User Guide rather than repeating steps.

For newcomers, I like the idea of guiding people into the information they need a little bit at a time rather than just dumping them into a huge wall of text and expecting them to figure out which part is relevant to them. Though, I also think the huge wall of text is useful and important for people who are no longer new or evaluating and are instead trying to answer a very specific question.

@eojthebrave so then my only real stipulation on this topic before I will stop saying that's a big duplication, is that if we _clearly_ define the silo's before continuing on this ticket, I really feel uneasy about continuing on this ticket without a clear definition of it's boundaries and what boundaries are of the other silo's.

I think all documentation silo's absolutely need to say who they're targeted at, this cuts on both sides - both helps the community at large who happen to come across the documentation aswell as maintainers to keep focus.

Remember - you/me/us/etc is probably not going to be maintaining the documentation in 5 or 10 years time, it's very important to set the trajectory of the silo's now.

I think clearly defining the silo's, no matter the current state of the documentation in those silo's is an easy win and gives us the first "foot in" to making productive change, hmm, ticket anyone? There's already the good spreadsheet from @jhodgdon which could be transposed to some documentation page on drupal.org to set the direction in the future (isnt there a documentation working group page?) venn diagram?

Maybe even simpler way to define the silos is to ensure all silo's have the opening paragraph like in your #2971701: Add info about audience to top level user guide page , this is also a nice "sticky" piece of content that should survive years to come

Thanks for looking over the fence @dgtlmoon. It does make sense with a single page for all Drupal installation info. If you do a search for wordpress install, the official Wordpress install page is the first in the search engine result, as well as more or less the only result from wordpress.org which it makes sense to click on.

A similar search for drupal install yields many drupal.org results, but it's not entirely clear which of them is the right one.

Going for a single page solution would allow us to select a canonical link like drupal.org/docs/install to be THE page for Drupal install info, which would ideally work forever.

For better usability, it would be nice with an automatic anchor links generator, which creates internal links on the page with indentation (the Wordpress "Contents" block) based on whether the header is h2, h3 or h4. This way, the page can be summarized with shortcut links to the pertinent chapter, and since it is created automatically, it would not need to be manually updated by the editors.

Thanks ressa! It could be that the more we think about an issue, the more we have a tendencies to "over cook it", the more people that really want to help out also causes the issue to be over-cooked somewhat, Wordpress is thousands of times larger than Drupal, and yet, just a single page , most big opensource projects also have just a single entry point for installation instructions.

Just a heads up @kay_v just wrote and submitted this page https://www.drupal.org/docs/8/install/quick-start-launch-drupal-8-using-..., which I think should probably be absorbed by whatever we end up doing here.

There's also some discussion about how the new quick-start commands for getting Drupal up and running relate to the user guide. #2969725: Add documentation about command-line quick start tool (8.6)

So now there's quickstart guide already in the 'Official Documentation' but this issue wants to start an entirely new section/silo?

thanks, @jhodgdon and @eojthebrave, for pointing me to this long-standing discussion. I'll digest it and contribute.

In the meantime, it's worth noting that the page I posted is pretty close to verbatim from the change record written by @kim.pepper - it does not yet attempt to address the intended audiences (the change record appropriately assumes developers are the readers).

I did some poking around options for quick-start on Windows, and believe one of our bigger documentation challenges will be installing and configuring dependencies.

Next step for me is to read through the discussion and work out constructive ways to contribute to this effort. Thanks for the work so far on sorting out the considerations!

RE #92, I think you are confusing the purpose of this initiative, which is to write a small series of one-page how-to guides for new Druapalists, with the documentation page that kay_v wrote about how to use a new feature of Drupal 8 that allows you to start up a non-production site for evaluative purposes using the PHP internal browser and SQLIte. Both happen to be called "quick start", but the latter is just another documentation page about Drupal 8 features, not a new "silo" of documentation.

Note, a strategic initiative page for the documentation initiative has been published. The "bucket" of work for the initiative include:

1. Make UX improvements to Documentation on Drupal.org.
2. Improve existing Community Documentation by consolidating, re-organizing, and revising it.
3. Introduce a new class of “Official” documentation that will be version controlled and subject to a review process that will enforce documentation standards. Strong efforts will be made to clearly define the standards and scope of this documentation, and to prevent duplication of existing content.

This issue is aligned with goal 3.

To clarify the scope of the documentation "silos:"

• Official Guides. These are fixed-scope one page guides that are intended to walk a user through accomplishing a set of tasks related to a single topic and oriented on a single goal. They are aimed at the "80% audience" and provide the officially suggested approach. They intentionally do not list all approaches. They are concise, high level, and confined to a single page. They are version controlled and subject to a review process. Planned guides include:
• Quick Start Guide. Provides a walk through for setting up a local development environment, downloading, installing, and logging into Drupal.
• Configuration Management Guide. Provides a walk through for setting up and performing a single configuration management deployment in a single common "representative" scenario. E.g., module installation, export, commit, push, import.
• Drupal 8 User Guide. While not conforming to the typical guidelines for One Pagers, this would be "grandfathered" into the "Official Guides" category.
• Community Documentation. This is the existing Drupal 8 community documentation. It is not subject to version control or review. As new Official Guides are drafted and published, we will also search for and remove duplicative documentation from the community documentation.
• API Documentation. This documents the code of Drupal core. E.g., classes, methods, services, etc. This is automatically generated from Drupal core code and annotations.

At present, the rough execution plan for the initiative looks like this:

Make UX improvements to Documentation on Drupal.org.

• Add Clickable Anchors and Table of Contents to Documentation Pages
• Add UI element that permits switching between Official Guide branches (7.x, 8.5.x, 8.6.x, etc.)
• Design top level landing page for the new documentation system

Improve existing Community Documentation by consolidating, re-organizing, and revising it.

• Refactor Information Architecture of Documentation section

Introduce a new class of “Official” documentation.

• Create repository for Drupal "Official Documentation" (for one page guides)
• Setup basic repo structure and scripts
• Draft standards for one-pager guides (in repo)
• Create template for one-pager guides (in repo)
• Specify requirements for Quick Start Guide
• Draft Quick Start Guide (in repo)
• Draft Configuration Management Guide (in repo)
• ...

Existing drupal.org issues linked where applicable.

This issue is already tagged "Needs issue summary template". Can someone please go through this issue and clarify what has been agreed to and what is still not agreed to? I'm very confused, especially in light of the discussion on #2977535: Create repository for "Official Docs" (guides). Things I thought were still in question and things I thought were decided seem to be the reverse, and this issue still says we're in the "discussion" phase, so I am also confused about whether it's time to start working on a repo in the first place.

Also, there seems to be a tendency to scope creep on this issue. It's supposed to just be about creating "quick start guide" pages, right? So let's keep discussion of other initiatives on other issues and/or their initiative pages, thanks!

I still don't think that we need MORE content, we need to reduce the content we have and re-structure it, the fact that many people are weighing in on this issue with somewhat unrelated issues should serve as notice that there are bigger fish to fry...

I still don't think that we need MORE content, we need to reduce the content we have and re-structure it

I agree that we do need to restructure and reduce the content that we already have. It's important work and it's being discussed in Refactor Information Architecture of Documentation section.

However, we also need different content than what we already have. Our content isn't just disorganized and redundant, much of it misses the mark in terms of audience and quality. We are missing high quality documentation for a handful of critical topics.

This issue is about addressing one such critical topic. We need high quality (discoverable, concise, targeted, etc.) documentation that helps new Drupal users get started quickly and easily. We don't have that now. We need it.

Restructuring existing content, while important, doesn't address this need. But these aren't mutually exclusive issues. We can fry both big fish.

Flippant opening remark: Were we to divert a fraction of the time we spend discussing how to structure docs to actually writing them…

More seriously:

- I feel decision making on this would be considerably easier if we did a content audit first. (Almost) none of us have a complete picture of what's actually there, including the stakeholders surveyed.
- If this is about writing new quick start guides, could we just write one of those and see how it turns out, before reprioritising everything else?
- +1 for placing new guides within the User Guide (#41, #42), or something similarly branded, thus boosting its visibility (within the site & external search) without further fragmentation.
- Maybe consider adding 'Page last reviewed' / 'Next review due' dates to key documentation (in addition to versioning)?
- A physical version (as well as ePub) of User/Quick Guides, for sale at events / hand out to potential users, might improve morale.
- How are you going to decide whose opinion is the best one to use? I'd suggest the "local dev environment" topic is a particularly tricky one - you practically need to interview a prospective user first to figure out what's right for them…

- I feel decision making on this would be considerably easier if we did a content audit first. (Almost) none of us have a complete picture of what's actually there, including the stakeholders surveyed.

Agreed. I'm working on getting access to a D.O dev env so I can generate a tree representing the current hierarchy #2979198: I want a drupal.org development site for Documentation Initiative work

If this is about writing new quick start guides, could we just write one of those and see how it turns out, before reprioritising everything else?

I'd like to get started on it. There's been a great deal of support for this idea in the community and I think it warrants a pilot attempt. I'm a bit blocked on #2977535: Create repository for "Official Docs" (guides), but perhaps I'll just draft it in Markdown and port it to ASCIIDocs format if that remains a blocker for long.

- +1 for placing new guides within the User Guide (#41, #42), or something similarly branded, thus boosting its visibility (within the site & external search) without further fragmentation.

Yeah I'd prefer to have everything in one place, but I do think that @webchick raises valid points in #43. I'm open to either option though.

- Maybe consider adding 'Page last reviewed' / 'Next review due' dates to key documentation (in addition to versioning)?

Sure!

- A physical version (as well as ePub) of User/Quick Guides, for sale at events / hand out to potential users, might improve morale.

Great idea.

- How are you going to decide whose opinion is the best one to use? I'd suggest the "local dev environment" topic is a particularly tricky one - you practically need to interview a prospective user first to figure out what's right for them…

It will be tricky, but we need to do it anyway. I think a clear definition of the intended audience will help. We can also have a public discussion and perform surveys. It will require a good bit of thought, but I feel like we should cross that bridge when we get to it.

As a next step for the Quick Start Guide, I propose that we create a repository where we can begin collaboration. We can then set up the ASCIIDoc scripts, write the guide standards and begin planning the content.

I've created #2977535: Create repository for "Official Docs" (guides) for that.

As a reminder, we are also pursuing a refactoring of the existing community guide in parallel in #2975147: Refactor Information Architecture of Documentation section.

I'm sorry, but I have to repeat some earlier comments while adding my thoughts:

>> Joachim: I can't shake the feeling that every time we try to improve / fix our docs, we try to come up with a Big Grand Idea that will make everything better, and involves flashy new stuff.

> grasmash: I agree, and I'd like to avoid trying to achieve something overly ambitious. That's why the "one pagers" really only introduce 3 or 4 new pages of documentation total. The rest of the proposal is to improve the documentation's UX in minor but impactful ways.

I would love to see a draft list of the planned "one pagers". I just feel that this easily can expand to much more and that the scope of this effort is unclear to people. I for one, had forgotten that it was just "3 or 4 new pages of documentation total". Maybe update the issue summary with some info about this.

>> Joachim: knuckle down and clean up and improve the documentation

> grasmash: The trouble with knuckling down and cleaning up the docs is that they're bound to atrophy again. Without an editorial process, improving the "web-editable" Community docs will always be an uphill battle. We need more controlled format. Documentation by committee has not been successful.

But the OG-based guides/community docs, have maintainers. If we have added workflow to these docs (like I suggested in another issue), people could still propose improvements, but only the maintainers approve/publish it. The Docs working group could decide which new guides should be accepted.

Maybe I haven't paid enough attention, but where is the suggestion for a "more controlled format" for the docs that aren't one-pagers?

Anyway, like Joachim I'm concerned. However, let us get these 3-4 one-pagers done and then we can focus on:

1. Completing the migration of the community docs. This includes deleting pages. (Will create an issue about that.)
2. Improving the OG-based guides - workflow and so on.
3. Improve the IA while remembering that we moved just moved from a deep to a flat hierarchy ... (This has already been started.)

Thanks for your feedback @hansfn.

would love to see a draft list of the planned "one pagers". I just feel that this easily can expand to much more and that the scope of this effort is unclear to people. I for one, had forgotten that it was just "3 or 4 new pages of documentation total". Maybe update the issue summary with some info about this.

The issue summary already includes this list:

• Official Quick Start Guide (download & install Drupal)
• Official Configuration Management Guide (export, import, update, deploy)
• Official Composer Guide (install, update, extend, maintain, troubleshoot)

But the OG-based guides/community docs, have maintainers. If we have added workflow to these docs (like I suggested in another issue), people could still propose improvements, but only the maintainers approve/publish it.

In my experience having maintainers does little to remedy the situation in absence of a workflow. I believe that we should simply use VCS to control workflow rather than inventing a new Drupal-specific system. Git is perfect for text repos.

I'd like to close out this issue. Thank you to everyone who has provided feedback. I believe that everyone's feedback has been incorporated into the plan.

We will limit the scope of Official Docs to a set of 4 guides, as defined in issue summary. The documentation initiative will ensure that improvement of the existing docs is high priority and that new guides do not introduce redundant information.

To recap, the plan is:

1. Introduce and announce a new "class" of Documentation on Drupal.org

This will be accomplished with UX changes in https://www.drupal.org/project/documentation/issues/2828874#comment-1266...

2. Add new, opinionated "one-pager" guides that provide a single, recommended way to accomplish common tasks.

This is a set of at most 4 guides (referenced in summary). This work has begun with the completion of #2977535: Create repository for "Official Docs" (guides)

3. Adopt best practices established by the Drupal 8 User Guide.

This is being accomplished in the implementation of #2977535: Create repository for "Official Docs" (guides).

4. Implement UX improvements on Drupal.org

This work is well underway. See these issues.

To cross of some of the initial "Remaining Tasks":

Open issue in ideas queue for public discussion period

Identify maintainer(s) for the various new guides, with committed time to not only initially author, but also maintain on an ongoing basis, including incorporating community suggestions.

I'd like to tackle these one at a time, with taking personal ownership of the Quick Start guide to begin, which I've renamed Getting Started guide to avoid confusion with the new 8.6.0 quick-start command. See #2993153: Draft "Getting Started" Outline & Guide. I've also opened #2993155: Draft "Evaluator Guide" Outline & Guide, #2993152: Draft "Configuration Management" Outline & Guide, and #2993152: Draft "Configuration Management" Outline & Guide.

Identify initiative coordinator(s) - @grasmash has offered to help lead this initiative.
Get product management sign-off on idea
We have sign off from the documentation working group to pursue this.

(After that) Develop more detailed implementation plans, including biksehedding the particulars about each guide (in other words, please don't delve into "tool A vs. tool B" details here... ;)).

This will be done in individual issues, such as #2993155: Draft "Evaluator Guide" Outline & Guide, #2993152: Draft "Configuration Management" Outline & Guide, and #2993152: Draft "Configuration Management" Outline & Guide.

I think we're currently missing a new issue for the Composer Guide (can't see it in Grashmash's profile posts and Configuration Management is duplicated).