The IRC meeting just wrapped, summary to be posted to g.d.o. by addi soon.

I feel like a salmon swimming upstream on this, but I feel the need to try one more pitch.

Regarding the creation of a D6-specific Getting Started guide - please don't.

From the official Doc writer's guide (currently under review):

Versions: There is only one set of documentation handbooks, since many pages apply to all versions of Drupal; since there are insufficient resources to maintain different sets of handbooks for different versions of Drupal; since inconsistencies would develop between parallel versions due to only one book being corrected when the problem affects both; and since guidance on the only available version is often useful to the reader who has a different version.
Information for different Drupal versions can be kept together on one page or separated on different pages. It is generally preferred to cover information for all the versions on a single page, but if instructions for the different Drupal versions differ substantially, separate pages are appropriate. Use the "Drupal version" drop-down menu and select which version(s) the page applies to.

If each version is dealt with on a separate page:

* Organize the pages on the same hierarchical level.
* Include the version number at the end of the title, so that one page is titled "Example topic, v. 5.x" and the next is "Example topic, v. 4.7."

If multiple versions are dealt with on one page:

* Select all the versions which the page applies to in the "Drupal version" drop-down menu.
* Information on the page should be listed from newest to oldest version.
* Mark the sub-sections for each version very clearly.
* If there are no separate subsections for the different versions because the entire page applies to all versions selected in the "Drupal version" drop-down menu, state so early in the page, so that readers don't wonder which sub-sections apply to their version.

----------------

Addi's reasoning for forking the GS guide was that it's quicker and easier (it's needed now) and that the HTML shouldnt' get out of sync with the PDF.

My case:

I don't see how doing it this way:

  • bulk copy D5 GS to a new D6 GS
  • -start editing new D6 GS

is any quicker than this way:

  • rename D5 GS to Drupal GS
  • start editing new Drupal GS
    • Stuff that applies to both D5 and D6 (IMO most of it) stays in
      pages along the "main spine"
    • Stuff that only applies to D5 gets moved to sub-pages labeled "for D5"
    • New sub-pages get created and marked "for D6"

And I think the PDF should just be an output medium for the master content on d.o.

IMO the advantages of having one non-version-specific GS doc greatly outweigh the little bit of complexity added.

Advantage of not forking the doc - further edits, improvements and
re-organizations benefit users of both versions.

Disadvantage of forking - edits improvements and re-organizations in
one book should be reflected in both books separately, but as this
doubles the work it doesn't happen. Information that may be useful to
users of version X only shows up in the other version's book.

If we go ahead with this, can we please make it the only handbook exception?

Or change the guidelines for doc writers (-1000 from me)

Obviously this whole issue stems from the fact that we're using Book, which only allows a node to have one parent in a single navigation hierarchy.

If at some point we have automated filter-the-view-by-version or something similar to the automatically-generated API docs, that will fix the problem in a much better way.

/end rantish soapbox

Comments

HansBKK’s picture

HansBKK commented
Title: Please don't split any more doc-topics by specific version. » No more version-specific books (GS?)

clearer title

although I mean major branches within books also, except perhaps when iterating through code-specific function lists, etc.

My general recommendation:

Main navigation hierarchy based on topic/function/user-role.

Content in the "main spine" page relevant to D5+D6.
Content specific to a version in clearly labeled sub-pages.

add1sun’s picture

add1sun commented

I do agree with your arguments to not duplicate content. The original idea behind creating a complete, per version guide was so that we could have a definitive PDF for download for each version of Drupal and have a matching online handbook to go with it. It was supposed to go into the CVS repository and be truly versioned but that sort of just never happened for a number of reasons. I still want to have "shippable" complete GS guides for a particular version of Drupal, but I think it is going to take some serious thought and planing from several angles.

My current leading thought is to use the advanced help module and create a documentation module that can be installed on any Drupal site and contain the Getting Started guide for that version. That is all well and good, but the issue of syncing that with Drupal.org is tricky (as it was the D5 guide docbook attempt too). So, perhaps we should just ignore that for now since we have no handy solution to implement anytime soon.

I dare say that *splitting* content out in the future is easier than merging it back together. So, while I did say let's just duplicate and roll, I'm open to changing that tack. If we do then we need to decide quickly so we can continue with implementation ASAP. Let's sort this out in this queue by Monday, November 24 (or earlier if we can) so Shai and others who want to work on this know which way they are headed.

leehunter’s picture

leehunter commented

My very strong preference is to not duplicate content if at all possible. Duplicated content is an absolute nightmare to maintain, especially in this kind of ad-hoc environment because (unless you lock down one version of a page) you'll immediately get people making different changes to each version of a page and inevitably important stuff like corrections and clarifications will get lost or mangled.

Having said that, I don't feel like I understand the resources and priorities of the documentation team well enough to say whether it absolutely should be done one way or another.

If it's helpful to the decision, I should note that I'm willing to put significant effort into getting the docs into a more rational structure. I've done a lot of this kind of restructuring before (it's what I do for a living and I have a bit of a passion for it) so it might go faster than we expect.

