Jennifer Hodgdon and I met at PNWDS and had a quick brain-dump about a plan. Here it is! I'll split these off into other sub-issues soon; just want a place to park this for now that's not an email. :)

We have the need of 4 main resources:

One D8 landing page to rule them all!

Somewhat similar to https://drupal.org/drupal-7.0 but expanded to cover specific target audiences, the idea is a single landing page that is widely publicized which helps answer FAQs like "what features are in D8?" "how do I upgrade to it?" "what documentation is available?" etc. and would point off to the resources down below. The Drupal.org Content Working Group is actively working on this, with an "end of Q4" target. I have a call with them sometime this week/next week to find out more.

For now, this is going to happen at https://drupal.org/drupal-8.0 and there are some content notes there. Later, there will be a really nicely designed site for this information.

Re-organized "Develop for Drupal" section

https://drupal.org/documentation/develop is a mishmash of D6, D7, and D8 code with no clear delineation of what applies to which version. While what we ultimately need is some means of cleanly identifying this from the backend side, lacking that infrastructure (which hopefully can be worked on once d.o D7 launches which is "soonish"), it really doesn't feel like this can wait. Drupal is currently inaccessible to grok for new people, so we need a place where we can work on making this more accessible RIGHT NOW.

What Jennifer recommended was adding D6/D7/D8 sections underneath both https://drupal.org/developing/modules and https://drupal.org/developing/api and moving the pages beneath that describe individual components to wherever the latest version they apply to is. The other pages should get pointers over to it, and in the case where the text applies 80% to D7 except for one part, add a paragraph denoting this. This would get us started in the direction of contextual versions without needing code changes.

Somewhere in here, I'd also like to incorporate the nice work that was done on the D8 community video curriculum lesson outline at https://github.com/xjm/d8_videos, and in the sub-pages add a "resources" section for now that points to good blog posts/presentations on these topics to at least get *something* started that people can add to. I feel like once this framework is in place, we can probably crowd-source at least some of the raw authoring work. In any event, we can definitely cross-link the videos/tutorials for those things once they're available.

Revamped "Contribute to Drupal 8" section

https://drupal.org/community-initiatives/drupal-core was useful up until feature freeze, but since then it's sort of lingered and is no longer reflecting what people are actually working on and where we really need help. I want to revamp this to provide things like a "countdown" of critical issues, pointers to tools like Examples module, Coder Upgrade, etc. where people can jump in and help port those, and a weekly or so "hit-list" of the most important issues we need eyeballs on, regardless of the initiatives. I mothballed the current page under "Previous / Inactive initiatives" at https://drupal.org/node/2107085 since for the most part these initiatives either happened already or aren't happening for D8 after all.

Revamped and expanded api.d.o landing page and "Topics" list for D8

Right now if you go to https://api.drupal.org/api/drupal/8 (which most people will) there's nothing remarkably different about this page than any other Drupal versions, and it's lacking pointers to huge changes in D8 like services, dependency injection, plugins and annotations, etc.

I've created a separate meta issue for this at: #2106873: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable

Comments

xjm’s picture

Also see: http://d8cx.org/api-examples (which attempts to aggregate stuff that's been published not-on-d.o).

eojthebrave’s picture

I think in addition to getting our existing content more organized it would also be good for us to start thinking about additional landing pages and/or ways of presenting the information in a logical order so that people who are looking to get started with D8 can find a single place to go which then links off to other d.o. and non d.o. resources. One of the things that I find challenging about the documentation we have now is that it's hard to find what you're looking for, and it's even harder to know which core concepts you need to understand first before diving in somewhere else. OOP basic before Annotations before Plugins for example. Or Routing before "Creating a Hello World page."

There's a lot of really good detailed information working with this specific API but not a whole lot of "Where should I start", and "Guide me through learning this", at least not that I've been able to find yet.

Do we have a way to start mapping out what we have and what should get moved under these new D6/7/8 sections or is this just a lets start moving things and see what happens?

