Home › Feed aggregator › Sources

Documentation Team

Syndicate content
News about ongoing work and ways to get involved with the Drupal.org Documentation Team
URL: http://groups.drupal.org/not_used/14492
Updated: 8 hours 35 min ago

when to use what HTML markup documentation/style guide?

Tue, 2010/02/23 - 10:18pm

Is there some Drupal documentation or a style guide which explains when to use what HTML markup?

For example, when to use <div class="section">, <div class="content">, <p>

  • or when to use <h1>, <h2>, <h3>, etc.

  • or when to use <div class="description">

I found the Drupal Markup Style Guide, http://groups.drupal.org/node/6355

^ which has some excellent "high level" guide lines - what I can't find is a catalog of Drupal classes and when to use them or what their purpose/meaning/rationale is

Does this exist?

Documentation Team

Building an awesome technical communication CMS

Tue, 2010/02/23 - 1:42am

In the not too distant future - perhaps soon after D7 work is finished - the Drupal handbooks will move to their own site within Drupal.org and hopefully the doc folks will then have much more control over their tools and templates. While it's very exciting to think that we'll finally be able to address some of our challenges - just adding Views would be amazing - I've been thinking that there's an opportunity here to do something that is WAY more awesome. Something that could return huge dividends to the Drupal docs.

What I'm thinking is that we could do more than just solve our own problem, we could use this opportunity to put together the foundation of a true technical communication CMS and release it into the wild. Perhaps even someday have an installation profile that delivers a complete technical communication CMS that anyone can pick up and run with.

The big potential payoff for Drupal docs is that by sharing our docs solution with the world we will hopefully get uptake from all manner of commercial and open source doc teams and that they will, in turn, have a vested interested in making the Drupal docs platform even more awesome by giving back ideas and code.

Some of the pieces (eg taxonomy and user access) are already baked into core and some can be added through standard modules (eg. views). But there are other pieces of a really awesome techcomm CMS which, as far as I know, are not currently available in Drupal or would require a lot of customization. Some things may have to be built from scratch. And it would be nice to have a really well integrated interface that ties everything together.

Here's a rough idea of what this beast might look like:

IMPORT TOOL - Ability to import XML-based content in DITA, DocBook, or custom formats. Able to monitor file folders or external databases/repositories for changed content and synch automatically or on demand.

ADMIN INTERFACE - Manage workflow, schema, taxonomy, GUIDs etc.

AUTHORING TOOL - WYSIWYG interface for creating and editing schema-compliant content. The writer can easily apply tags to content (but only the permitted tags for a given context!). The author can be given suggestions and prompts. There is a mechanism for conditional text (i.e. the writer can tag text and images so that different versions can appear in different publications). All this would require a lot of JQuery love to be usable.

PUBLISHING/EXPORT TOOL - Provides drag-and-drop interface for organizing content into single sourced publications (i.e. the same chunk can appear in many places). The publications can be web-based, PDF, XML, online Help etc. Different versions can be built using tags and conditional text.

Now I'm not saying that we should necessarily build any or all of this. Some of those features might never be useful for the Drupal handbooks. But I'd like to plant this idea that there might be value in thinking of the new Drupal docs site as the first step in creating a truly awesome platform for ANY kind of technical communication, one that will hopefully grow to become a project distinct from the Drupal documentation and with a community that is using it to manage technical communication for all kinds of products and projects.

What do you think?

Documentation Team

Standards for documenting classes and interfaces

Mon, 2010/02/22 - 5:58pm

There's a discussion going on about standards for documenting classes and interfaces in the Drupal API -- please comment on the issue (and NOT here) if interested:
http://drupal.org/node/718596

Documentation Team

Workflow for Drupalversity - how to contribute!

Sun, 2010/02/14 - 9:40pm

Now that this project has started to move, I've started to think about it less in terms of something that I can build myself and more in terms of a bigger project that lots of different people can contribute to, usually in a relatively small way.

