Follow-ups to improve the community docs

Thanks for starting this thread. I'll start brainstorming on some mockups.

sub

I got this idea while looking at the Plone documentation, specifically their Docs landing page and Knowledge Base. I'm suggesting adding collapsing blocks to the main docs page which reveal the navigation block per book. Current section descriptions would be moved to an info bubble which would appear on mouseover.  Trying to create a design that is more open without losing any current information and adding accessibility to nav contents.

The main considerations for the design were the following:

• Make the "Help us Maintain Documentation" call to action more prominent to encourage Docs participation.
• Move the "Community" block to the top beside the Help call to action, because encouraging participation on Drupal.org as a whole is a good thing. Having the current Community block at the bottom makes it easy to miss.
• Provide direct access to the Book navigation blocks per book from the Docs main page via a collapsing block.
• Display book description info via a jquery info bubble (coda style?). This would free up the page for  redesign because the current content (book descriptions) seem to have driven layout.

There are a lot of different initiatives going on so if this can be rolled into another project let me know. @arianek has been working on a great redesign idea here. That idea seems close to finished so I don't know how this landing page would fit  with that. The main idea of the collapsing navigation blocks goes under the assumption that we are keeping book as the content type for a while even if we change how that content is maintained. Not sure if the current Community Documentation (wiki) redesign would apply to the front page as well but I thought I would post anyway just in case.

You are better at this than I am but here goes. :)

Summary of follow-up issues from #1278256: Make it more clear that the current Documentation on drupal.org is community maintained

#8 Improve search experience within Documentation
#8 Introduce rewards/badges as motivational factors for Docs
#18 Make wiki Taxonomy based
#70 Have a way to flag keywords (like synonyms) for inclusion in an index.

The line between what was definitely being considered for the Community Documentation (wiki) and what was a follow-up for later projects was blurry for me at times. If I've overlooked anyone's ideas in the previous thread please let me know and I'll add them.

Edit:
Removed #14 because Discussion Tab was adopted into the base proposal.
Removed #16 because Curated Docs has it's own issue here Make a curated docs section

In addition to a TOC, it would be nice to have a way to flag keywords (and their synonyms) for inclusion in an index. For example:

Input text

With permission, users can post messages on other users' <cite>profiles</cite>, <cite>groups</cite>, and nearly anywhere else.

Rendered output

With permission, users can post message on other users' <a id="profile_1" href="/node/999999#profile_99">profile</a>, <a id="og_1" href="/node/999999#og_99">groups</a>, and nearly anywhere else.

Index entry

<dt><a id="group">Group</a></dt>
<dd>See <a href="/node/999999#og">Organic group</a></dd>
...
<dt><a id="og">Organic group</a></dt>
...
<dd><a id="og_99" href="/node/123456#og_1">Facebook-style statuses</a></dd>
...
<dt><a id="profile">Profile</a></dt>
...
<dd><a id="profile_99" href="/node/123456#profiles_1">Facebook-style statuses</a></dd>

In this example, the <cite> tag is changed by the text input filter into an index link. It would probably be more straightforward to use <a rel="index">, but I like the idea of making the <cite> tag actually do something.

Also, group is a synonym for og, and the plural of any keyword is automatically a synonym for its default singular form. Of course, there would have to be a mechanism for registering indexed keywords and their synonyms.

Summary updated. @jhodgdon did I link to the correct issue for Curated Docs?

I've got a request - can we please work on getting emfield/media so that users can embed video??? Issues like this should not need to be bottlenecked by a site maintainer. http://drupal.org/node/1250580

I know Johan (itangalo) would also love to see this so his awesome screencasts could actually be shown on d.o

subscribe ...

I'd like to request we add some basic wiki syntax to the input format used for documentation: #1074796: enable basic wiki syntax for writing docs pages.

Sorry, I replied over there.

All I can say is that I personally find it a barrier -- I don't know about anybody else. I know HTML perfectly well, but typing * for lists is just *quicker*. So is doing that for emphasis ;)