rcross’s picture

rcross commented

I am completely for version-specific documentation. I actually have posted several times about this, and have an issue in the queue for this.

I think that this is an issue of a large deficiency in the documentation tools, not in the logical reasoning of our policies. I look at in in the same way as our code - we don't try to keep deprecated code in the same file, why should we do that with our documentation?
I think the biggest reason for not doing this is because there is not an easy way to duplicate/branch any documentation. We should be able to have branches for our documentation in the same way that we have for the code. This means that our documentation continues to improve and evolve with time, without needing to either remove or keepup outdated documentation and it doesn't mean that some documentation can not be maintained across all drupal versions, like project history or current maintainers. You see the concept of version specific documentation all the time with commercial tech books.

Anyone want to read a microsoft windows book that covers everything from windows 3.1 to windows vista?

HansBKK’s picture

HansBKK commented

rcross, you're absolutely right, the docs should be kept in better tools. And IMO, have paid professionals building them along with the development cycle so they are ready to be published the same time a new release ships.

But while we're running on Book and relying on the community to volunteer to write docs in bits and pieces over time, the docs team has decided that version-specific docs are just not realistic.

Except APIs of course, which ARE kept in sync with the code and automatically generated.

leehunter’s picture

leehunter commented

I'm also very keen on version-specific books but, for the reasons Hans mentioned, it has to be done by single-sourcing as much as possible any shared content.

Part of the solution might be there already. Since pages are now tagged with the version it should be simple to filter the content by version. In other words, if you click the Drupal 6 Theming Guide, you'd actually get much the same body of content as when you click the Drupal 5 Theming Guide, only with the D5 and earlier stuff filtered out.

But before you reach that point, you'd still have to consolidate everything so that it's reasonably consistent in terms of structure and so that you've got all the more generic stuff factored out.

I think there's also a lot of potential in using CVS, but as Add1sun was saying, there might be some heavy lifting involved in getting that set up properly.

HansBKK’s picture

HansBKK commented
Title: No more version-specific books (GS?) » Getting Started Must Die!

http://groups.drupal.org/node/15965#comment-58092

Gee Lee don't hold yourself back :)

You're right in that just having GS then pretty much everything else tossed into Beyond the Basics is not useful. And having version-specific branching right at the top is, well everyone knows how I feel about that :), but if there's any place this is most inappropriate, IMO it's here.

I reckon the introductory conceptual overview should all be at the top, it's before you "get started", perhaps "Introduction to" or "Understanding Drupal". There should be a succinct description of what Drupal is usually used for, not the underlying information architecture, not all the possibilities, but what does it usually do for non-wizards more or less out of the box (the box meaning DrupALL, eliminate the "core vs contrib" dichotomy at this stage, as that's completely arbitrary as far as the user's concerned. Sub-pages can add more IA detail, the CMF vs CMS stuff, and examples of what more knowledgable people can make it do (and the fact that wizards can make it do anything :)

So all this is pure conceptual, addressing the needs of a complete stranger, orienting them gently into the jargon and various components. For those that already have a decent idea, all this should be clearly marked so they can skip it and get to the real Getting Started.

Which should be procedural but IMO high-level, specifically designed to help the noob get to the point where they can start checking Drupal out, walking them through a sequence of what's ahead in the next part of the learning curve. Not too much detail here, or where would you stop? just link out to the more detailed content. Of course it should include installation, but after a more helpful "choosing your version" page. The install sections need to include (or link to) tips on problems with shared hosting, which generates a lot of help requests. Then theming should be referenced pretty early on, and an overview of the different types of modules, with descriptions of the major ones.

IMO the whole thing should print out to less than twenty pages.

leehunter’s picture

leehunter commented

Well, I posted on the rethinking docs thread because I didn't want to hijack this issue which started out with a much narrower scope. But now that we're here...

I think we're close to being on the same page, but there really should be a completely separate installation guide (ideally available from the main landing page) that is only about installation and nothing else: in other words, what are the system requirements, how do you prepare for it, how do you do an installation, what are the alternative ways of installing (e.g. multi-site) and what do you do if your installation goes amok.

