documentation [#2423189]

I'm kind of surprised that this made into 8 core when so few sites use it and there is zero documentation and no tutorials (video or otherwise) to be found online and not even any basic instructions on the page. I shouldn't be too surprised, lack of documentation is one of my biggest complaints about Drupal (and most open source).

That said - how do I get this running? I'm a savvy drupal guy so a few simple line items would probably do it. What I've done:

1. installed and enabled the module
2. downloaded the 2 required js libs required and placed them in my libraries folder
3. Granted permissions
4. looked for some configuration page somewhere in admin, found none.
5. browsed to many pages of different content types - no change
6. checked for a disabled block. Nope.

So what do i need to do to get this working? Do the js files need to be placed somewhere else? added to my theme's info file perhaps? Do I need to add a css class into my theme or something?

This is a great module which I really want to use, but if anything beyond basic install is required there should at least be installation instructions.

Comments

Comment #1

sander-martijn CreditAttribution: sander-martijn commented 9 February 2015 at 23:57

Priority:

Normal

» Major

I should have marked this as major because although it's probably super easy to fix/solve it's kind of a big deal when there isn't even anything about how to use it.

Comment #2

sander-martijn CreditAttribution: sander-martijn commented 10 February 2015 at 00:26

update:
1. There are instructions in the readme file (this doesn't change my feeling that it should be either on the main page and/or a documentation link).
2. the main problem was shown in status report - apparently this version doesn't support the latest version of underscore which is 1.7. rolling back to 1.52 solved it
3. your ckeditor needs the sourcedialog plugin, which isn't mentioned anywhere I could find. I figured that out by comparing my custom ckeditor build with the one linked from the main page and finding that one being the only one i was missing.

Comment #3

Wim Leers

Ghent 🇧🇪🇪🇺

CreditAttribution: Wim Leers commented 2 March 2015 at 19:24

Status:

Active

» Postponed (maintainer needs more info)

It's customary in Drupal to have detailed instructions in the README and high-level instructions on the project page. #2.2 and #2.3 are explicitly mentioned in the README. And they're even explicitly checked programmatically in the status report.

Where were you looking for installation instructions? On the project page? I know many modules do that :) But IMHO that's extremely wrong. The project page should only provide high-level info, especially because the installation instructions may have to be updated for a release. The README included with a release is therefore the best place for installation instructions.

Finally, I think that once you're used to Drupal, you'll find that many of the better modules with "special needs" (Quick Edit definitely has special needs that aren't typical of most Drupal modules) have status report entries that help you get everything set up correctly.

Does that answer all questions?

Comment #4

sander-martijn CreditAttribution: sander-martijn commented 3 March 2015 at 18:12

"once you're used to Drupal"... uhm "Member for7 years 6 months" - I've been building Drupal sites for at least that long starting in D5. I've built custom modules and themes, contrib'd patches etc for years. You shouldn't make such assumptions ;)

Nearly every module that requires more than just install/activate/set permissions has installation info either on the project page or on a dedicated documentation page, and I think that's appropriate, for one thing so I know what is entailed/required before I decide to download and install it. I guess different people like it different ways but I personally prefer having a webpage I can bookmark over opening readme files.

At any rate I found quickedit to be too buggy for my tastes (or more likely conflicted with too many other things this project requires), so unfortunately at least for now it's disabled.

Comment #5

kopeboy CreditAttribution: kopeboy commented 25 March 2015 at 22:27

Status:

Postponed (maintainer needs more info)

» Needs work

I think sander is right. If installation is complicated (anything more than enabling and having a Configure link) there is usually (and I think should be) at least a mention on the module's page.

What if I install with Drush or with FTP directly from Drupal interface? I would never open the folders on my server and look for a README if you don't tell me so.

I see there is a useful FAQ section in the readme, you may mention it to prevent new issues (it seems there are many open issues compared to #installs).

I also have some questions: does this work on any entity or on nodes only?
(when installation seems troublesome people will ask questions before spending time to test themselves)

Comment #6

doxigo CreditAttribution: doxigo commented 20 July 2015 at 03:12

To be honest, both of you have good points, the module homepage should only contain critical info regarding the task the module handles but it also needs a documentation page along side with it so people don't end up looking here and there (some might not be as bright to know that they should look into README file!).

Anyhow I know you guys are busy and generous enough to dedicate your time to develop such module barely have time to make the goddman documentation page! others might be able to contribute to the documentation maybe if given the permission to do so.