eojthebrave’s picture

Issue summary: View changes

Updated issue summary.

webchick’s picture

I think atm it's "let's start moving things and see what happens" which is definitely not a great "end goal" plan, but is at least a start at seeing what we've got and what we need. :)

Btw, I have access to Google Analytics for d.o, and I can share some stats that may be of interest. These are the following pages by # of page views:

#1: / (the home page) — 600,000 views in the past month
#2: /download
#4: /project/drupal
#6: /start
#8: /documentation/install
#9: /documentation
#16: /requirements
#36: /about
#37: /community
#39: /community-initiatives/drupal-core (20,000 views in the last month) Surprised it's that high... I guess from the front-page ad that cycles?
#40: /documentation/install/download
#46: /documentation/install/create-database
#49: /documentation/understand
#50: /planet
#52: /documentation/install/settings-file
#53: /documentation/theme
#58: /documentation/administer
#60: /documentation/build
#80: /documentation/concepts
#103: /documentation/install/modules-themes
#121: /core/release-cycle
#123: /best-practices
#142: /documentation/structure
#148: /theme-guide/6-7
#149: /getting-started/before/overview
#169: /developing/modules — 6,700 views in the last month
#173: /documentation/install/modules-themes/modules-7
#189: /requirements/webserver
#227: /getting-started/7/admin
#232: /upgrade
#250: /documentation/install/after
#254: /developing/api/database
#282: /documentation/develop — 4,600 views in the last month

Given that data, it seems like if we're going to spend energy fleshing out handbooks in the #170th and #282nd most-visited sections of the site, we are also going to need some good, healthy cross-linking at some of the top 10 pages in order for this work to have any meaningful impact. It also seems to imply that those sections of the handbook aren't nearly as well-trafficked as we might otherwise have thought. :\

Jennifer, do you have the ability to pull some kind of usage stats from api.d.o to find out what traffic is like over there so we could compare? It might be that it's actually better to centralize all efforts for developer documentation on that site instead.

webchick’s picture

For reference, smerrill just pulled the following Lucene query for me from Logstash:

