Quite often when making changes to a page that only serves as a container for other pages, I find myself having to add unnecessary words for no other reason than meeting the new 25 word minimum. This is both a hassle for the person making the changes and a bit of extra burden for the reader. Often I feel like I'm adding nothing better than yada yada yada just to fill up the difference.

Can we reduce the minimum, to maybe 15 words or, even better, not require a minimum for people on the documentation team?

Comments

johnnoc’s picture

johnnoc
Primary language Norwegian Bokmål
Location Oslo
commented

reducing the minimum word limit for all users may not be ideal as we might get a lot of pages that lack useful content. If it's possible for no min word limit requirement just for handbook maintainers then i guess it's ok. On the other hand, 25 words are not so much, i guess it wouldn't be a problem for the handbook maintainers to fill that up... it's just about 2 til 3 sentences.

leehunter’s picture

leehunter commented

Whether it's two sentences or twenty, we shouldn't be writing *anything* that isn't really needed. It's a waste of effort, it creates more stuff to be reviewed and maintained, and it forces the reader to plow through more verbal noise.

webernet’s picture

webernet commented
Status: Active » Closed (won't fix)

Maybe you should rethink whether a 'Container page' is appropriate at all if you're having a hard time coming up with 25 words to fill it.

leehunter’s picture

leehunter commented
Status: Closed (won't fix) » Active

I've reopened this issue.

I've been a senior technical editor in the software industry for many years and I think I can judge very well whether text is needed or not. When it's not needed it should *always* be removed as a matter of course.

This is the first place I've ever seen verbosity made mandatory.

In some cases a container page does not need a lengthy overview because the contents of the section are very well communicated by the headings of the child pages. Simply restating that information in an overview is pointless and makes the page harder to maintain (if one of the child pages is moved or archived the overview has to be rewritten).

Forcing people to dream up useless text also slows down the work of restructuring and it puts a needless burden on the reader (many of whom are not native English speakers).

johnnoc’s picture

johnnoc
Primary language Norwegian Bokmål
Location Oslo
commented

I think reducing the minimum number of words has more negative repercussion than positive. There will be more reviewing and maintaining if a user can write a page in 15 words.

I also do not agree on the point of NNEs. It's not verbosity but it's explaining thoroughly. I work a lot with NNEs, and living in Norway, I also work a lot with non-native norwegian speakers. I think they will appreciate and understand a longer well explained sentence/s rather than a concise one better. To get a point across, explaining things like you're explaining the birds and the bees to a child is always more effective.

+1 on comment #3's status

leehunter’s picture

leehunter commented

I don't see why it means more pages. If people want to create a page they will do it. If there's a minimum word limit, they just add more words (whether those extra words are needed or not).

It's nice to think that people are explaining things more thoroughly but from my own experience I know for sure that this is not the case.

Here's an example of what I'm talking about. I wanted to change the title of a section from "5.x" to "Creating Drupal 5.x Modules" because I thought the original title wasn't very helpful (especially if someone landed there from somewhere else). The actual body was perfectly fine because the *real* information was in the list of child pages. But the minimum word limit forced me to write an extra couple of sentences. Since I didn't have anything to say on the subject, what I added only repeated *what was already visible*.

http://drupal.org/node/231275/revisions/view/264069/421110

That's not to say that someone could not come along and write a good overview that added more value to the page, but the existing text ("How to create modules in Drupal 5.x") was perfectly adequate for the time being since the *purpose* of the page is only to gather a set of related child pages.

add1sun’s picture

add1sun commented

Right, so I can see both sides of the argument here and originally I think this was added to try to deter spam and test pages (which, it doesn't really). At the end of the day what Lee says is pretty spot. We all just end up adding gibberish to fill the minimum when we don't have time or there isn't a lot to say. So, I'd be for reducing or removing the minimum requirement. If that really is just too much for people then, we should at least remove it for doc admins (documentation maintainer role).

webchick’s picture

webchick
she/they
Primary language English
Location Vancouver 🇨🇦
commented

FWIW, I hate this setting to the very pit of my soul. I've had to put in garbage text on certain landing pages just to get this validation message to go away.

I've also been reading Don't Make Me Think! and one of the chapters there is called Remove Needless Text. He challenges web writers to cut down the text they have by half, and then cut it in half again. We shouldn't be encouraging our contributors to be more verbose than is necessary.

johnnoc’s picture

johnnoc
Primary language Norwegian Bokmål
Location Oslo
commented

My point on #5 is what Addi mentioned on #7 (spam and test pages) and that is what I'm afraid of. If we're really confident that it doesn't help and we will also not be bombarded by lots of unfinished pages, then I do not have any problem with reducing/removing the word limit. To be safe, I'd be for removing it for doc admins only though.

webernet’s picture

webernet commented

I'm not against removing the limit, but I am against empty 'list of child pages' pages.

All pages including 'Landing'/'Container' pages should have content in them. Usually one of the child pages contains the information that should have been in the parent page in the first place.

leehunter’s picture

leehunter commented

I agree, except where the overview is long (more than a single screen). In that case it's much much better to move it to a new child page. If we don't do that, the really important list of child pages (i.e. the task oriented content) disappears off the bottom of the screen making it very likely that the reader will miss it completely. On the web, people generally don't give more than a quick glance to a page. If it doesn't appear to deliver what they're looking for, they go somewhere else.

johnnoc’s picture

johnnoc
Primary language Norwegian Bokmål
Location Oslo
commented
Issue tags: +planning sprint
sime’s picture

sime
any/any
Location Melbourne
commented

Do we have evidence that removing the minimum word limit increases spam or nonsense pages significantly?

It would be better to remove a page in a no-brainer way than to disrupt the writing flow of people who are thinking-it-with-drupal.

Let's reduce it.

leehunter’s picture

leehunter commented
Status: Active » Fixed

Status: Fixed » Closed (fixed)

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

vm’s picture

vm commented

This discussion is carried over to : http://drupal.org/node/648148

where this has become an issue with blank test pages being submitted to drupal.org