Core Conversations on documentation at DrupalCon?

The main thing that comes to mind is "What would the documentation team like to see in the core help system to make it not suck?"

Limitations of the current help system in core include:
- You must write patches in order to change the text; huge barrier of entry
- You can't use images (I guess technically you can, but it's not easy)
- Help constrained to a single page only; no sub-pages
- The table of contents is module-based, rather than topic-based
- The text cannot be changed after a stable release is out due to string freeze
- It therefore falls horribly out of sync with the documentation on Drupal.org
- Other stuff I'm sure I'm forgetting

I think there are two aspects of this:

1. What system do we want in core to display/navigate help pages? Earl Miles attempted to solve a lot of these problems with http://drupal.org/project/advanced_help module. However, I've not seen the documentation team really rally around this solution. http://drupal.org/node/299050 was a very sad patch to try and move some of that into core, but that didn't make it into D7, for a host of different reasons, but chiefly concerns about how text would be translated, and whether that was actually the right solution to the problem.

2. Integration with Drupal.org, if any, and if so to what extent. Do we use Drupal.org as the "master" copy of documentation, and periodically export to core/contrib modules? Do we get rid of a core help system altogether and only link to online docs? How about a "suggest a problem" type of functionality with the docs that posts an issue to Drupal.org? Other kinds of ideas you folks might have.

I fully agree with greggmarshall.

The general varied methods of getting Drupal help and participating... not clarified at all. :-(

Getting Help comes first
and if help is effective, then confident participation will simply follow. (!!)

The levels of doc abstraction (generality) and detail (specifics) can be MANY....

1. QuickStart = Easy Hands-On Overview (As If This Is Exactly What Is Needed AND All Will Just Work)

                                 Determining WHICH module(s) MAY best fit reqs is usually FIRST!  :-)
   
                The absence of high-level diagrams to detail functionality needs community help, folks!
   
                                 eg:  http://drupal.org/project/token   (sorry for the flagrant self-promo!)
   

2. Handbook = Read And Think About How This Is Done Best in Drupal (prerequisite skills should be no mystery)

3. OTHER? for what EXACTLY!!!!

I suggest that we consider leveraging links and tags to docs
that already exist to completely document features of the underlying LAMP technology stack:

L = LINUX = http://www.linux.org/

A = APACHE = apache.org

M = MySQL, Postgres, etc = dev.mysql.com

P = PHP = php.net

http://jquery.com/ Varied browser compatibility and testing, etc. http://seleniumhq.org/projects/ide/

Between nice graphics to help grasp functionality
and links to EXISTING docs for LAMP stack, we can make all of our lives easier.

Also, personal laptop and isp setups are a HUGE starting point in need of smart guidance and support!

Roadmap is a nice word to expand on here, esp with regard to documentation and participation!

Please feel free to disagree, as I learn more that way! Thanks all for caring and thinking!

http://drupal.meetup.com/9

I already wanted to solve this properly once for all, but the attempt was shot down by Drupal's trademark policy; my request was declined.

Actually I think it will help a lot if you have a few more high-level strategy goals for the year, or even 5 year-span. That will kind of help you set priorities, even if though there are many particulars as webchick and http://drupal.org/node/1005304 point out. You will be missing the overarching ideas, if you get lost in the details.

Thank you all for this discussion.

There are 3 things that make Drupal Rock:

1. community

2. code

3. docs (we are here)

@Arianek: Getting your job done now is surely top priority. Confirmed!
I recommend delegation to volunteers, asap.

You have my full support and apprec to Stay Focused, ;-)

AND To document and discuss current audiences and goals, (?where)

AND To help us all connect where we are now to where we need to go with Drupal Docs. (?NOW)

• Your focus for yourself is perfectly fine, but, respectfully,
  suppressing the big picture discussion for a year is simply not in our interest.
  Please tell us where there will be room for the following D7 discussions in January, 2011.

Big Picture Roadmap Topics Below Include:

1. Expert Roles (Themer/Dev/ProjMgr)

2. Expert Workflows (front end, app dev, project planning)

3. Diagrams beat words. Concrete example provided.

The lack of complete distinction
in Drupal Docs between Themer Design and Developer Best Practices is simply not ok.

There also might be some thought as to how to create an expert team, and not one hack claiming global expertise.

In my view,
the profound lack of clear prerequisites
and skills and tasks for Themers and Devs and Project Managers is bad for our Drupal community. VERY.

At the core of D7, there are again the core required modules (user, block, filter, node, system).
The code and logic of these few components is the foundation of Drupal data and processing.
IF you are a Drupal Developer, then that is not much to learn, folks!
IF you are a Drupal Themer, that is probably not necessary.

The two distinctions I am proposing are pretty pivotal to how to think about Docs going forward:

1. Right-Now Solution : Right Solution... as in Mr. Right vs Mr. Right-Now (seldom the same guy!)

2. Themer : Developer and how best practices are INCUMBENT upon both to some degree.

This is how to help create expertise,
instead of teeming hordes of Drupal Hacks who claim to know all and know nothing.