request:\/api\/* NOT \/api\/search\/*

There were 3,222,320 hits (1,309,270 anonymous) to api.d.o since October 1 (so in less than a month). Interestingly, this seems to imply that api.d.o is more popular than Drupal.org. ;) I'm sure there's some further filtering that needs to happen here, but point being fairly starkly I think that when developers are looking for info, they're going to api.d.o, not the Drupal.org Handbooks.

EDIT: Oooh, pretty graphs and stuff! https://docs.google.com/file/d/0B0P7mqGSyuntT2t5dnBVYlk1Z2s/edit?usp=sha...

webchick’s picture

Also, I (re-)learned recently that the https://drupal.org/project/documentation repository is where api.d.o pulls its main landing page and a few other things (like the form API reference). Possible we could start a "definitive" D8 developer guide there, where the access is locked down a bit better? Is that a silly idea? etc.

eojthebrave’s picture

Honestly I think we need to do some of both. We need to cleanup the existing handbook pages so they are more navigable, so it's clearer what is D8 and what is not, and continue to add more high level information about the Drupal module development process.

We can also work towards improving api.d.o, and especially if those numbers are anywhere close to true this could be a great funnel to the handbook. It makes sense that people are finding api.d.o first, and using it a lot since really it is the main documentation for our code-base, and ... people who have already got a grasp on documentation are much more likely to look things up there than on d.o.

However, it is currently a wasteland for people who are new to module development. If I've never written a module before, or even if I have but I'm just new to D8 where do I start on this page? https://api.drupal.org/api/drupal/8

This seems like a really good opportunity to do some cross promotion and to begin to provide a "new to drupal? start here", "new to d8? start here" funnel that we can use to walk people through essential concepts and introduce things in a logical order. My guess is there are very few people who start learning Drupal module development through the database abstraction layer or the node access system. :P

Gábor Hojtsy’s picture

Absolutely agreed with @eojthebrave! The handbook is the community editable/organizable place where we can explain concepts, use images (woosh!), structure content, etc. We can/should cross-reference from the api docs, but the API site is NOT the place to provide overviews, tutorials, etc. It should proactively link back to the handbook for these.

webchick’s picture

I think that's probably right, but I just want to point out that the front page of api.d.o is simply pulled from http://drupalcode.org/project/documentation.git/blob/refs/heads/8.x-1.x:.... There is no technical reason that this needs to be so barren of "new to Drupal? start here!" conceptual info, nor a foregone conclusion that it cannot have images. :)

I think I agree though that the handbook's probably the best spot for longer-winded things due to the ease of editing it (though that also has its downfalls, in that people can insert complete wrong and confusing/duplicate crap). The battleplan at #2106873: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable (cross-linked in the issue summary) denotes that each of these top-level API topics should have 3-4 paras of "intro", linking off to the handbook for the "guts" of each topic. That'd probably work best with the "funnel people from api.d.o, where we know they already go" approach.

jhodgdon’s picture

I am not surprised by the low counts for developing/api and other programmer-related docs, as compared to d.o home or downloads. I imagine that the universe of "people who download and install Drupal and use it to build sites" is a lot less than the universe of "people who write their own modules for Drupal".

Also I am not surprised that api.d.o gets a lot more hits than d.o's developer-oriented sections. API is a reference site, so whenever you need info about a particular function, that is where you go. Also, at least in my experience, when I'm researching for a particular line of code I need to write/edit, I often generate 10 or more hits on api.d.o (like, I might go to one function, see how it's called, check a few more functions, etc.). It's much more likely I'll go to api.d.o while I'm developing than developing/api/* -- I would only read the developing/api/* page on a particular topic once or twice probably, then use api.d.o for reference after I've understood the background that developing/api/* should have in it. That doesn't mean we don't need developing/api/* -- I also hardly ever go to developing/modules because I know how to make a module, but that doesn't mean it isn't useful information the first time you go to create a module. Right?

So.

Yes, let's fix up the api.d.o landing pages for each major version of Drupal. webchick and I discussed this a bit at PNWDS last weekend, but we actually could put the landing page code into system.api.php for Drupal 8 at least, and get it out of the docs repository. Which I think would be a Good Thing (TM). Probably.

Then, we need to make sure that each system developers should know about has a Topic. We have an issue for that already:
#2106873: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable

And yes, each of these topics should be relatively short, and then link to an expanded page/section within developing/api.

jhodgdon’s picture

Component: routing system » documentation

Not sure why this was in "routing system"? :)

soulfroys’s picture

Inspiration: http://docs.ckeditor.com/#!/guide
(All of you probably already know it, but others might not)

Gábor Hojtsy’s picture

An update on the issue summary:

- https://drupal.org/drupal-8.0 launched! Also redirected to from https://drupal.org/8 for easier tweeting :)
- the creating Drupal 8 modules section has been expanded: https://drupal.org/developing/modules/8
- there is now a Drupal 8 APIs section a thttps://drupal.org/node/2116747 and several new pages have been written; a whole section on routes (yml, route providers, upcasting, access, etc), a new section on menu API (menu items, tabs), the config section was reworked, etc.

The rest is I believe still to be started.

jhodgdon’s picture

Yes, the new section is coming along!

However, on #2106873: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable we are making plans to move all the API reference and module building docs to api.drupal.org. I was going to say that https://drupal.org/drupal-8.0 would need an update to point to the new docs location, but since it doesn't apparently tell where to get any information for developers, I guess there is nothing to update yet.

jhodgdon’s picture

Issue summary: View changes

x

jhodgdon’s picture

Do we still need this issue? I am inclined to say no...

webchick’s picture

Status: Active » Fixed

Nope, I think this is officially done. There might be more things we can do, but they're fine to be other dedicated issues.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.