Problem/Motivation

* The readme is very small (for a module of this complexity)
* Swentel complains at presentations that he always has to answer the same question ;)
* The community docs http://drupal.org/node/644662 can be improved. There is no Getting Started section for example
* There is plenty of good information available (in blogs and videos), but it is not in the docs on d.o.

Proposed resolution

* I'll attempt to improve the community docs and add a Getting Started section
* For the readme I'll create a summary of the docs

Remaining tasks

* Everything

I would like to know if the maintainers support this initiative and whether they are available for feedback.

CommentFileSizeAuthor
#3 Folder.pdf129.87 KBswentel

Comments

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Issue summary: View changes

smiley

swentel’s picture

swentel commented

Swentel complains at presentations that he always has to answer the same question ;)

Hehe, I of course welcome this. I know from myself that I'm really bad at documentation writing and I also mostly fail at finding people for it.
I'm available for feedback, I'm usually pretty close on the issue queue anyway.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

Great. Gould you help me to text of this booklet?
http://labs.krimson.be/sites/default/files/attachments/2011/08/17/Bookle...
In this pdf the text cannot be copied (is a bitmap I suppose)

The booklet & video are a great starting point for docs.

swentel’s picture

swentel commented
StatusFileSize
new Folder.pdf129.87 KB

I think you should be able to copy paste from this one.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

I think the structure of the booklet is an excellent start for the documentation.

I will start with 3 sections:

- What is DS
- - Installation
- - Configuring a layout

And continue later with rest.

I'll try to merge with the existing docs pages where possible.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

Given this a bit more thought and this would be my structure for the docs section:

- Introduction
- - Installation
- - Configure layout
- - Fields
- - View Modes
- - Search
- - Field templates
- - Region to block
- - Extras
- - Panel View Modes
- - Views Displays
- - Export configuration
- - Display Suite as API
- - - D6
- - - D7
- - About Display Suite <-- can contain history and comparison w Panels)
- - Further reading & viewing <-- listing the screencasts and articles elsewhere

I guess small changes can/will occur when I have started ("voortschrijdend inzicht" as they say in NL).

This structure marries the booklet with the current community docs.

Let me know if you think this could work as structure for the community docs.

swentel’s picture

swentel commented

Sounds great to begin with! One thing I'm wondering, would you list the changes between the 7.x-1.x and 7.x-2.x branch on the same pages ? Changes between those branches are listed on http://drupal.org/node/1524800 and are especially different regarding the choosing of layouts and field templates quite different.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

One thing I'm wondering, would you list the changes between the 7.x-1.x and 7.x-2.x branch on the same pages ?

Yes, definitely. I know this page is important.

I'm not going to throw any information away, by the way. (unless very outdated or very irrelevant, but I will let you decide)

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

I encounter small UI-text inconsistencies such as e.g., the verti tab "Extra classes for regions" which holds a textarea called "Styles for regions". I would find it less confusing if all were called "classes" or "styles".

Do you want me to take note of these (in a separate issue)?

swentel’s picture

swentel commented

Those should all be 'fixed' in the second branch normally. I would be good to make those consistent in the first branch as well, might be good to put them in a separate issue I think. Note that I'm scheduling a 7.x-1.6 release on the 4th of October, along with 7.x-2.0 that day as well, so not everything will be committed by then, depending on how much it is of course, been a while since I looked at that version.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
  1. Does it make sense to make the documentation for the 7.x-2.0 then?
  2. That will be the "main" version that most new users are supposed to work with, right?
  3. You think the outline above is as valid for 7.x-2.0 as it is for the 7.x-1 versions?
swentel’s picture

swentel commented

New users will switch to that branch yes, so I think it makes the most sense to use that for the documentation. The outline is the same, except for panel view modes which is gone in the second branch.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Assigned: Unassigned » batigolix

I've created a draft for the first three sections:

- Introduction
- - Installation
- - Manage display (I moved away from using the term "layout" conform DS 7.x-2.x)

Have a look at
https://docs.google.com/document/d/1kfO_JXZcE0mtONQ1CRKCYDcTBe6rMWFgY6M7...

If you think that this is ~90% okay then I put it on drupal.org for further fine tuning.

swentel’s picture

swentel commented

Wow, that's great! I'll try to address the doubts somewhere this week if you give me access to the document as well.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

I shared the doc with you (and enabled anonymous editing access).

I don't think there are real big questions that need an answer (just small stuff like e.g. if the extras module is required for custom css field classes). No showstoppers, I hope.

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

By the way, and slightly off topic: Did you read this book?:
http://www.amazon.com/Drupal-Fusion-Display-suite-project/dp/1477637753
Is there useful stuff in there for the Docs I'm assembling?

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

Yup, I'm done with first draft, from Installation to Export:

https://docs.google.com/document/d/1kfO_JXZcE0mtONQ1CRKCYDcTBe6rMWFgY6M7...

I only had some problems getting the Views stuff (screencast 10) to work. So I need some help with that (not urgent).

I now need:
* create screenshots
* revise
* get a "90%=Okay" confirmation from you
* move the stuff to d.o., add the links, re-arrange existing d.o. content according to outline
* fine-tune (can be done over the next weeks, no hurry)
* do the readme(?)

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

O nay, forgot "Regions to blocks" and "Manage forms" ...

swentel’s picture

swentel commented

I haven't read the book, I only found it out it existed during Munich. Pity that the author hasn't send me a copy :)

Other than that, wow, that's a fantastic overview already, so yes, that's definitely a go for me. I don't have time to revise further until the weekend though.
I saw you added some UI glitches, feel free to add them into a separate issue, there's basically ten days left for the 2.0 release, so that would be great - of course, no pressure here, this stuff is already amazing.

Next time we meet, remember that I overload you with your favorite [insert drink here].

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

overload you with your favorite [insert drink here]

ouch, that is a tough one. I tend to down anything that has an alcohol percentage between 3 and 17% - except for certain Belgian, Dutch, Danish and American pilseners. And please: no Awesome Sauce :P

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

Smile!

Everything is on d.o. now: http://drupal.org/node/644662
(Except the Views Display part which didn't work for me.)

I also restructured the existing material to match the proposed outline at #5

You can revise it directly on d.o. And so can the rest of the Drupal community. -- I didn't do a proper proofreading, spell check or link check, yet :(

I disabled editing for the Google Docs to prevent confusion.

There is still a couple some things that need clarification so: I Will Be Back

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Title: Improve community docs & readme » Improve community docs

Created an issue for the Readme improvement: #1796638: Improve readme

swentel’s picture

swentel commented
Status: Active » Closed (fixed)

I think this is ok already - people who have problems can always make changes to the pages to fix them.

swentel’s picture

swentel commented
Issue summary: View changes

typo