I am glad to learn plenty, YET This is Team Web Dev in 2011...
we all must be honest about where our expertise lay and where not.

For example, EVEN IF I learned CSS well, it is not my strength to work front end magic!

These distinctions are crucial to thinking through a high-quality lean and mean team.

Just defining Themer and Developer Training Prerequisites is not difficult...

ROLE: Drupal Themer
PREREQS: html, css, jquery, ?
REQUISITE SKILLS: basic php, Drupal setup and config local, Theming Training and Theme API

ROLE: Drupal Developer
PREREQS: php, mysql, scm, ?
REQUISITE SKILLS: intermediate php, Drupal 6-7 Core+ API

ROLE: DBA/NetAdmin
PREREQS: advanced dbms / net linux
REQUISITE SKILLS: Network LAMP app and operations support

ROLE: Project Manager
PREREQS: ?? Let's Talk!
REQUISITE SKILLS: ?? Let's Talk!

This does not mean that you cannot get started with an HONEST Themer and get a GREAT DEAL done.

It also does not mean that an Expert Themer cannot learn some Expert Project Management.

That is the VERY magic of Drupal, but the magic should NOT stop there!

The alternative is that Drupal people will be increasingly known as Jacks of All Trades...
YET MASTERS OF NONE!

That is already happening
and the EXPERTLESS CMS EPIDEMIC can be quelled with quality approaches to organizing docs and support.

Also, despite the fact that I am NOT an artist, per se,
I made a diagram for the Token module that saves interested users TONS of doc time.

http://drupal.org/project/token

It allows them to understand the module's functionality and also reference the docs and code with smarts.

This needs to be done for EVERY module in D6 and D7 core. Now.

@Bojhan: I agree with you about the value of road mapping Drupal 7.x docs, now.

That is how Drupal code was improved upon, and we should not take that team approach for granted.

As per @Arianek's points,
we need to Execute WHILE Thinking Big Picture. Is that ok?
That happens to be how our Beloved Drupal came into being and improved.

If we simply keep trudging along this path, Drupal will be buried in yet more oceans of docs.

Let me again affirm my appreciation for the evident hard work and devotion Jennifer and Arianek have.
That is earnest appreciation. I would like the fruits of their labors to be max effective across audiences.

Note that the diagram that I created for token module took me ~2hrs with Maintainer via IM.

I had already invested 30 minutes into reading the Token module code and docs, and understood little.
Paving that road for myself and other was good.

We need more efforts like that with regard to D6 and D7 Core Modules.
Pages and pages of docs that talk about 500 lines of code just seems increasingly strange and ineffective to me.

While technical, I am human first.
I like text, but I prefer to start with pictures. Don't you?

Feel free to disagree as I learn more that way.

Thank you all for grappling with the most crucial piece of Drupal.

1. Drupal distro's: using DITA it would be possible to create dita maps that incorporate existing documentation for each of the distro's rather than creating new documentation from scratch. We've done a proof of concept for Drupal-DITA integration at drupal.org/project/dita
2. Localization: I know several national Drupal community sites that have put together some sort of documentation in their national languages. If we provide the tools these could be translations living on d.o. documentation.
3. documentation client/server concept: http://drupal.org/project/advanced_help and http://drupal.org/project/helpinject show how it's possible to work with an online version of documentation that later get's codified into a offline documentation package. We've have a proof of concept for the client/server thing.
4. the Error and warning handlers could be simply automatically generated links next to the messages, that somehow strip out the site specific stuff (e.g. domain), and that send you to a wiki like page: if it doesn't yet exist you're invited to fill out the page...
5. Configuration dumps: check out http://drupal.org/project/fingerprint it is based on a features export of all the available exportables
6. The structured Drupal vocabulary: probably we could start this with a community site based of http://code.google.com/p/neologism/ with a wiki like workflow. Ideally though this would be a module that integrates with a Drupal related blog that let's you submit new terms into the centralized vocabulary straight from your blog.

A much more detailed description of what our current technical state is with these features is available at http://www.pronovix.com/blog/technologies-improved-infrastructure-drupal...

I posted one on improving the issue queue with summaries and handling documentation during the development process. Hope to have everybody's input.

A presentation for discussion is at

https://docs.google.com/present/edit?id=0ATSj3ekASkFxZGRzZDVzdzdfNDk3Y3F...

Thanks for starting this conversation arienek- I'm definitely interested in the Core Conversation on "Essential Docs", and would love to participate. One thing that's currently confusing to me is the separation between documentation and other sections of the site (esp. those that are open to the docs team, which I believe are all sections using book module, but I could be wrong).

I'm also very interested in figuring out better ways for people to get involved with what I would call the "marketing materials on d.o." (the about section, the landing pages for different sections, the homepage, etc), which I helped out with during the redesign, but for which there's not a clear way to get involved (to me). I'd also be very curious to know what other folks think of having some of the text on d.o. in hard-coded pages, which is the case with several of the pages for the redesign...