One of the biggest problems with projects like this is reaching consensus with regards to what the finished project will look like. I think that the project could be really held back if we spend too much time on this sort of thing; conversely, it will really fly if it is developed in such a way that anyone is able to muck in when they have five minutes to spare.

I have therefore slightly remodelled the main wiki page so that it is easier to contribute in the following ways:

  • There are now four "streams": beginners (BEG), site building and administration (SBA), theming (THE), and development (DEV).
  • Under each of these streams there is a header titled "Stuff that definitely needs to be covered in the {name of stream} stream.
  • If you want to see something covered in a particular stream, add it under that header. You can add anything, as big or as small as you like. For example, the THE stream should really cover preprocess functions. Don't worry that this is a big subject; just add it to the list. Someone else can break it up into smaller chunks (or you can, if you really want to!). The point here is that we can all quickly note down what we think each stream should cover; we'll worry about the rest later.
  • Similarly, there are other areas of the page that you can use to quickly add individual tutorials, or websites that contain a number of tutorials. Again, don't worry about the details: just get stuff down on paper. We'll deal with organising all of this stuff later.
  • Finally, if you are a Drupal newbie, you are the most valuable people of all for this project. Note down your own experience of learning Drupal: what you wanted to learn, how you went about learning it, what resources were useful, where you got stuck. Someone has already done this on the wiki; just follow their lead, or add your own wiki page if you like. Even if you're a more experienced Drupal user, you're going to be learning new stuff all the time: please add your own experiences to the wiki.

Does this all make sense? Anyone got any questions or ideas?

Documentation Team

Controlled (and owned) vs Contrib Documentation

Sun, 2010/02/14 - 8:30am

I've been toying with some questions surrounding our perpetual difficulty with docs, and our tendency to burn through docs contributors (perceived... maybe not actual).

Question: Why is it possible to have at least two or three books published, perhaps more, that blow away anything we have on d.o in their clarity, scope, and accuracy? I'm thinking of Pro Drupal Development, for example, which has a clearer statement of what's going on in Drupal code than anywhere else. Why couldn't we have a doc of that quality in our repertoire? The subversion project does? The git project has two. jQuery has two websites that take your breath away in their conciseness and clarity (and interactivity).

My theory is that it may because we focus on only community documentation, which by its nature gets fragmented. People just scratch their little itch and it all gets out of hand so quickly.

Could we create a comprehensive, high-quality tutorial or reference like git or subversion or jquery have, and maintain it? How would we do that? Would it break our community culture? Could it be properly maintained? Why is the absolute best documentation being done outside our community, in the book publishing world?

Looking forward to your answers.

Documentation Team

Drupal 7 Doc Sprints

Sun, 2010/02/14 - 2:59am
Start:  2010-02-16 04:00 - 06:00 America/Los_Angeles Organizers:  jhodgdon Virtual meeting (eg. IRC meeting, Drupal Dojo)

I'm going to be hosting Drupal 7 documentation sprints on the #drupal-docs IRC channel.

My plan is to have them on Tuesday afternoons from 4pm to 6pm, Seattle time, for the next few weeks (find your time). I'll edit this post again if/when I decide to stop having sprints or schedule more. So far, I'm definitely planning sprints on Feb 16, Feb 23, Mar 2, and Mar 9.

You're all invited (beginner with Drupal, beginner with Doc, expert at everything, anything in between). We can find some way for you to help.

Drupal 7 tasks to be tackled: http://drupal.org/node/515870

I also invite anyone else who has time to organize a virtual sprint -- there's still a lot to be done to get documentation in shape for Drupal 7!

Documentation Team

Getting organized

Sat, 2010/02/13 - 11:43pm

This weekend in Seattle I met up with a few folks to talk about some larger documentation team issues which have come to light as a result of a tumultuous year for me personally, which caused me to withdraw from the community and my role as doc team lead. I realize that as the Drupal community has grown and changed, we have outgrown a model where one person alone can coordinate such a huge area as documentation. I asked several people, who had stepped in to fill leadership gaps and contacted me about general leadership concerns, to help me come up with a better plan for a sustainable doc team organization.

