Posted by jhodgdon on September 12, 2011 at 9:22pm
As a (partial) follow-up to Towards Docs Sustainability... Here is a proposal (or the beginnings of a proposal) for a major structural revision to how we do documentation on Drupal.org, and to the Documentation team.
Your suggestions and ideas are welcome! Please comment below, and then I'll go back and edit this proposal to incorporate the great suggestions I'm sure you will have.
Note: This is a work in progress, and may have been edited since you last looked at it, or since someone made a particular comment... sorry for any confusion!
- The documentation that is currently at http://drupal.org/documentation (formerly known as the Handbook in past years) will now become the Community Documentation Wiki. This will also include the non-documentation content on Drupal.org (such as the About Drupal book and the Contributing book).
- This will make it clearer to the community as a whole that they are welcome to edit and add pages in the Wiki. Undoubtedly some sidebars and headers will need to be redone a bit to make it clear what's part of the Wiki.
- The Wiki will have its own project and issue queue, with components corresponding to the top-level books. Current issues in the Documentation issue queue (except API Docs issues) will be moved to the Wiki issue queue.
- Work on the Wiki will be coordinated by section coordinators (corresponding to top-level books). Each section coordinator will coordinate work (writing, revision, content overseeing, issue queue farming, etc.) on that section of the wiki.
- Current Wiki infrastructure improvements in progress that we need in order to launch this:
- Allow all d.o users to embed images safely into Wiki pages, so that no special permissions will be needed to edit the pages on the Wiki (see issue http://drupal.org/node/528682). Once that is done, we'll also need to migrate pages in the Wiki away from the Documentation input format so that regular folks can edit them (possibly this will be on a case-by-case basis?), and remove special Documentation privs from most users (see discussion on http://drupal.org/node/1275424).
- Turn off Wiki comments, once we have a viable alternative (see issues http://drupal.org/node/995292 and http://drupal.org/node/810508).
- Reference field so Wiki pages can reference projects, and projects can see a list of related Wiki pages (see issue http://drupal.org/node/733908).
- Are there other infrastructure improvements needed right away? Video infrastructure? Markdown formatting? ???
- We will create a directory of Off Drupal.org Documentation (real name to be determined). The basic idea is that there is a lot of documentation out there that is useful, but people want to retain ownership of it (post it on their corp web sites, blogs, etc.). There have recently been several ideas floating around in the Dojo, Padewan, Open Learning Inititaive, Kata, etc. about creating a directory like this... It probably needs to be on Drupal.org and under the umbrella of the Documentation Team. Ideas: [this is a new idea and needs to be fleshed out!]:
- The content for this directory will be maintained like a Wiki section (probably in the Wiki issue queue, or could be a separate project/queue).
- Items in the Directory would be Nodes, with basic information fields: title, URL, description.
- Items would have a Project node reference so you could state what projects the item is documenting (multi-valued).
- Items would need to have some taxonomies, like Level (beginning, etc.), Audience (site builder, themer, etc. - reused from the Wiki), ???
- There would be a View that would let you do a filtered search for these items. But since they are nodes, they would also come up in d.o and google searches presumably.
- It might be possible for Lin Clark's ideas about RDFa tags or microdata on Planet posts to be used to automatically create new items (or at least proposed item?) as people post to Planet with tutorial-type material. Lin is talking about doing something else with this... maybe could be incorporated?
- We will create a new content type (or at least a dedicated input format), and a new section on Drupal.org for "Curated Documentation" (name to be determined).
- Ariane will be the coordinator for this documentation (at least for now).
- Its issues will be managed in an issue queue that is separate from the Wiki issue queue.
- Editing pages in the curated documentation will be role-limited, and creating new pages will not be done without discussion of why we need a new section (an even smaller group would have permission to create new pages).
- We will move certain pages from the Wiki to this section (perhaps the Install Guide and Upgrade Guide, or at least the top-level pages for them?).
- Johan Falk has generously offered to donate the entire text of his "Drupal 7: The Essentials" book to Drupal.org, and we would like this to go into the Curated Docs area.
- We will also continue to work on a new Help system for Drupal 8, and in conjunction, a set of curated module-related documentation. That is separate from this d.o curated doc, and it will be DITA-like, task-based, and really aimed more at inline help (i.e. the help you see when you install Drupal) rather than tutorials and guides (the main aim of the d.o docs). See http://drupal.org/node/1095012 for full discussion of this effort.
- Responsibilities of the Docs team leadership will become:
- Maintaining the Wiki, Curated, and Outside docs infrastructure.
- Recruiting volunteers for all Documentation components.
- Recruiting section coordinators for the Wiki and Outside Directory
- Directly overseeing the Curated docs, the API docs, and the new help system docs.
Comments
Off D.O. Documentation
For adding tutorial links to off Drupal.org sites - How do we assure that links are still valid over time? I've found that tutorial sites frequently come and go. Perhaps Linkchecker module?
For the Curated Docs, do you think D.O. would ever publish a formal printed Drupal.org manual just based on these curated docs?
http://www.webbfx.net/
Hmmm...
Good question about the links... Not sure about linkchecker, but we should definitely have a "report a broken link" link on the pages.
Regarding a printed manual - I'm not sure, but you are right we should consider a way to export a PDF version or something like that.
And maybe we should include books in the "outside docs" directory? And reviews of the outside docs? Hmmm.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
ePub
If we're going to have an export format for the "canonical" documentation, I think ePub is probably a much more practical and useful format than PDF these days. And it kills fewer rainforests.
Export to both :-)
I don't know of a reason for either/or here. We should be able to export to both ePub and PDF. PDF is still the format that everybody in the world knows how to use.
I'd be more concerned that we be able to export to something meaningful. The current book module is so incredibly antiquated and what it gathers together for a single export is almost unusable. So making the export readable and usable would be more important in my book than the format (but let's do both)
Thanks so much for getting
Thanks so much for getting down on "paper" some of the stuff we've been hashing out over the last couple months!
I have some suggestions/opinions/amendments to the above - of course up for discussion, my opinion isn't final by any means...
1) Docs wiki
2) Offsite content
We should probably leave this as a second stage of work so that when we do it, we can do it properly and fully focus on this, and wait to see how Lin's work with the project reference module goes. I think the idea with that is that it would alleviate us from needing to keep the offsite content on D.o in any form. We would just need to build the infrastructure (an aggregator, view with search, and the SPARQL endpoint db), and get anyone who wants their content searchable to use the necessary modules. Then all the off-site content would be indexed and searchable without needing it to be on D.o.
3) Core/curated docs
4) Help system
Sounds good!
5) Responsibilities
Here is how I see the roles/responsibilities panning out:
I've purposely left out wiki maintenance, as I think that should really be left up to the community, that's the whole point of turning the massive amount of docs content loose as a wiki. And I've also left out overseeing the curated docs, as the content itself should not need maintenance, only the infra for it.
Whew, I think that about covers it for now!
ps. I'm of two minds on comments
ps. I'm of two minds on comments with these latest turns of events. The reason I originally wanted to close comments and funnel feedback into issues and forums was because of the maintenance burden. I'm not sure it makes sense to funnel feedback into issues if there is no maintainer watching them, and if the comments don't need managing, then maybe we should just allow them? Can't even believe I'm writing this, but just trying to be open minded now that plans are changing...
Some more thoughts...
a) Names and URLs - definitely open to revision, those were just working titles so that I could refer to them in the text. But I don't think we can (at this point) easily move the entire Wiki (or whatever it's called) to a sub-site. ??? Too many references...
b) Agreed that the off-site docs index could be a later phase project -- it is a new idea. And I am not sure Lin's idea of indexing planet posts with special RDFa tags will really suffice, but yeah, let's think about that later.
c) Wiki section coordinators... My feeling is that if we don't recruit section coordinators, we are basically saying "the Wiki is not maintained or overseen at all by the Documentation Team". In which case, that seems to mean that we don't have a "Documentation Team" that anyone can join -- we're only inviting a select few to contribute to the curated docs, and the rest is just "the community" who can add to and edit the Wiki, which will surely devolve even further into a complete mess without any oversight at all. Is that what we want?
That would also (I think) mean:
- No reason to have docs sprints
- No reason to recruit large numbers of new docs contributors
(In both cases, I would say aside from API docs, which are a separate issue and not really a problem right now for sustainability anyway)
Again, is that what we want? And is that acceptable to the Drupal community at large?
Note that I'm not suggesting that Ariane should be the overseer of the Wiki coordinators. I'm just asking whether in principle we still want to have some oversight on the Wiki and a large "documentation team" that anyone can join. My proposal above suggested a route to spreading out the oversight responsibilities, but I still think we need people who can answer questions, coordinate volunteer writers, and watch the issue queues for the Wiki (or sections thereof). And I still think it is of value to the Drupal community to have a "documentation team" that anyone can join just by contributing to the wiki. We can't do that without some oversight and coordination...
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Randy just commented while I
Randy just commented while I was writing below [1], and I understand the rationale of wanting coordinators for the existing content. I just don't know how that will really be any more sustainable - it's the size and state of each individual section is still overwhelming, maybe if a few people could dedicate themselves to each section then there might be a way, but as there have been few volunteers in the past, I don't want to make any assumptions... of course, if there are willing people then I guess there's no reason to stop them! ;)
I guess what I'm getting at (and I realize this is a huge change) is that I'm not sure the wiki would need coordinators - isn't that sort of the point of converting it into a wiki? Of course we'll still want to remove spam, etc. so would need some maintainers to deal with that (or maybe we add some wiki admins to the webmasters team?)
And as far as what happens to the Docs Team, I'd love to see something like this:
To think that we shouldn't make a change like this because it would dampen the need for Docs sprints or recruitment - well, I don't think that we should look at it from this perspective. People who are interested in Docs will still have many areas to contribute:
I think there is still a lot of work that we can funnel people towards - and maybe actually have adequate coverage relative to the size/efforts of the Docs Team. We shouldn't equate changing focus/tasks with shutting down the team.
Too much for me
So many help systems... I don't get the point. Why a wiki and curated docs section ? If the curated section receives high quality content like John Falk's book and blessing from high profile Drupal contributors (I mean the dedicated team of coordinators with edit rights), we will end up with 2 docs with different quality. I'd rather focus my energy in only one, with the ability to edit any page. Why not an issue automatically created with the status "needs review" when one creates/edits a page, so anyone can just review it through the issue queue ? One issue queue (the Wiki issue queue) to rule the world of Docs. Remember that the issue queue is where stuff happen. The Wiki can be proper docs, tutorials, api coverage, how-tos, faqs, anything... If it can be anything edited by anyone, for me it's a true win.
And apart from tools, we also need a plan. I mean a plan like one can find in the first pages of any book. The top level sections would correspond to chapters of these books for instance. A consistent plan could help people find their way into the mess we have now, we can't risk creating another mess. If each chapter had the same structure, with the same set of sub chapter for instance... Or each module documentation has the same structure, like 1. What's the module purpose 2. How to install it 3. How to use it (with screenshots) 4. API docs 5. Code explanation to help people understand the design and both evaluate the module/write patches. The point for me is : if anyone can edit anything, it could be a mess. If anyone can edit anything but is clearly "enforced" somehow to follow a proper structure, it could still be a mess, but with the opportunity of a complete, exhaustive, comprehensive Drupal documentation.
Side note/question : why should we fear giving edit rights to anybody ? Has there already been a very bad episode in the life of the Drupal Docs when a user completely screwed doc pages because he had the right to ? If not, I think we should really re-consider the question...
If the wiki and its issue
If the wiki and its issue queue were to rule the world of docs, it would be happening. But it is not. The handbook is an utter and complete mess. It lacks any organization and it is almost completely useless for helping to onboard new Drupal users. Note that this is not the fault of the amazingly hard-working docs team, its just that without a coherent vision for organization and planning, and organic documentation will slowly turn towards chaos and unmaintainability. I was really struck when doing research for my core initiative how Plone has very very structured task-driven documentation, and it is incredibly useful when getting started. However it can't cover everything by any means, and once users start getting their feet wet and need to dive deeper, we will have the wiki where more focused information is useful.
I have no idea how you would enforce the kind of editing plan you want onto a wiki that anyone can edit. It is a joke to think this will work, because right now any logged in user can edit pages and it doesn't. If anyone can edit then anyone can and will break from the plan, and then the entire docs team is spending all their time cleaning up after people. Again, if this could work it would have, and it hasn't.
Yeah I agree with heyrocker
Yeah I agree with heyrocker entirely on this, I'd add one extra point to back this up:
everyone editing docs pages is a relatively recent thing - past 2-3 years, however lots of people don't take advantage of the permission, partly because some of the documentation looks very official. Usually when I edit documentation pages it is to mark them as deprecated and move them to the 'archive' section (i.e. bin), but most people are more tactful than me and leave them as they are, and even I have limits so don't do this often.
What we've had for many, many years is the ability for anyone to add documentation pages, anywhere in the system - this is what makes it such a monster to maintain.
So when talking about a much smaller, curated docs section, it is about taking the load off the people who are trying to structure probably tens of thousands of pages (bear in mind many contributed modules have entire sections in the handbook and some pages date back to 4.7 or earlier), so they can focus on a much more focused set of docs (which already exists to an extent in some places but is competing for their attention with PHP snippets posted in 2004).
Plone docs ++
Thanks for pointing to those plone docs, they really are very well done. One thing that I think is very nice about them is it's obvious from the get-go who wrote the documentation. Not only do they give better credit to the authors, but as with modules, the names of well known contributors would lend a bit more credence to the documentation. It also helps with one of the aspects of Drupal docs that I've always found disorienting: the lack of a single "voice" in the docs. Maybe it's just me, but reading through a bunch of doc pages seems like a more cohesive experience, since I can see who wrote any page right from the page I'm viewing.
Alex Urevick-Ackelsberg
ZivTech: Illuminating Technology
I think it is actually EASIER
I think it is actually EASIER to get contributors for this kind of documentation than for wiki format, because they know that their work will not be torn down and screwed up tomorrow. I know I would be much more inclined to write a piece of documentation if I knew where it fit into the whole, and that it would survive in a meaningful form for a good long amount of time.
re: editorial voice
Alex brings up great points. Also, although this would probably add a level of abstraction to the documentation project, but maybe what is needed is an editorial team going through the content after it has been written to ensure consistency against some style guide.
I'd be happy to help in this endeavor (after the end of the year, too overcommitted in volunteer work right now).
Joe Bachana
First Employee at DPCI
1560 Broadway
NY, NY 10036
212.575.5609
www.dpci.com
Current problems
Edit: heyrocker was quicker than me to post his comment (above) – this comment basically repeats the same things. I'm leaving it here anyway, for sentimental reasons. Sorry for chopping down digital trees.
Having many separate documentation places is not a good thing, but I think everyone can agree that the current wiki is too messy to even start digging in. It's a good place to put a documentation page, or even a whole documentation book, but there is no way you can expect new Drupal users to go into the wiki and find what they need to get started.
I think Drupal would benefit from having clear, consistent and overviewable documentation – and evidence shows that the wiki isn't the right place for this. (Which is all well and good – the nature of a wiki is to have a lot of content but less structure.)
Adding clear guidelines about how to write documentation in the wiki is problematic. Many sections in the wiki doesn't fit the regular "what does this module do" pattern, since it also contains a lot of single-purpose PHP snippets, recipees for creating functionality of some sort, comparison of different modules, help on upgrading or installing, and what not. Even if we could find a single guidline that fits all the needs we have, there would still be the work of "enforcing" it – which to a large extent would mean either rewriting/complementing a lot of content, or unpublishing stuff that doesn't meet the standards. In the former case we are at the current situation (with HEAPS of issues and still a mess in the wiki), in the latter case we more or less have curated docs.
I think a curated docs section is beneficial. And I definately think that we need a documentation wiki as well. (Then I wouldn't mind if the "off D.o documentation", once introduced, fits into the wiki – but that's a different matter.)
The help system for Drupal 8 is another matter. If it is possible, it would be really cool to have it as a part of the curated docs, but it is too soon to say anything about that.
//Johan Falk
**
Check out NodeOne's Drupal Learning Library! 190+ screencasts and exercises, for Drupal introduction, advanced configuration, and coding. Creative Commons license!
Book
Holy mackerel! Seriously? I don't know if I can +1 Johan enough before hitting the size limit on this text area (currently measured in gigabytes, I believe).
+1 for video
I definately think we should add the possibility to embed video in both wiki and curated docs. (I know that at least I have a few videos that would be awesome to share at the Drupal main hub.)
Using embedded video, and not uploads, shouldn't be a problem at all. And if we embed rather than upload, this should be a pretty easy task. (Right?)
//Johan Falk
**
Check out NodeOne's Drupal Learning Library! 190+ screencasts and exercises, for Drupal introduction, advanced configuration, and coding. Creative Commons license!
Video
Also, just FTR I am totally a +1 on video embedding for both the wiki and the curated docs.
I understand that "structured
I understand that "structured docs" and "wiki" are not really compatible. Hence the Curated docs. So my idea about a plan and everything should definitely go into the Curated Docs. I wasn't really enforcing one set of guidelines : core stuff could have their own guidelines, contrib doc their own, how-tos their own, snippets their own, and all belong to a semi structured document. It's just an idea by the way.
I like the idea of DITA docs using Curated Docs content. What else should they use ? It would help us curate them even more.
About enforcing guidelines : it may be a stupid idea, but maybe we could write these guidelines in a simple and short way when one creates/edits a wiki page, like the input format guidelines ? I see it like the "issue summary initiative".
And another thing. I may hurt people here. I remember a tweet not far ago : "GROW UP AND DOCUMENT". It's silly for me that people who have the knowledge don't write the docs the stuff they wrote. Who better than a core subsystem maintainer know how this subsystem works ? Who better than a module maintainer know its code and its purpose ? Open source projects out there are dying because of the lack of documentation (don't talk about in-code comments please), not because of poor quality. Well, undocumented code is code of poor quality, we all know this in the business. We shouldn't wait for the generosity and goodwill of someone completely out of the development to write this doc for us, even if it's very good for them. I am one of them, I actually maintain no module, and already helped in a few core/contrib doc pages. But I don't think I can explain in detail the DBTNG or low level stuff that requires skills (or lot of time) to understand and explain in pages.
Itangalo : THANK YOU for giving the content of your book to d.o. I already said this at London, but I'd rather see the content of "The definitive guide to Drupal 7" goes into d.o as well.
-- Sorry about the rant --
And, +1 about video, Itangalo could at last put its screencasts on d.o :)
Good points
I too remember the "GROW UP AND DOCUMENT" tweet, and I agree that we should put more effort into documenting. (I know not all coders have excellent skills for writing documentation, but it wouldn't be crazy to treat documenters as additional module maintainers.) But I will leave this for another discussion.
I definately like the idea of having short guidelines visible when creating/editing wiki pages. +1 for that!
I was working on my prototype
I was working on my prototype for parsing tutorials on Drupal Planet into a queryable dataset when I found out that the list of projects on Drupal.org has been access controlled!! I need this to create the autocomplete field for people to tag their posts.
Does anyone know the fastest way to get this changed back to the way it was?
Issue-queue managed sections should be discrete
I'd like to see the documentation broken into manageable issue queues, that one or two people could take ownership of. For example, the module development section of the Wiki could be owned by one issue queue, and the theme development section owned by another.
I'd love to see individual module documentation owned by that module's issue queue.
IMO it's not just organization we're aiming for here, but ownership. Ownership that might actually be expected to be sustainable.
Huge +1 to the whole plan.
Wiki vs. curated + team implications
I completely agree with what heyrocker [1], catch [1], and itangalo [1] [2] are saying.
This method has already proven itself completely unsustainable - rather than dream this will change, why not adapt the method to something that will actually work?
The Plone docs heyrocker mentions are an ideal of what we could end up with - for eg. the Theme guide http://plone.org/documentation/manual/theme-reference is so well structured and easy to navigate. And the amount of content is clearly more manageable. (I also love their sidebar eg. http://plone.org/documentation/manual/theme-reference/buildingblocks/ove... but that is a little OT...)
To achieve something like this writing from scratch would have been such a big job I'm not sure it would have been realistic, but thanks to Johan's donation of his book text, it really saves us probably a year of writing work, where we can start immediately with fantastic D7 docs, and add in whatever is needed, then maintain that.
Benefits of this include that:
a) avid writers/editors can actually maintain something that is not a disaster, and hence be more efficient/effective
b) users can find clear/concise information much more easily
c) we could move towards having shorter more concise exportable versions
d) yes, the lead/core/most involved docs contributors can have more control over the docs - maybe this isn't as "open" as we're used to, but it will make a huge difference in the quality of this essential/core content, and that is a big win for current users, as well as working towards the goal Dries talked about in London of better/easier adoption of Drupal.
Lin - will follow up on the page access issue...
Jennifer - replying above....
One thing we need to plan for
One thing we need to plan for going forward is that Johan's book has a lot of contrib involved in it, and as we all know contrib changes much faster than core does and thus these docs will need to continue to be maintained. This is even more important given their 'curated' status and assumedly their increased level of attention and prominence. While I'm sure Johan will love doing this work, it is good that a plan is put together to manage this going forward as well. Perhaps reaching out to the maintainers of the modules involved when big changes are coming, and a small team of solid tech writers to make and review revisions. Again, the hope is that since these people can make a more meaningful impact and build something realy good, we will have an easier time getting committments from people.
Definitely - and we don't
Definitely - and we don't want to have to rely on any single person on keeping these up to snuff/date. I'd really like some of the docs team to disperse and start partnering up with some of the most popular contrib project maintainers to make their docs just as awesome. We'll have to figure out whether it makes sense to put contrib in the "core/curated" docs, or whether to somehow have "official" project docs for contrib as well, that is separate from the wiki...
Totally agree that the more clear + concise the docs are, the more they will actually be maintained into the future.
Kudos on the proposed plan
In general I really like the proposal with the doc divided into three categories (I would list them in this order):
(1) Curated docs (I think users might understand "core docs" better -- I've never heard the term "curated" used in connection with docs, but I guess people would catch on eventually) that is rather tightly controlled by a relatively small group of people. If Johan has something to contribute as a starter set, that would be great! I'd suggest taking the time to create a core set of taxonomy terms that both maps to Johan's doc and also covers topics the team think would be needed to make Johan's doc relatively complete. I think most users would want to know that there is a basic set of topics of this type, what they cover and what they don't cover. (Certainly an overview of all docs and doc types should be part of this collection.)
(2) Community docs done in wiki format and essentially open to all contributors. I think if the docs team continues to get involved in this to any depth it will rapidly get out of control (again!). Add to the core set of taxonomy terms created for (1). Then identify the categories that will be REQUIRED for ALL docs (that is, docs in all three categories) included or linked on d.o. I'm thinking of things like Drupal version (or "generic"), type ("tutorial"), user skill level ("beginner," "advanced"), role ("builder," "themer"), module, etc.
(3) Linked (offsite) docs that could appear anywhere in any format. Make it a requirement that the doc owner post (on d.o) an overview of the doc contents that includes at a minimum the required categories. Post all links to offsite docs under the category names in some central location on d.o. For example, put all links to tutorials for beginning themers together.
I really think the docs team can exert a reasonable level of control over the entire doc set (and I think that's a good thing for the experts to be doing) with this taxonomy-based approach. It still allows everyone to participate, but encourages more responsibility toward the user's being able to find what s/he's looking for.
I'm glad you're still thinking of a DITA-based solution for future releases -- I think it would work well for the core ("structured") doc.
By the way, my business partner, Dick Johnson, has created a sandbox site for his bulkpub module that allows a set of documentation topics to be published directly to a Drupal 7 site. He'll be refining it over time -- if it could be used for your proposed D8 work he'd be glad to consider suggestions and requirements.
I have a couple of questions:
- What do you mean by "project"?
- Do you plan to tag future doc topics by release numbers? I've had a lot of trouble finding D7 topics and even knowing whether a particular topic applies to D6 of D7. I recommend that all future topics have a release number label.
I could definitely see the
I could definitely see the conditional text and possibly some better tree/hierarchical menu work going into the curated docs (and hopefully trickling down to the wiki at some point?), as those are already being built for the Help System.
Though, as I've said before, I wouldn't want to hold up getting this "core/curated docs" content online for this infra to be in place. Since we are starting with some completed text, it doesn't add more work to adapt this later on.
Skill level, version, type of content are all possibilities if we want to categorize, etc. but we don't need to get into those details yet, first we need some consensus on this plan, then we'll get to the nitty gritty.
Re: offsite docs - the idea is that the content is not maintained at all on d.o. That's the whole point of building infra with microdata and sparql endpoints - so let's leave out any plans for "maintaining" offsite content at all - hopefully there will be no need to maintain that content, only the infra to make it searchable via d.o.
ps. Project = Drupal project (any theme, module, install profile, etc. is its own project - as in project module, which runs issue queues - on Drupal.org + their own git repo). You can tell if something is a project, as it'll have "project" in its path on d.o.
Ideas from the Docs Office Hours
We had a discussion today about this in IRC during docs office hours.
The main topic was about "how to turn the current Documentation on drupal.org into a real Wiki". Some thoughts:
a) Call it a wiki, and have sidebars, headers, etc. to make that clear.
b) Make sure people realize they can/should edit it.
c) Discussion ability? (maybe not needed - we have comments now and revision logs as it is). Maybe move the comments to a new tab?
d) Full edit perms with images and (hopefully) videos for all.
e) Moderators for spam removal and dispute resolution.
f) Some way for people who want to improve the wiki to find pages that people have identified as problematic
g) Some way for people to mark pages as problematic without clicking "edit" which is scary since they don't know what the right answer is [flag + comment?]. Or a way to make it clear that you use "edit" to change the status.
i) Make it clear we are not removing the old docs, just calling them what they are - community-maintained docs.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
This is now an issue
This is now a formal issue:
http://drupal.org/node/1278256
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Regarding c) Discussion ability
Consider making the comments a separate tab, as you suggest, but with some differences. Wikis (not just Wikipedia, but most any wiki out there) allow for topic comments on the discussion page, each with a separate edit link. They function as a combination of issues and comments. Also, it's not these infinite threads, but each topic with its own thread. Much easier to follow. And comments can go so far down the page. A separate tab allows the contributor to read the issue, then easily switch back to the doc. Topics could even be collapsible so you only see the issue you're concerned with.
Comment on issue please!
If you have comments about the Wiki stuff, please comment on the issue and not here at this point, thanks!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
some thoughts
After the IRC discussion, I've had time to think about this, so here are a few thoughts.
a) Call it a wiki
We can call it whatever we want, but without a paradigm shift in our thinking, nothing will change. A couple (few) years ago we renamed Handbook to Documentation, but we still have the same problems as before.
Months ago someone (somehow I think it was you, Jennifer) asked on Twitter to name some of the best Wikis out there. I named wiki.archlinux.org as a great one. So I've been thinking what makes a wiki great, and I've come up with, besides well written content, taxonomy.
People have to be able to find what they're looking for easily. Right now, with the current structure, it takes quite a few clicks and searches to be able to find anything. Please, let's use taxonomy to our advantage!
c) Discussion ability?
A tab page with the threaded comments on it would be great!
d) Full edit perms with images and (hopefully) videos for all.
Images are definitely needed!
e) Moderators for spam removal and dispute resolution.
All content on d.o is moderated - low-level human moderation. Whoever moderates needs the list of new/edited pages and updated comments.
i) Make it clear we are not removing the old docs, just calling them what they are - community-maintained docs.
Sometimes I think that if we got rid of 1/2 the doc pages, no one would notice. And I'll admit, starting fresh has a certain appeal...
(And for the record, I don't believe we should be looking to Wikipedia for a lot of inspiration here - that's a general knowledge wiki, and we should be looking at technological-oriented sites.)
Must do something
100% support for jhodgdon and Arienek's ideas and solutions. No problems with a Wiki, I know it has lots of drawbacks, but the problems are small potato compared to what we are dealing with now.
--Sig--
Owner of Proper Programming, LLC a software and website development firm.
criteria
arianek and I were chatting on IRC and I came up with a question that should be asked to be able to distinguish between what's wiki content and 'currated' content.
"When do we tell people to go to the Wiki, and when do we tell them to go to the 'curated' docs?"
Easy
Just tell them check both. Many times the wiki will be be informational, and the coursers docs more technical (from what I've gathered). You can never go wrong with multiple perspectives.
~~Cheers!
cleverington
The man of many hats.
Just make it clear to users what the various doctypes are
I don't think we would need to tell users which kind of docs to use -- just tell them what are the key characteristics of each kind, and then let them decide for themselves. A few samples displayed in a sidebar would probably help them make up their minds. Also, key pages, put a prominent message like "Didn't find the information you're looking for? Try the curated docs!"
DITA
DITA has been mentioned many times in these discussions, will this technology be available soon to the Documentation team or is it still in the planning phases?
Edit - reposting on the issue.
http://www.webbfx.net/
"Curated" core docs
I've been pondering what exactly would be different from the "wiki" docs in the "curated" core docs... I think not too much other than:
A) No comments, and restricted editing access - people must file issues for problems with content.
B) Not sure if we reference related forum posts here? See sidebar in image (wireframe in progress for wiki pages) on http://drupal.org/node/1278256#comment-4991304
C) Focus of efforts of core docs team members
So really, there's not a big difference technically in my mind.
I'm not sure whether it's time to file an issue for this, or if we still need to discuss further here... it seems like it's got people more on the fence than the docs --> wiki issue...
careful with restrictions - maybe revisioning module?
With regards to A, specifically "restricted editing access", I like the general idea, but I think it's a really bad idea to force people to make suggested edits in an issue. In my experience, issues are not very conducive to collective editing, and for new folks they can be very intimidating. I highly suggest we use something like the revisioning module, so that people can make "suggested" changes, but then those changes would have to be pulled into the original by the owner of the page or a person with sufficient privileges ("core doc admin?"). This is something that Quora gets right, and I think curation of editing the answers (and credit for them) is a big reason why the service has gotten so much traction. Edit: I don't see that feature on Quora any more. Now you just edit the question directly, which I don't like as much.
Either way, I think one goal here should be to ensure that there is the lowest possible bar of entry for new people who want to help in small ways. With volunteers, every journey starts with one step, so let's use the tools available to us to make that first step as easy to take as possible. So, if I'm a good technical writer that is new to the community (or a dev/admin with a thing for good documentation), and I see something wrong, I need to see something obvious that indicates that I can contribute to and improve the answer (without a 20 step process).
Alex Urevick-Ackelsberg
ZivTech: Illuminating Technology
Interesting!
I didn't know about that Revisioning module -- looks very interesting! I was under the impression that the Workbench module did some of this type of workflow (which I think we are going to need for the new Help system), but if not, hopefully they would integrate. Anyway, thanks for the tip!
I do like the idea of the community being able to propose revisions, and the overseers of the core help and/or the curated docs having control over which revisions get accepted. It's kind of like the patch system we have for code development, but accessible to docs people.
Ariane and others -- thoughts?
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Yes
Workbench is able to do "in review, not yet published" revisioning, yes. It can also restrict edit access by section, which can be defined in (almost) any arbitrary fashion.
workbench is awesome
We've just done a documentation site in which we are using workbench, the revision system is awesome. We've also even seen that there is a patch for diffing in the issue queue.
--
Check out more of my writing on our blog and my Twitter account.
I think this is an
I think this is an interesting idea, and yet... regressing from the initial idea of why to have the curated docs area (which is also ok). Moderation = more work for the curators, which makes it more like the existing docs. Then the only real difference is that some pages are more highly restricted and put on a pedestal (which isn't really the point).
It's a good piece of functionality, and would indeed help onboard people really interested in docs, so I see the value in it. But it definitely diverges from what was being discussed in London in regards to the "curated" docs. The Plone docs also do not have direct editing.
"Report errors, omissions, etc., to the documentation by emailing plone-docs@lists.sourceforge.net" - not much different than using an issue queue, aside from being even less transparent.
Actually I kind of think it
Actually I kind of think it is the point. They are put on a pedestal because in theory they have been more seriously vetted and written with more attention and care. They will also be (assumedly) more focused on tasks than modules, which makes them better for onboarding new users. That said, there is definitely value for a simpler way than the issue queue for users to report errors and/or additions. I mean, just because it is curated doesn't mean people won't make mistakes. Also, because this documentation will include contrib, it will go out of date more quickly, so easier reporting of that will be important.
Distributed Responsibility
.
The way I was thinking it would work is that the original creator of the document would be notified when someone suggested an edit, and it would only get bumped to an issue that would require curator attention if the document creator didn't respond to the change. I know that makes the section slightly less "curated", at least in the sense that the docs team isn't directly responsible for every curated page, but I think that's a feature, not a bug. As I mentioned before, crediting and clearly calling out the individual authors of the docs is something I really like about the Plone documentation, and I feel that giving people "ownership" over the pages they create is a great way to incentivise participation.
I guess for this to work there also needs to be a way for people to suggest topics and/or add new documentation to the curated area, but I don't think that should be a technical issue as much as a bit of work for the documentation team. On the whole though I think this way would lead to significantly less duplicated work and errors, since there won't be as much copy and pasting between issue queues and documentation pages.
Alex Urevick-Ackelsberg
ZivTech: Illuminating Technology
well spoken, Alex
There are new and current users.
That is tough split for the Drupal Docs community for many reasons.
Docs are sposta lower the bar of entry to all Drupal-centric roles
(dev, themer, sysadmin, content manager, users, project managers, etcetc).
That seems where we could begin, with min effort and discussion.
I propose max use of imagery about real code.
eg, see graphic @ http://drupal.org/project/token
Jeremy Donson
Database and Systems Engineer
New York City
Just one point here - I think
Just one point here - I think we need to be very careful about always making docs the "lower bar" task. Writing good docs is a skill that not ever new Drupal user will have - sure, we want them to learn, but it's a lot of mentoring for a small team or core docs contributors.
Getting other areas to have a lower barrier to entry isn't really Docs Team's prerogative, but we shouldn't focus too much on maintaining the lowest barrier to entry - that's what the Wiki would be for, it's still going to be there full of content that can use gardening, and everyone will have access to it.
If someone has been actively working on Wiki pages and wants to work on the core docs then it's easy to evaluate their work and give them that role.
"Lowering the Bar" isn't about docs
In my experience healthy volunteer communities are constantly refreshing, or growing, their base of supporters. You never know what potential volunteer "superstar" might be lurking quietly someplace just waiting for a bit of engagement. IMO this means that the goal within any distinct working group within the community--whether core/contrib developers, themers/front-end devs, designers, PMs, marketers, UX, or documentation--needs to figure out ways to continually lower the bar for serious contribution. That's not to say it should be lowered so far as to encourage low-quality work (that's not what I mean, at least, by lowering the bar), but the bar for contributing at high-quality work should be as low as possible.
Alex Urevick-Ackelsberg
ZivTech: Illuminating Technology
You are HERE. (I think...?)
(Foreword: Just trying to make sure I understand where we are, since a lot has happened in the past week.)
Where it appears we are now:
('aka: Curated Docs') - This will be maintained and updated by the Documentation
Team only. ~75% Agile.
Composed only of Team Coordinators.
Content focus on 'Branding' content. (The Beginner's Guides, Welcome to Drupal, etc.)
Comments closed.
Two Coordinators, plus admins.
One Coordinator, plus admins.
One Coordinator,, plus admins.
One Coordinator, plus admins.
Agile-Inspired Groups for specific sections of
documentation. Leads get Admin. Content to be reviewed
by Coordinators, prior to publishing.
Version, User Level, Type, Role, Themes, Modules, API, Maintainer, Contributor
('aka: Wiki') - This is able to be maintained by everyone and will be 100% Agile.
documentation assistance, maintain documentation of assigned 'section'.
(Same sections as Core Handbook, with HOPEFULLY separate
coordinators)
removing/editing content/comments flagged as 'xxxx issue').
outside of issue Queues:
Guide - One time design, and possibly a bi-annual review)
Version, User Level, Type, Role, Themes, Modules, API, Maintainer, Contributor
('aka: Off-site Sources') - This is able to be maintained by everyone and will be 100% Agile.
where 'corporate' contributed content and/or blogger contributed
tutorials / content will be placed.
Only tagging, spam removal, and general issue queue items.
involve updating this queue without correcting the issue.
moment because the Core Handbook and Wiki come first.
Version, User Level, Type, Role, Themes, Modules, API, Maintainer, Contributor
"One of the most powerful tools of the Agile Developmental
Management is when it implements Waterfall Developmental thinking.
No-one notices."
Current Roster -
(Can we look into getting this up to date in a different discussion)
etc.)
Responsibility: Branding and Content Structure Design)
No more than one for each Core Handbook section.
'brand' and the 'culture'.
wrong.
Tagging Systems:
(Needed Fields)
Advanced, Expert, Drup-Ninja
Cookbook, Administration, Installation, Structure, Site Building, API,
Related API
Designer, Developer, Documentation Contributors
enabled, 960 Grid, 1/2/3/4 column, etc
Developer, jQuery Enabled, etc,
P.S. I'd volunteer for the uncreated 'n00b Docs Team' or the Structure
Docs Team.
~~Cheers!
cleverington
The man of many hats.
Just to note - I don't have
Just to note - I don't have time to amend this right now (at work) but there are several inaccuracies in this list here, so if others are reading this, bear that in mind! Will try and post back later...
Thanks arianek. I was just
Thanks arianek.
I was just trying to organize where we are. I'm a 'lists' type of guy.
:-)
~~Cheers!
cleverington
The man of many hats.
Attempt at updating
Here's my attempt at updating that condensed review... note I haven't incorporated Johan's comments regarding promoted wiki pages as curated pages, would like to hear more input on that.
1. Community Wiki: Community managed, completely open editing
enable video embed for all
standard page "tags" (version, audience)
2. "Curated" or Core Docs: Maintained by core docs maintainers
photo and video embed
standard page "tags" (version, audience)
3. Offsite docs: Uses a module to reference D.o projects; submitted items go into a feed into a Sparql Endpoint which is then surfaced on D.o as a searchable view.
Roles
Categorization (for wiki + curated)
open to ...
I would like to join my hands in:
Sree
A great change
I've been reading through this thread and am really excited about the possibility of having curated docs and an organized way of accessing and navigating off-Drupal documentation. Letting the current docs turn into a community-edited wiki also seems like a good way to free up the docs team's time and encourage the community to create innovative, useful documentation.
Since this discussion is a bit hard to follow, I put together a chart to try and organize the major changes and next steps. The original is in OmniGraffle and can be downloaded here for editing.
For the "Curated Docu" - design aspects
Firstly, I think one the most important points for a curated documentation is to clearly separate between the Drupal versions. In my opinion there should be 2 "books" for D6 and D7.
Also, I would like to have the documentation page separated from d.o in order to have the full screen available for just for the documentation page with its navigational elements. Also, I would argue that the documentation site would be worth for some serious design and IA love, just as the D7 admin theme and also drupal.org just recently got. Redesigning the docu site is definitively a smaller task, however it should be taken serious. All the valuable content needs to be presented the right way.
Maybe an "HTML based e-book with a reduced interface and rich navigational tools" is what I am actually thinking of.
Here are some quick links, which might help to think further:
-- http://www.readability.com/
-- "dmig" online magazine has some different ideas - not sure if they make it easier or more difficult to read. Their layout are a good base for playing with the topic anyhow: http://www.designmadeingermany.de/magazin/5/
Would be glad to discuss this further! Hope to get some replies :)
Specifics?
All of us might not have time to read those links... Can you make some specific suggestions about layout and navigation that you think would work well for Drupal documentation?
Regarding two books...
a) I don't think we are going to start out the curated docs with D6 at all at this point.
b) Maintaining very similar content in two places is painful and inefficient, so when it is time to add d8 to the curated docs, I doubt we will make it completely separate. Instead, we would probably tend to use Conditional Text, so that pages or sections of pages can be shown/hidden based on version.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
The links I posted, both show
The links I posted, both show web layouts that focus on readability. The main objectives are less distraction and a pleasant reading even on the screen. Those designs try to make longer reading sessions on the web more enjoyable.
On one hand, the documentation probably is often used as a reference book, where you are quickly searching for a specific information. On the other hand a curated documentation could, and in my opinion: should be a book, which is intended to read from the beginning to the end. That way it could be the resource for people to start with Drupal. For the community the role of such a book is that people can build a common ground of knowledge about Drupal.
So, I think a "book" is in general a good idea. I agree that such a book should be downloadable and therefor readable offline. But, I also think - as we are all HTML and web experts - a special Web Version could also get special attention. So far so good.
Now, on the web people usually do not read long stuff most of the time. Most web layouts and web pages are full of distractions. I would be glad if the Drupal "Handbook" (or what ever it is called) is a positive exception in this regard.
In specific I think that probably stuff like this helps:
-- having a documentation only website (no other menus -- eg. the user guide of expression engine has more or less a docu-only site: http://expressionengine.com/user_guide)
-- having a reduced, but usable and enjoyable design and layout. In particular good typography, high contrast, and the like.
-- having practical navigational aids (breadcrumbs, maybe auto complete text search like on api.drupal.org, .. )
An example of a very usable navigational aid in the context of blog entries is this Outline-Thingy seen at Lin Clarks Blog: http://lin-clark.com/blog/microdata-drupal-challenges-field-formatters
I would think that less than a handful of well designed and well thought navigational aids would be more than enough for a Drupal Handbook.
On the whole I think there are more topics, not really connected to this one, which are important.
-- clear separation between versions. If this is possible with conditional text, as you say - fine. Is there any discussion somewhere in particular about this topic?
-- content structure, length of text, usage of images, usage of videos.
-- Should there be any interactive elements, like comments, or not
Finally, what is the best or central place where discussions about a new handbook happen?
Lots to digest...
Lots to digest in your post...
For now, i can just address the last question about discussions:
- Right now, we are discussing initial changes to management of the current (community) documentation at http://drupal.org/node/1278256 -- there is a concrete proposal there now that hopefully will get accepted (perhaps with refinements) shortly.
- For the moment, discussions of the more curated user handbook are happening right here. When we get the previous item's plan settled, we'll probably open issues for (a) follow-ups on the community docs (infrastructure improvements) (b) creating a more curated user handbook.
- In general, groups.drupal.org/documentation-team is the place to discuss ideas about Drupal documentation.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Offer to prototype a DITA-based info collection for D7 docs
Hi, All --
My business partner, Dick Johnson, and I have been looking into ways we could contribute to the D7 documentation effort. (We've considered whether we could contribute at the D6 level and have concluded that we just don't know enough about it -- we have really only worked on D7 sites.)
We'd like to offer our help in prototyping a rich-content solution that we hope might be useful in the D7 (and beyond) project. If nothing else, we hope it could be a learning exercise for us all -- if that's all that ever comes of it, that would be OK by us, too, and we could maybe contribute in some other way as the D7 effort gets underway. We already have a specific idea in mind and would welcome additional input from the group.
By way of history: We have been contributing to the DITA documentation effort through that open source community since 2006. For about a year we have been experimenting with DITA/Drupal and DITA/WordPress information mashups, as we call them (that is, structured/unstructured solutions where the various info collections are "linked" using metadata). We've just published our 8th edition of our DITAinformationcenter on www.ditainfo.info (a D7 site).
Publishing on our ditainfo.info site was accomplished with a new, contributed D7 module that Dick wrote: http://drupal.org/sandbox/rjohnson42/1278058. It publishes the DITA output as a Drupal book. This latest edition makes better use of the native Drupal 7 features for navigation, metadata, search, etc., and we have removed some of the DITA capabilities that got in the way of a streamlined solution.
The same DITA structured source can also be published to ePub, PDF, HTML Help, Eclipse, and XHTML. We have posted these versions on our DITAinfo.info site as downloads. We have noted that some members of this group have asked for ePub and PDF, in addition to the web content -- with DITA and Drupal you can easily have it all!
We have also modeled the addition of unstructured content on the same ditainfo.info site that was created with the native Drupal editor (you could also use ScribeFire or MS Word). The structured/unstructured collections are linked using a common set of tags. So from a content creator point of view, you can also have it all: a professional editing and publishing environment for the pros (DITA) and an uncomplicated, wiki-based setup for the "rest of us."
We believe the key benefit for users is they can easily search and locate everything on the site with keyword search, query by tag, etc. We have only scratched the surface of the Drupal capabilities in this area!
Based on our understanding of the recent strategic discussion within this group, we believe there is some promise in using this approach for the "curated" (structured) and "crowsourced" (wiki) documentation in the future.
We'd like to create a Drupal information prototype similar in concept to what we have already done with the DITA information collection, based on this group's reaction to what we have done already and additional requirements from the Drupal doc team.
We could target an initial demo/discussion by early November (based on an estimate of 30-50 DITA topics and a setup somewhat similar to what we have done already). We could post our prototype on a subdomain of one our existing D7 domains.
If this effort appeals to the group, we'd like to get a green light and the project elements (existing doc to be converted to DITA?) and general requirements by the end of next week (Sep 30).
Please let us know -- we'd love to get involved.
Anna van Raaphorst and Dick Johnson
In progress work?
We're well on our way to a DITA-based (loosely, anyway) solution for inline and online docs for Drupal 7/8. Have you been following:
http://drupal.org/node/1095012
There are specific calls for help for module builders and site builders for docs infrastructure at
http://groups.drupal.org/node/174499
More to be added to that page shortly...
Thanks!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
New issue for Curated discussion
Discussion of what the curated docs should be should now happen on this issue:
http://drupal.org/node/1291058
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Issue tag
We have a new issue tag for issues related to documentation infrastructure:
docs infrastructure
I think all of the issues related to everything being discussed here (and some more) are now tagged with that tag (Ariane edited the name of the previous cryptic "docsyvr2010" tag to this name, and then I added it to a bunch more issues).
The reason we need this tag is that while these issues might start out being discussed in the Documentation issue queue, they tend to get moved to other issue queues as they get worked on (such as Drupal.org infrastructure improvements). So now we have a unified tag that will track them no matter where they end up. Hooray!
If you are tracking any issues related to docs infrastructure, please check and make sure they have this tag, so we can all find them. Thanks!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
Note: I just updated
Note: I just updated http://groups.drupal.org/node/175174#comment-585239 to add JuliaKM to the list of potential curated docs maintainers after talking with her on some other issues.
"Docs-team curated" and "Other-curated"
I suspect we're making too large a differentiation between curated and uncurated. I'm way in favor of this proposal, and think it will be a huge win.
But why can't subsections of the "uncurated" docs actually be curated by owners who are not the docs team?
Could a book section have an owner, who was notified of changes
Could a book section have an issue queue, where people who cared could see about issues in that section?
Discuss on issue please?
We're now discussing the curated docs on issue
http://drupal.org/node/1291058
And the community docs planning is issue
http://drupal.org/node/1278256
I'd prefer to keep the discussions there so people don't have to look at two places. Thanks!
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon
One more issue
The followup "further improve community docs" issue is here:
http://drupal.org/node/1287784
I am not certain whether your idea pertains to the Community or Curated docs, so I haven't added it to any of the issues, but if it's for the Community docs, it should definitely go in the Followup issue not the main issue.
Drupal programmer - http://poplarware.com
Drupal author - http://shop.oreilly.com/product/0636920034612.do
Drupal contributor - https://www.drupal.org/u/jhodgdon