By chaloum on

Ok this is a rant so move a long if you don't want to see a rant

Drupal Documentation.
Who is writing this stuff?
Who are they writing if for?

I seems that most of the documentation is about the core and the rational behind the core, along with a few code fragments on how something might be used with the piece of core functionality. The documentation seem to be clearly focused on people writing for the drupal core not for people wanting the leverage the core

for example if I buy a book or search for some jquery functionality, I don't get a huge discussion on the rational for how the function was coded , but instead get clear and concise information on how to use the functionality.

Wording inconstancies and reinventions of terminology seem to the the flavour de jure for Drupal documentation. one minute it's referred to as a node next it's table when its always a table.

end of rant for the time being.

⋅ Categories: Drupal 7.x

Comments

WorldFallz’s picture

WorldFallz commented

The documentation is written by the community and there is an ongoing effort to completely redesign it atm.

However, in the meantime, you'll notice an 'edit' link at the top of almost every page-- any time you feel you can explain something better feel free to go ahead and do it.

Aminka Ozmun’s picture

Aminka Ozmun commented

I honestly don't think helping helps. I got banned (under a different handle) years ago because they told me, why don't you help out instead of complaining.

So I helped with documentation of the PageEar module but apparently they didn't mean that I could continue saying anything other than how wonderful Drupal is; "helping out" was meant in a "STFU" kind of way!

WorldFallz’s picture

WorldFallz commented

uh... i'm fairly certain I know what your other handle was and you were blocked for being abusive and condescending to other users in the forums.

We don't ban people because they speak against drupal-- we ban them for basically 2 reasons: 1) spamming and 2) repeatedly violating the http://drupal.org/dcoc.

It's not what you say, it's how you say it and how you treat fellow members of the community.

Aminka Ozmun’s picture

Aminka Ozmun commented

Not "what" but "how?"

So you admit that y'all value style over substance, correct?

Anyways:

Show me specific examples of me being "abusive" or "condescending" and I'll show you at least two people who are dancing rather happily together (or else why would they be "dancing?" It's not like people are forced to respond to others' commentary).

The problem with the charges of being "abusive" and "condescending" (especially "condescending") is that you people are thin-skinned and so most anything less than outright obsequiousness if complaining about something will rub y'all the wrong way.

Again, cite specific examples. Otherwise, you're actually just engaged in rumor-mongering -- which must be against your precious code of conduct, no?

zirvap’s picture

zirvap commented

As WorldFallz said, the docs are written by volunteers. That means:

  • You'll only find the doc pages that people have chosen to contribute, so it's very likely that some topics will be missing because noone has chosen to write those specific docs
  • You'll find pages written by lots of different people, who may or may not have paid attention to the style guide and terminology used in related docs, so it's very likely that terminology is inconsistent

There are volunteers who work on coordinating the doc efforts, and try to identify the most important missing docs and get them written, but the task is huge. So you're very, very welcome to help out!

Some things you can do:

  • If you notice problems that you can fix yoursef, such as a page using "node" when it should have been "table", simply edit the page, as WordFallz said. (Make sure you understand Drupal's use of the term node, though.)
  • If some documentation is missing, and you don't have enough knowledge to write the missing docs, write an issue in the docs issue queue. Unfortunately, there's no guarantee that a volunteer will decide to spend time writing the page you want, but there's some chance, at least.
  • If you notice other problems, such as docs that are badly organized, hard to find, outdated, or whatever, and you don't know how to fix it yourself, write an issue.