Define documentation vocabulary

My to Cent: Just for simplify "Flagging" , as a NEN I had to search the term "Stub" to understand what it does mean. Were it possible to use "Flags" that are easer to understand for a broader quantity of Peoples visiting Drupal.org?

Thanks

Just toke a look at : http://thesaurus.reference.com/browse/stub for "Stub"

2 results for: stub 1-2 of 2 results

1. Synonym Collection v1.1
Main Entry: stub
Part of Speech: noun
Synonyms: bump, butt, counterfoil, crush, extinguish, receipt, remainder, remnant, snag, stump

2. Roget's II: The New Thesaurus
Main Entry: end
Part of Speech: noun
Definition: Residual matter.
Synonyms: butt, fragment, ort, scrap, shard

I cannot say which term under those above may be much easer and simply to associate to "Stup page"
as I'm not an english language expert. Maybe there is one that is more common known and can be used with "page"

Edit:

My suggestion: incomplete page ?

A stub page is definitely a familiar term for those used to Wiki editing, although a completely unfamiliar term outside of this context. See: http://en.wikipedia.org/wiki/Wikipedia:Stub

Looking through the language from Wikipedia page I wonder if there is some merit to any of:
- Holding page
- Starter or
- Preliminary page

I think the Wikipedia page does an excellent job of explaining "stub." I also like their default text that appears on the page explaining to people that the page needs to be expanded. This helps to "train" users on the use of the terminology.

Ok, with it. But definitively I will add the term, if not already done yet, to Common english expression & acronyms used on Drupal.org for those new to Wiki management and add your provided link. Thanks.

+1 to this general idea. I think this will be valuable data, both for people looking for things that need to be done, and for readers who are trying to understand whether or not a given page is relevant or complete.

I'd vote for either using the term "stub page" and defining it in place, the way Wikipedia does (as suggested by emmajane in #4), or using the term "incomplete page". But, even in the second case, a short piece of explanatory text might be nice.

+1 for explanatory text on the incomplete page regardless of the term used. :)

I'm not sure what the plan is in terms of visual implementation, but I really liked this example from Michelle's site. I thought I'd attach it here to keep ideas together. :) The URL for the page is here: http://shellmultimedia.com/tutorials/user-profiles-version-2

There was also an idea to have "Community pages" vs. "Handbook"/locked pages. (Yes, I know, we're opening it up.) I wonder if there is some merit in having two versions of "ok" where it's Documentation-team verified vs. Community-contributed? Or maybe a hierarchical taxonomy with:

[Page Status]
OK
- Community contributed
- Peer-reviewed

Warning
- Incomplete
- Outdated
- Insecure code

More thoughts?

A common complaint is that beginner-users find themselves looking at developer-coder documentation.

Could/should we have 'audience' tags to distinguish between the things that can be done in the UI (users) and the things involved in installation/troubleshooting/upgrading (admin) and actual code and theme developer stuff (developer)

What about:
Warning Status
- No known issues (default)
- Incomplete
- Outdated
- Insecure code

I like the idea of having audience tags...how can we implement it in a way that doesn't encourage people to get so narrow that they don't read across to other pages when it's relevant to them? I'm thinking specifically about theme_ functions in modules (and their relevance to themers, even though it's in a module).

There is certainly too much crossover between theme and developer for me to distinguish.
But if we could filter the handbooks down to those pages fit to be a client-end-user guide to point the human people at once the webmaster has finished building the thing, that would be friendly.

Using the CMS rather than changing the CMS. Yeah, there's lots of cross-over still. Is adding a custom block "content management" or "site building"?
...I don't have the full answer, but would be in favour of trimming, removing or filtering portions of the handbook a bit more rigorously.

+1 for #10 and +1 for 15 ;-)

+1 for #17 (#14) - just comes in mind "What about to add Moved to the list?

#19 gets my +1 with the caveat that I said on IRC that insecure code should be unpublished as well as flagged. I think this will go a long way towards helping users use the docs. Right now, it's hard to tell if any given page is really usable. Sure it gets version flagged but that often doesn't really convey the meaning "this is outdated". They may wonder, "It says 5.x but will it work on 6.x?". If it gets marked outdated, then it's clear that it doesn't work with the latest core version. I also like incomplete better than stub. Because it may be more than a stub but still not finished. Having it be a term means it's easy to get a quick list of all incomplete docs if someone is looking for something to work on.

Sorry, got a bit rambly there, but very much +1. :)

Michelle

#19 definitely +1 for me

I was going to add a note re this change to the documentation writers guide with instructions on how to use this vocab. ... but then it seems pretty self-explanatory!
However, how does this 'outdated' flag compare with the 'archive' process described at the bottom of the docs page? Shall we do both? Or is this flag to be a better system?
My feeling is that putting 'outdated' in the title and removing it from the menu is actually more effective :-/

So
"outdated.a" is "Needs updating" - needs attention to apply to the current release.
"outdated.b" is "No longer relevant" - archived and kept only to avoid linkrot.

Renamed "outdated" into "needs updating" I guess. "archive" is not specific enough...

Looking for guidance...
OK, so I look at this page in the troubleshooting handbook that appears to refer to a pre-D5 issue.
I considered flagging it 'outdated' as in 'totally redundant, problem no longer occurs, we don't care'
Is using the vocab selector actually useful here? Does it make any difference yet, or will it? What is the way I should proceed here when filtering pages like this - trying to remove irrelevant items from the book here...

Maybe there is a subtle difference between "out of date" and "outdated". Maybe too subtle ;-)

outdated.a = "Needs updating" is OK by me. Sounds a little negative but it should only be used as a TODO flag.
outdated.b = "expired" ? "retired" ?
... "Archived" doesn't have the same "deprecated" meaning it needs. It's too vague, sometimes 'archiving' is what you do to the valuable data.

I agree that theming the retired pages is necessary. Like a grey background or something similar to how 'unpublished' nodes are visually flagged to editors. At least a warning banner at the top.

+1 for the terms Deprecated and Needs updating :)

+1 for the terms Deprecated and Needs updating. ditto

IMO an additional text field is needed to make this really fly. For example, if a page is incomplete, what is missing? If it needs updating, what on the page is out-of-date? Admittedly this can be handled to some extent by adding stuff to the page itself or adding a comment, but that's pretty untidy and rather defeats the object of the vocab.

But being able to tag a page as "needs updating" and add in an adjacent field "The snippet in 3rd paragraph only works for 5.x, need version for 6.x" - now that would be useful!

Yes, that thought had crossed my mind, but at the moment that's not really how the Log field is used (for example, http://drupal.org/handbook/updates doesn't show any status changes *), and besides it's visually far removed from the Status field at present. The Log field is associated with a particular revision, whereas a status text field would be persistent until changed.

If I visit a handbook page and see Page Status = incomplete and a message about what's missing (perhaps at the top of the page ... like the example on Michelle's site) then I might be motivated to add the missing info. if I know it. If I just see Incomplete I'm unlikely to hit Revisions and search down for any info about what's missing just in case the relevant editor remembered to include information about what is missing and also on the offchance that I might know something about the thing that is stated as being missing, assuming it is stated. ;)

BTW just to make clear - I do fully support all these efforts to improve docs and appreciate that this is not a simple matter!

(*) possibly this means that the status field is not being used

Added Depreciated here: http://drupal.org/node/302146

Anyone else have any other locations? Marked as Fixed so that this will eventually go away from deep within the issue querry.