Based on various discussions over the last year, it seems that part of the solution involves improving the channels for communication and another part involves sharing leadership with as many people as possible. I feel that these changes will not only help us get docs back on track, but will make the documentation team stronger and more flexible as we head on down the road.

Communications

In the past, this group page (http://groups.drupal.org/documentation-team) was for announcements only. It's now open so that you can join, start discussions, and post events, and it will be the central clearinghouse for news and discussions about the documentation effort. This will make getting involved more discoverable and let us integrate our work with other groups in the Drupal community through cross-posting. Please note that this group only replaces the mailing list and not the documentation issue queue. The RSS feed for this group is http://groups.drupal.org/node/14492/feed

To avoid overlapping channels of communication, the documentation mailing list has been closed.

Roles and responsibilities

As the documentation has grown in size and complexity, more people are needed to coordinate and facilitate documentation activities. In addition to myself, who will continue as the overall documentation coordinator, the following people have volunteered to help with specific areas:

This information and a documentation team overview has been added to the handbook on the Documentation team page. There's still a need for more people to take on coordination roles, especially in various content areas. If you have a passion and/or expertise in a particular part of the documentation and you'd like to help make sure that it's current and complete, please contact me or one of the above coordinators directly.

The coordinators' role involves several activities:

  • Identifying gaps and troubleshooting problems
  • Acting as a resource for people with questions and concerns
  • Helping new folks get up to speed and involved

It's important to note that the coordinator role is not a gatekeeper or taskmaster, it is a resource. As always, everyone is encouraged to jump in anywhere and any time you see an opportunity to improve the documentation. What's new is that we now have people who will make themselves available to provide feedback and guidance where needed.

Questions, comments or suggestions? Let's discuss it here!

Documentation Team

Drupalversity (original wiki page)

Wed, 2010/02/10 - 2:08pm

We've been booted out of our own group (the reasons given made sense) so I'm re-posting to this to other groups.

This is the original Drupalversity wiki page that was originally at http://groups.drupal.org/node/44418. I fully expect it to be broken up into subpages at some point.

This page will contain a few trial Drupalversity courses.

Tracks

Tracks are broad subject areas which Drupal can be divided into. Much like a degree in Mathematics might be divided into tracks in algebra, analysis, mathematical methods and medhanics, Drupal can be divided into three tracks: site building and administration, theming and development. In addition to this, a separate foundation track, Beginning Drupal can broadly be compared to a pre-university course in Mathematics that teaches the basics, and can then be relied upon in the other tracks.

Courses

Each track is subdivided into courses, much like how the analysis track in a Mathematics degree might be divided into courses titled Analysis 1, Analysis 2, Analysis 3: Complex Analysis, Analysis 4: Real Analysis, and so on. While tracks are designed to be indepent (but with some inevitable overlap), courses build on each other.

Each course will make use of existing material as often as possible. It is not the intention of this project to create new learning materials: there are plenty of those already. Instead, Drupalversity will organise these materials to make them more accessible, and to make learning Drupal more proactive (what should I learn next?) than reactive (this project has to be finished by the end of today and I need to know how Views Bulk Operations works).

Course numbers are made up of three letters followed by three numbers. The three letters indicate the track that the course is part of:

  • BEG for beginners' courses
  • SBA for site building and administration
  • THM for theming courses
  • DEV for development courses

The three numbers are, for the moment, arbitrary. I'm sure we'll be able to come up with some sort of classification system if we need one later.

Beginners' courses

Course codes for this track start BEG.

Stuff that definitely needs to be covered in the BEG track:
  • Drupal Concepts and Terminology
    • This should be some kind of subsection, so we can get all the terminology sorted out in one place: a glossary, I guess.
  • Setting up a local server:
    • Acquia DAMP or XAMPP
    • MAMP
  • Installing Drupal 6
  • Basics of configuring Drupal 6
  • Admin Interface
  • Core modules
  • Contrib modules
    • How to work out which contrib modules to use (maybe this goes in SBA?)
    • How to install modules
  • Creating a page
  • Menus
  • Core themes
  • How to install and enable themes
  • Content types
  • Blocks
  • Aliases (do you mean URL aliases?)
  • Roles and Permissions
Potential courses for the BEG track Site building and administration courses

Course codes for this track start SBA.

Stuff that definitely needs to be covered in the SBA track:
  • CCK
  • Views
  • Drush
  • Image handling
  • Input filters
  • WYSIWYG
  • Managing content (probably want to use a custom module like CMF for this)
  • Managing users (again, using a custom module- Advanced User?)
  • Menus
  • SEO? Using the SEO Checklist
  • Date and time settings
  • The file system?
  • Blocks
  • Taxonomy
  • Comments
  • Basic site settings (everything in the "Site Information" bit)
  • Reports (Watchdog etc)
  • The Command Line
      • Setting up Cygwin
    • Basic CLI stuff (there's a good Lullabot video tute on this)
    • Source control? git?
    • Setting up shortcuts with bashrc etc - based on the (non-free) peepcode tutorial
  • Monitoring performace (parts, or all, of this should go under DEV maybe):
    • The Devel Performance sub-module
    • Benchmarking and profiling Drupal: http://drupal.org/node/79237
      • Apache Bench
      • The standard performance testing environment
      • Profiling memory usage

Potential courses for the SBA track
  • Introduction to building sites with Drupal (take from the Drupal Cookbook)
    • Image handling
      • Image cache
  • Advanced Drupal site-building and administration
    • Drush
  • CCK
    • Introduction to CCK
    • Important field types and widgets
  • Views
    • Introduction to Views
Theming courses

Course codes for this track start THM.

Stuff that definitely needs to be covered in the THM track:
  • Creating sub-themes
  • Where to get good free Drupal themes (do we bother with paid-for themes? I'm thinking not)
  • Preprocess functions
  • Themable functions
  • Basics of programming - done, see below
  • Adding regions
  • jQuery in Drupal theming
  • Javascript in Drupal theming
Potential courses for the THM track Fundamentals of programming - THM901

Many graphic designers who want to become themers have never done any programming, but they need to understand conditional logic, variables and arrays to be able to use the theming system. No-one tells them this, though. I searched around on the net and couldn't find anything that did the job well enough, so I ended up writing something here. It covers:

  • Input, processing, output, and comments
  • Variables
  • Operators and concatenators
  • Arrays
  • Conditional logic
  • Functions
  • Objects
Development courses

Course codes for this track start DEV.

Stuff that definitely needs to be covered in the DEV track:
  • Introduction to Drupal development: following one of the standard example modules being built

  • Token integration
  • Views integration
  • CCK integration
  • The Node Access system
  • Devel module
  • Coder module
  • Coding standards
  • CVS (or whatever source control Drupal ends up using)
  • Contributing your module to the community
  • Cointributing to Drupal core

    • Potential courses for the DEV track Resource dump

    If you find good resources that could be referenced by a course, add a link here. We can then build the resources into courses as they are written.

    Blogs etc that we can go through to find useful articles Stuff from lullabot.com that can be used Drupal learning experiences

    A really useful way that Drupal newbies can contributed to the Drupalversity project is to keep a record of their Drupal learning experience: what they knew about Drupal and web development and design when they started; what they wanted to be able to do; what resources they used; where they got stuck. This sort of narrative is invaluable when it comes to writing Drupalversity courses. Stick your learning experience record below!

    totsubo's learning experience

    In order to help contribute to the University here's a list of issues I faced when first starting with Drupal, some resources that helped me out, and things I learned along the way.

    I wanted to set up an Internet site for a hobby that would have the following properties/functions:

    1. Let me sell stuff, i.e. be an online store
    2. Be an online community where other hobbyist could share info and come together
    3. Be bilingual English/Japanese

    I started looking around the web for a free solution that would meet all three requirements. I mostly concentrated on #1 and #3 and didn't give much thought to #2. I was waffling between Zen cart and OsCommerce when someone on the Zen cart forums suggested I have a look at Drupal and a Drupal module called Ubercart. I looked and liked! The Drupal + Ubercart combination seemed to fill all my needs.

    Resource #1: Ubercart http://www.ubercart.org/

    Issue #1: What did I need in order to build a Drupal site

    I'm an IT guy so anything I built was always for the company I worked for which meant I always had a server and the necessary infrastructure all set up for me. But when it came to building a personal web site I had no idea what was needed. Luckily I had friend who had a Wordpress site and he explained to me the basics of finding a hosting solution.

    Even after this was all explained to me I was still really worried that I would pick the wrong hosting solution and I'd have spent money registering for a service that wouldn't fit my needs and wouldn't support Drupal.

    Issue #2: What do you need in a hosting solution in order to support Drupal?

    Now that I've been using Drupal for 2 months I have an idea what the answer to #2 is but I don't know the answer with 100% accuracy. In my case I might have just gotten lucky and picked a good hosting solution, who knows. One thing to point out is that some hosting site actually say they 'come with Drupal' or something like that. Mine did not, but it was listed on the list of hosting solutions that support Drupal. This I found confusing, why would Drupal list you as a host that is Drupal friendly but the host itself doesn't advertise this?

    My advice, contact the hosting company directly and simply ask, do you support Drupal. Being new to all this I was very afraid of sounded like an idiot, but they were very friendly and helpful. Plus, if they aren't friendly and helpful, it might be a sign that you shouldn't do business with them :)

    That's it for now. Coming later:

    1. Installing Drupal issues
    2. Issues figuring out how to install modules
    3. So many settings!
    4. Installing Ubercart issues
    5. i18n: the bane of my existence
    6. Advanced Forums
    7. Themes, Acquia Marina
    8. WYSIWYG + tinyMCE
    9. Creating a cutom content type, CCK fields
    10. Location
    11. GMap
    12. Views
      1. Setting up a GMap view
      2. Replacing the default Blog page with a custom View
    13. And lots more ...
    Documentation Team

    Drupalversity

    Sat, 2010/01/02 - 5:26am

    I've discussed this idea to some extent on the dev and docs mailing lists, it was suggested that I also post here. In brief:

    I think it would be great if we (the broad Drupal community) could put together a series of online courses which teach people different aspects of Drupal.

    This differs from new documentation. Indeed, it doesn't necessarily require any new documentation and could make use of documentation that is already available online. A "course", in this sense, is a structured document that links to pieces of documentation - whether they be text tuturials, videos, exercises, or something else entirely - and helps someone move further down a particular track of learning about Drupal.

    The Drupal Cookbook is a great example of what I consider to be a course in this context. In fact, it could be described as "Drupal 101: Beginning Drupal". Other courses would very likely be more specialised, focusing on theming, say, or contributing to Drupal Core, or more popular modules such as CCK and Views.

    Drupalversity would address a number of shortcomings in Drupal documentation viewed on the macro level. There is tons of great documentation out there, both in the form of books and (usually free) online resources, but this documentation is, by and large, reactive. If you have a particular thing you want to be able to do with Drupal then it is often possible to find documentation that will help you do what you want to do and get your project finished. But if you just want to learn more about jQuery and how it works wit Drupal then things are less easy. Worse still is trying to answer the question, "I currently know X, Y and Z about Drupal - what should I learn next?".

    Traditionally, Universities and structured education solve these problems, and that's what I'd like Drupalversity to do. There would be no teaching, assessment or accreditation (although training companies could use courses to teach from). It would be really cool if some Drupal rockstars could give a little time over to consult on what should go in a course that covers their field of expertise: Crell on databases in Drupal, webchick on contributing to Drupal core, merlinofchaos on Views, etc. This isn't necessary, though, and I certainly see the courses as being a collaborative effort where we try to reach informed consensus.

    So, what do y'all think?

    Drupal Kata

    Why I believe this group is needed

    Sun, 2009/12/27 - 5:52am

    Hi,

    Since I wanted to keep the group description shortish, I thought it would be a good idea to give some more background information to why I believe this group is needed.

    I discovered Drupal about a year and half ago. Since then I have learned a lot, as well as thinking about ways to use it for my own projects and business ideas. It has now come as far as I am planning to launch my first real Drupal based website in a few weeks.

    Launching a site to the world dramatically changes, and limits, the freedom for further improvements of it, especially when it comes to changing existing live functionality. New sections and features can generally only be added as long as they follow the design specification, look and feel of the existing site.

    Anything that links to the live site, be it search engines or other sites, need to know that what they link to will be accessible in the future. Even though pathauto let me configure it to keep old links, it would only create unnecessary future complications if I tinker too much with structure and URL's.

    A while ago I started to search for information and guides about how to solve some of the issues I have identified will happen when the site officially is live:

    • Proper Project Management for development.
    • Setting up a development and testing environment that mirrors the live site.
    • Organisational processes to manage the development, testing, implementation and roll out of changes and/or adding new features to the live site to minimise risk for downtime as well as "screw-ups" due to bad planning (i.e. knowledge).
    • How to document and backport changes to the live site to the dev/test servers.
    • What changes and adjustments needed when more people get involved working on the site.

    Unfortunately I didn't manage to find much I found useful, so I began working out my own plan.

    Then it struck me that this must be something than more or less everyone developing Drupal sites are facing. That made me even more confused about the lack of available information.

    Sure, many generic software development project management templates and process strategies will probably work just fine for Drupal developers with a little tweaking.

    But I am no expert on project management and most of the other stuff involved in this. I also think there are a lot more like me out there searching for this information.

    Also I believe there are quite a few areas where these templates and processes needs to be tailored to really be simple to apply on development of Drupal based websites.

    The best way of addressing this I could come up with was to create this group where we can discuss and exchange experience.

    That way we can all help creating documents, guides, templates, protocol's, checklists and so on that will cover the needs for efficient development, testing and rollouts.

    I know for sure that I have far from the knowledge and expertise needed to, for example, produce a process of rolling out a new feature on a live site as efficiently as possible. My choice right now seems to be to more or less trial and error. Learn from that and slowly evolve my own processes to be more efficient and automated.

    If I had access to generic test protocols and checkslist, for example about how to test a newly developed feature for my live site, it would save me a lot of time. If I also had a guide on how to write an implementation guide for the rollout I would minimise the risk of "skipping" any important steps because I simply don't have the knowledge yet. Being able to do that would also minimise the downtime and risks to the live site when the rollout starts.

    I believe that a lot of this is more or less the same for the majority of Drupal sites. Much like simpletest has made testing Drupal Core and Contribs much more efficient. This group might be able to do the same for custom development of features on existing live sites.

    If we together can create this information I am sure it will have many positive effects:

    • It will give Drupal beginners as well as people with limited project management skills a wonderful source of knowledge.
    • By collaborating we can together create tailored processes, project management templates, test protocols, check lists, etc for Drupal.
    • Drupal Core, module and theme developers will get valuable insight to the processes used in development, testing and roll out of both new websites and the new issues that are faced after the site is live.

    I think that right now more or less every individual or organisation is inventing its own new wheel when it comes to this. Its, in my opinion, a waste of knowledge.

    Looking at what Drupal 7 is focusing a lot on, usability and scalability, this is something that that is going to be important to address to make it easier for beginners as well as larger organisations to start using Drupal.

    If this group can result in "blue prints" that will aid the maintenance, administration and development of Drupal based sites it will save a lot of time that instead can be put into "real" development.

    My plan right now is to try and find a process and strategy that works for my current needs, a shared hosting solution, but that can be scaled and changed as the needs grow.

    As soon as I have come a bit further, and got some structure, with this I will create a page in this group outlining for everyone to see and discuss. I hope I will get a lot of valuable feedback from all of you that I can use to improve working on it. Hopefully it will be good enough to also make it into the Drupal Handbook.

    My goal is also that this will be something useful for everyone else in the community to save time as well as more efficiently be able to develop sites.

    In the meantime I would be most interested in your feedback to this post.

    It would be even more fantastic to read about the processes, etc you are using for these issues. Please feel free to post in this group about it.

    Documentation Team