The reason for a separate guide is that the installation process has a very sharply defined scope and it's something that people expect to see at the top of the main documentation page. In a large IT or webhosting environment, you can print out your Installation Guide and hand it to Joe the Application Installer (the cousin of Joe the Plumber). His manager has given approval to install a PHP/MySQL application on the web server and now the installer expects to see a succinct explanation of how to do it. He doesn't need to know anything about what Drupal is, why you need it, or what you're going to do with it.

Also if you're a consultant selling a Drupal solution to a large corporation you might be expected to show that your solution is based on a mature application that comes with a complete set of documentation. If there's not even an installation guide, you might get some funny looks.

All the stuff about why you would choose Drupal, what you can do with it, etc belongs somewhere else and I'm not sure that "Getting Started" is such a great title for it because "getting started" can mean different things to different people and different people are actually going to need completely different starting points (to get started with adding a CSS file to a theme, a designer doesn't necessarily need to know why Drupal is such a cool application). And to me, getting started is an action phrase that means actually doing things as opposed to just reading about them. I would maybe go with the "Understanding Drupal" heading you suggested, but make it for the entire handbook. That tells me right away that this is strictly conceptual information. If I want to understand Drupal, I know that it's for me, otherwise if I have a narrow functional role in the website (installing the app for example) I can ignore it.

This all speaks to the big issue of how we organize all the documentation. I'm very confident that the big pieces would fall into place very smoothly if we fit the handbooks to the important user roles, rather than expect everyone who uses the docs to progress through a pre-ordained path until they become a general expert.

HansBKK’s picture

HansBKK commented

+1 on what you say Lee. I self-hijacked the thread because I thought your title might get some attention, get some feedback to Addi and the others in GS workgroup.

I didn't mean that Installation details should be included, but that it should definitely be addressed and linked to. And to the extent it does have meaning, Getting Started to me means with using Drupal for someone who's never actually touched it.

First comes the (separate not part of GS) big-picture intro/overview stuff (Introduction to Drupal) which would include the functionality/comparison information that would be included in "why should I choose Drupal" or "what is Drupal for".

Then if the visitor thinks "yes, I'd like to check it out", meaning start having a hands-on look at Drupal - that's the point at which they should be directed to the GS content. Customization topics, well you've already started haven't you? It's the bridge, the very first procedural documentation to getting yourself to the point where you can actually start doing (anything). Of course it's not just cookbook howto, there also needs to be a lot of conceptual information, more details that the person who hasn't yet decided to check it out doesn't need.

Maybe expand the title? "Getting Started with Drupal". Then analogs - "Getting Started with Theming" "Getting Started with Module Development" (next year :)

add1sun’s picture

add1sun commented

Hm, I'm getting ready to go to the airport so this will be brief, general response, now that we've morphed into "what is the getting started section."

First, I agree that the Getting Started book is broader than I'd like. It is something I've been tossing around a bit in my head. I think that the whole idea of overview, introduction, evaluator stuff is fuzzy and spread out between GS and the About books. The whole lot of it needs to be considered so I think having these conversations is great BUT at this point I really think all of this should be happening in the Redesign thread and not here. The very idea of GS page or section, or "About" even being a "handbook" is one thing that the redesign looks to be moving to change (which I'm not averse to). I'd really rather not monkey tremendously with either book until we have a better idea of the redesign, so this conversation does belong there and not as a doc team task at the moment.

Wolfflow’s picture

Wolfflow commented

Hi All,

I tried to read carefully the content and comments of this issue. I know I'm not an expert in organizing and write clear argumentations, but at the end you know I insist and hopefully I make me understand.

The first what come up immediately is that we all have great Ideas on how to:

(@add1sun)

I still want to have "shippable" complete GS guides for a particular version of Drupal

and (@HansBKK)

the whole thing should print out to less than twenty pages...

and (@LeeHunter)

put significant effort into getting the docs into a more rational structure

.

But at the end most proposed issues in regard end up to (@add1sun)

I'd really rather not monkey tremendously with either book until we have a better idea of the redesign, so this conversation does belong there and not as a doc team task at the moment.

So I have to give my vote to +1 to @add1sun, we have to wait that the redesign work will be finished and applied to drupal.org and then see what can be implemented for all the here mentioned ideas.

Chhers

HansBKK’s picture

HansBKK commented
Status: Active » Closed (fixed)

OK, to be continued over there: http://groups.drupal.org/node/15965

senpai’s picture

senpai commented
Status: Closed (fixed) » Fixed

I've added an issue on preventing documentation forking to the Docs Queue that pertains directly to the discussion above. Please comment on it at http://drupal.org/node/339456

Status: Fixed » Closed (fixed)

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