I'm going to be working on thoroughly documenting the 2.x branch for end-users, basic topic including:

* Behaviors
* Data from CCK, KML, Geo Taxonomy
* Views, views arguments
* Styles
* Exporting & Importing maps

I've already written a bunch of this as markdown with screenshots, but the Drupal.org book hobbles any attempt at making good documentation (it cuts out images, for one thing). Possibly this could be in the module; the first place it might end up is on MapBox.com.

Comments

tmcw’s picture

tmcw commented

Adding a lot of helptext to the module:

http://drupal.org/cvs?commit=326534
http://drupal.org/cvs?commit=326516

Staying away from advanced_help for the moment.

tmcw’s picture

tmcw commented

Note that my current work in 2.x is moving away from using Advanced Help integration and towards inline documentation and building better book pages and README.txt. Both of these formats have some serious limitations (no images, so no screenshots, so limited illustrative possibilities), so some more documentation might fall on MapBox.com or blog posts.

zzolo’s picture

zzolo commented

tmcw, I am curious why you have strayed away from advanced_help? I am happy for any documentation, but just curious. I don't think advanced_help is the best thing int he world but form what I understand it is pretty much the most standard way to include rich documentation within a module.

tmcw’s picture

tmcw commented

In short, I think it's a better idea to have documentation on Drupal.org that's easy to reference if you don't have the module installed, if you're going for the longform, narrative-type help that advanced_help aims for. The Drupal help system really does a pretty good job of inline help, and there are tons of places where we should be making the UI better instead of explaining it more. Splitting help between doc pages, drupal help, advanced_help, and external sites is just going to be tricky and will increase the effort of documenting new features (since we'll have stale documentation as well).

Of course, advanced_help documentation doesn't hurt at all, and I have no immediate intentions of tearing it out, but I think that new help is better put elsewhere.

zzolo’s picture

zzolo commented

Sounds reasonable. Also, if you want to put screenshots in drupal.org handbook pages, I am a member of the doc team and would be happy to do it for you.

jesss’s picture

jesss commented

+1 for step-by-step instructions on how to work with Views. I'm hopelessly confused.

tmcw’s picture

tmcw commented

jesss: indeed. The beginnings of it are in the tutorial in the documentation book.

tmcw’s picture

tmcw commented

Posted source of the documentation with references to the images

http://gist.github.com/305868

jesss’s picture

jesss commented

Thank you! I've got a map working, though I still have to iron out some theming kinks. Some suggestions for the documentation on creating the preset, based on what was tripping me up:

1) You have to make sure your views display that you just created is enabled and activated under Overlay Layers on the Layers & Styles tab.

2) You have to make sure that the Default Style isn't set to Invisible.

On a related note, I don't understand why, when you add a new preset, Invisible is the pre-selected style option. It left me scratching my head wondering why none of my markers were showing up.

tmcw’s picture

tmcw commented

Starting by rewriting the text documentation in Markdown, since it's easier to draft and more immediately useful. jesss, I've created an issue for the Transparent-by-default behavior.

http://drupal.org/node/717344

zzolo’s picture

zzolo commented

So, I have added the images. But I think this might cause a bit of a problem. Once the input format has been changed to documentation, I think, regular editors cannot edit it.

So, the best workflow may be for you to update your markdown version, as you were anyway, then export it as HTML and I can change the article. Kind of silly, but not really that bad.

Also, note that I did not actually upload the images to d.o, I just used the img tags that were in there.

tmcw’s picture

tmcw commented

That's bizarre. I guess this is a spam prevention issue - Is there anyway way around this? Drupal.org kind of cripples everything. What does it take to get on the documentation team?

zzolo’s picture

zzolo commented

This is actually how Drupal's input filters usually work. It's a simple permissions thing. It is an annoyance for sure. I doubt they would give you documentation team access just to be able to put images in, but here is the link: http://drupal.org/contribute/documentation/join

I don't see this as "crippling" documentation efforts, just a kind of annoyance. If you do want to put documentation off of drupal.org, it has to be in a place where people (specifically the developers) can all edit. The Drupal.org docs may be a little annoying, but they are still wiki-like and that is pretty important for documentation outside the module.

tmcw’s picture

tmcw commented

That isn't really an inherent problem with input filters; someone could easily allow normal users to also have permission to the Filtered HTML or Full HTML formatter.

I've added another documentation page, explaining layer types.

http://drupal.org/cvs?commit=331874

I'd like to keep core documentation on Drupal.org just as much as you and phayes. Some screencasts and tutorials may live offsite, and if so they'll be freely licensed for anyone to bring into Drupal.org for those with the ability to add images to things.

zzolo’s picture

zzolo commented

I think this broad issue can probably be closed. Handbook pages are shaping nicely thanks to @tmcw as well as inline module help. I think one task to create is to remove the old advanced_help stuff that is in the 2.x codebase (I am assuming its still there); nonetheless, I'll make a ticket for that later.

Feel free to re-open or start more specific issues.

zzolo’s picture

zzolo commented
Status: Active » Fixed

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.