Posted by add1sun on September 6, 2008 at 3:27pm
| Project: | Documentation |
| Version: | 6.x-1.x-dev |
| Component: | New documentation |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
This issue stems from a discussion in IRC and on the mail list re: creating a vocabulary of terms to flag the status of handbook pages. The documentation team can then use those flags to create lists (with views) and effect the appearance of pages to give readers a clue about what may be going on with it.
A rough suggestion for terms is:
Stub page
Outdated
Insecure code
Please give feedback and suggest terms/rewording that you think would be useful.
Another point to consider before we implement this, is whether or not to remove the select list for this from the node add/edit form for regular users (easily achieved by a hook_form_alter in drupalorg.module).
Comments
#1
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
#2
Sure thing. Do you have a suggestion for another term we can use for stub pages?
#3
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 ?
#4
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.
#5
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.
#6
+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.
#7
re: stub page, I'm partial to placeholder, though incomplete works for me too.
#8
+1 for explanatory text on the incomplete page regardless of the term used. :)
#9
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
#10
I'm not sure what Michelle is using but there is the Term Message module. I have my eye on it to use for this, though it will need to go through cleanup and scrutiny to get on d.o. Benjamin has said that he is willing to work on this though, since he originally made it pretty much for this use case on d.o.
In terms of the list are we OK with these for starts?
- Incomplete
- Outdated
- Insecure code
Maybe the name of the vocabulary could be "Page status"? But we don't have an OK status listed so that may confuse some folks. Hmm. Thoughts?
#11
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?
#12
Hrm, I think that I would rather keep the warning status as its own vocabulary, just for that, and make the locked/community flagging a separate thing (maybe not even a vocab in the end). First, because I honestly want more time to think about the "locked" flagging bit and the best way to implement/use it. Secondly, I think adding that as a flag to this list is just sort of confusing. I think it is much harder for people to decide what they should select there unless they are immersed in the "world of docs". The warnings seem much more straightforward to me. Maybe we should just have a "Warning status" vocabulary with those three terms (and a none option) and help text that says to leave it at none unless one of the three apply.
hmmm.
#13
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)
#14
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).
#15
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.
#16
+1 for #10 and +1 for 15 ;-)
#17
Agreed that organizing the content is a more accessible way is needed, i.e. audience. I'd rather keep this initial vocab to the "warning status" kind of thing and take up any "organizing" vocabs a bit more down the road as we have time to work with the redesign team.
So in terms of presenting the vocab for warnings, I like emmajane's list in #14. What do others think? I'd like to implement this this week to assist with creating the Getting Involved book.
#18
+1 for #17 (#14) - just comes in mind "What about to add Moved to the list?
#19
ok, I'm going to move this to webmasters queue for feedback from admins. I can make this change myself but I want to make sure I'm allowed to first.
to be clear to the webmasters, the proposal is to:
- Add a new vocabulary ("Handbook page status", "Page status"?)
- Applies only to book content type
- Contains the terms:
--- No known issues
--- Incomplete
--- Outdated
--- Insecure code
#20
#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
#21
#19 definitely +1 for me
#22
OK, I made the new vocab. We can tweak it as we need to. Please open a new issue if you think there should be changes to the terms or the help text.
#23
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 :-/
#24
The only problem with moving a page to the outdated book is that you lose its position in the handbook. When the page is updated, you have to figure out where it goes.
I'd like for a subtle distinction - though I know that is hard to articulate/determine. The outdated vocab can be used for things like a D4.7 version of a snippet that can be upgraded to D6, while moving to the outdated book is for things that can't actually be updated. In that respect that should probably be an "Archive" instead.
#25
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...
#26
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...
#27
Reopening the issue. Yeah, I was thinking about this over the weekend and the idea I came up with is:
If the page is simply outdated but would still be useful if updated, then use the vocabulary term but leave it where it is.
If the page is just irrelevant anymore and no amount of "updating" will make it so, then move it to the Archive book so we can get rid of clutter.
It would be nice to still have the archive pages marked as such for theming/message so that if someone stumbles across them they will know at a glance what kind of info it is. Should we add an "Archive" vocabulary? Should we change the Outdated term (Need upgrade?) that makes it clearly different from Archive? Let's hash out some ideas and then write up some guidelines.
#28
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.
#29
""Archived" doesn't have the same "deprecated" meaning it needs. "
How about we use "Deprecated"? :-)
#30
+1 for the terms Deprecated and Needs updating :)
#31
+1 for the terms Deprecated and Needs updating. ditto
#32
OK, Outdated has been changed to Needs updating and I've added Deprecated.
We need to document the policy on moving pages to Archive and marking Deprecated as well as making sure that the new vocab is generally documented somewhere, including the distinction between Needs updating and Deprecated. I'm moving this to Docs until we get the documentation part of it done.
#33
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!
#34
In my mind the existing log field works fine for that. When a status is changed the changer should explain why in the log.
#35
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
#36
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.
#37
Automatically closed -- issue fixed for 2 weeks with no activity.