Options:

1. BUEditor

   A text editor aiming to facilitate code writing. Native support for html tags, bbcode tags, and other markup systems.

   See #424400: Use BUEditor on drupal.org

   Pros:

   • Adds buttons for common HTML tags for those who prefer a point-and-click interface.
   • Adds keystroke shortcuts for common editing functions.
   • Optionally supports BBcode markup.
   • Optionally supports IMCE.
   • Very customizable; can be made to support other markup styles such as Markdown or MediaWiki.

   Cons:

   • Requires javascript (but degrades gracefully).
   • Not WYSIWYG.
   • Preview button behavior has been described as "slightly weird".

2. Markdown Filter

   The Markdown syntax is designed to co-exist with HTML, so you can set up input formats with both HTML and Markdown support. It is also meant to be as human-readable as possible when left as "source".

   See #1224506: Allow markdown on drupal.org comments (with a non-default markdown-tuned input format)

   Pros:

   • Those familiar with the syntax can type the Markdown codes for headers, footers, links, lists, and emphasis much more quickly than typing the equivalent HTML.
   • No javascript required; all processing is done server-side.
   • The unformatted source is designed to be easy to read and understand.
   • Already in use on groups.drupal.org.
   • Does not conflict with inline HTML.

   Cons:

   • Not WYSIWYG.
   • No point-and-click interface.
   • Doesn't help people who are unfamiliar with Markdown syntax.

3. MarkItUp

   A content editor plugin based on jQuery. Provides the same functionality as BUEditor, but with more Drupal-ish theming support and better keyboard shortcuts.

   See #424400-16: Use BUEditor on drupal.org
   And #424400-39: Use BUEditor on drupal.org

   Pros/Cons: Essentially the same as BUEditor.

4. WYSIWYG

   Provides support for the following client-side javascript content editors:

   • CKEditor
   • FCKeditor
   • JWYSIWYG
   • markItUp
   • NicEdit
   • openWYSIWYG
   • TinyMCE
   • Whizzywig
   • WYMeditor
   • YUI editor

   See #997504: WYSIWYG for D.O

   Pros:

   • Lots of choices makes it easier to please everyone.
   • WYSIWYG editors are more familiar to non-technical users.

   Cons:

   • Lots of choices makes it easier to confuse everyone.
   • WYSIWYG editors may automatically add/remove whitespace or change source wrapping, making revision diffs less useful.

I don't personally love using markdown style, but I know a lot of people do. My main concern would be what would happen in the future if we want to make content be part of the Help System or somehow automate, sync, do whatever to it... would there be any future consequence to having a mix of markup types?

Actually, arianek's point makes me wonder about the D8 documentation plan -- doesn't that involve doc pages from d.org being slurped into people's Drupal installs? In which case, it would have to be in an input format that's installed in core :/

Personally, I'm in favor of installing WYSIWYG for the benefit of those people who type with one hand and mouse with the other. :-) As for me, I'll keep on typing HTML with both hands. If I want a better editor than the one on-screen I can always use Its All Text with Xemacs.

@ jhodgdon:

But it would make it significantly harder to promote Community docs to Help System, or import their content, if we were using strange input formats.

Why is it significantly harder to reference the rendered content rather than the database source?

If the docs are being fetched from within d.o then it's a simple matter of running check_markup(). If they're being fetched from outside, then grabbing the rendered page would be significantly easier than performing a remote database query, I would think.

WYSIWYG ... Not sure how the infra team feels about that.

They're generally opposed. See comments by silverwing, MGParisi, chx, Michelle, and kiamlaluno.

sun says he would consider adding wysiwyg only after 6.x-3.x is stable.

http://drupal.org/node/1278256#comment-5075908 rfay added a request for notifications/subscriptions to discussion threads or pages' discussion threads.

Adding bookmarks to the documentation #1304216: A user should be able to "follow" individual pages of content and receive email notifications for new comments