Re: thoughts on making a true Beginners Guide

Joomla! Documentation Workgroup

Moderator: Documentation

ReginaStreets
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 174
Joined: Sat Jun 13, 2009 7:19 pm
Location: Regina, Canada

Re: thoughts on making a true Beginners Guide

Post by ReginaStreets » Fri Oct 09, 2009 5:17 pm

Hey there.....

It is a shame that 'that thread' (http://forum.joomla.org/viewtopic.php?f=303&t=445633) denigrated into long, rambling rants and personal attacks because some valuable points were being made. One of the unfortunate thing about writing for beginners is that the only people who give feedback are generally too angry/frustrated to make that feedback even remotely constructive.

My background is in internet marketing, user training/experience and accessibility. In my current position, I wrote all the tutorials/support documentation for a new device. And, in my spare time, I have been writing/researching a program to teach not for profits how to use open source technology to build their brands and improve their efficiency.

Consequently, I not only have experience in user training/experience, I also have a vested interest in putting together a very strong 'Beginner's Guide.' So, I would love to help out with this project and put together something fairly comprehensive.

Please let me know if you would like my assistance - pm is excellent, then I can give you my personal email address.

Take care....

Greg H.

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: thoughts on making a true Beginners Guide

Post by Chris Davenport » Fri Oct 09, 2009 5:57 pm

Hi Greg,

No need to ask, just go right ahead and start writing on the wiki. The Beginner's page itself had to be protected from spammers, but if you'd like to start something elsewhere, perhaps in your user pages, then it can easily be transferred when ready. If you need any help getting started with the wiki, just ask.

Thanks for volunteering. :)

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Sat Oct 10, 2009 10:03 pm

is there a way that we can colarborate or pick a topic on the guide so we dont work on the wiki and then find we duplicated our work.. eg set up a section or tea cup system to make sure its done efficiently?
finding a nice little project fork tracker might help
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Sun Oct 11, 2009 8:38 am

without aiming to lead, i think one of the first things is to take alll the ODT links on the beginners guide page and convert them to wiki articles.. cant see the point of sending someone to the wiki and then get them to down load a document..
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: thoughts on making a true Beginners Guide

Post by Chris Davenport » Sun Oct 11, 2009 9:35 am

mandville wrote:is there a way that we can colarborate or pick a topic on the guide so we dont work on the wiki and then find we duplicated our work.. eg set up a section or tea cup system to make sure its done efficiently?
finding a nice little project fork tracker might help
I think a really good place to start would be create an outline of the topics that need to be covered and the order in which concepts should be introduced. With that framework in place it will be easier for people to then flesh out the skeleton and have all the pieces fit together properly and make sense as a single narrative.

What do you think?

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: thoughts on making a true Beginners Guide

Post by Chris Davenport » Sun Oct 11, 2009 9:42 am

mandville wrote:without aiming to lead, i think one of the first things is to take alll the ODT links on the beginners guide page and convert them to wiki articles.. cant see the point of sending someone to the wiki and then get them to down load a document..
That's a good idea. The only reason they were placed in ODT files in the first place was because of GHOP contest rules. It was always the intention to transfer useful content to the wiki.

The only one (that I'm aware of) that you can't transfer is Saurabh Bhide's guide, as the license is not compatible with the JEDL.

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Sun Oct 11, 2009 10:02 am

so its convert the ODT to wiki text and reverse engineer the PDF's where possible to wiki text..

i will look at the actual beginners guide thats in PDf and rip that apart.. (stand back everyone -- im going in.....)
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: thoughts on making a true Beginners Guide

Post by Chris Davenport » Sun Oct 11, 2009 1:40 pm

mandville wrote:so its convert the ODT to wiki text and reverse engineer the PDF's where possible to wiki text..

i will look at the actual beginners guide thats in PDf and rip that apart.. (stand back everyone -- im going in.....)
You shouldn't need to reverse engineer the PDFs as the source ODF files should be here: http://docs.joomla.org/GHOP_Contest_Tasks

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Fri Oct 16, 2009 9:25 am

chris check my user page if thats the idea of what is need - and for some reason i am not wiki coding aware..
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Fri Oct 23, 2009 2:34 am

Good news to those who are interested in a manual for Joomla. Several of us are now in the beginning stages of discussing comprehensive user guide for Joomla 1.6 (probably focusing on site building and administrative rather than API, although it would be great to see a separate document for that if there was interest).

We can really use some more people with strong Joomla experience, but writing, proofreading, html/css and general technology skills are valuable as well. Anyone is welcome to help if you think you can contribute. The link is: http://www.alltogetherasawhole.org/grou ... in-the-j16

Chris, I'd appreciate it if you could take a second to go over there and read the proposal. I'd love to hear your thoughts. Is there any chance of a possibility that we could work towards some kind of "official" status? I'm not making final decisions for our group, but my thinking is many more people would benefit if the manual was placed on Joomla.org. Otherwise, I think we're happy to be "unofficial".

You wouldn't have to make a final decision until you saw the finished product, but if you let us know now if it's a possibility... we can work according to your guidelines. BTY... you're more then welcome to participate if you like and have time.

User avatar
brad
Joomla! Master
Joomla! Master
Posts: 13272
Joined: Fri Aug 12, 2005 12:38 am
Location: Australia
Contact:

Re: thoughts on making a true Beginners Guide

Post by brad » Fri Oct 23, 2009 3:14 am

Why not do your work on the wiki so that everyone can participate?
Nice to hear you have been able to also encourage others to help you, and that you are setting the lead in wanting to contribute.

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Fri Oct 23, 2009 4:01 am

Hi Brad,

If you follow the link I explain why. I think the wiki is helpful and has a place, but I think there is a lot of interest for a more organized format... something that's very hard to achieve when you have so many people contributing and without strong coordination. Plus, many people like to be able to hit the print button. You know me... I've talked about this a bit here before :)

I hope everything has been well with you...

Jason

p.s. Mark Dexter, if you read this... It would be great to get you on board, or at least helping in some way if you have any interest. We have someone who has written/published a bunch of high profile computer books as our project leader so I think there's a lot of potential.

User avatar
brad
Joomla! Master
Joomla! Master
Posts: 13272
Joined: Fri Aug 12, 2005 12:38 am
Location: Australia
Contact:

Re: thoughts on making a true Beginners Guide

Post by brad » Fri Oct 23, 2009 4:14 am

I haven't read the link, but I am sure that Chris can fill you in on the plans to use the wiki to pull in content to a readable/pdf/printable form. Having the raw data in the first place I believe is what they need.

Anyway.. I'll leave it to them.

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Fri Oct 23, 2009 4:29 am

Well if you're ever curious, it's just a quick read. I feel a lot of people will benefit from an organized manual typeset in Indesign. This cannot be achieved in a wiki. A wiki (like wikipedia) makes a good reference... but not so good for an ongoing learning process, unless the different wiki entries have a strong cohesion and are very well organized.

A "manual" is pretty standard for almost every software I can think of, yet Joomla doesn't have one. I do believe the wiki and this document can peacefully exist side by side. It would be good for everyone I think if the powers that be at Joomla would embrace the idea.

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Fri Oct 23, 2009 10:56 am

while i agree every piece of software should have one, i find the sectioned pdfs/docs for joomla useful. eg if you look at the manual for phpbb its a covers everything, unprintable, document.
you will also need to look at how often you update it and where to store the copies.
would the official joomla version differ from the un official version.
yes the post on the link you provided was short but the comments that followed were not. wonder why some of the people on that link never came here to discuss it previously in this existing topic
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Fri Oct 23, 2009 9:00 pm

Hi Mandville, I haven't read the phpBB docs, but let me ask... is it maintained by the community, or by one or a few individuals? My guess is if it's really useful (and there's a consensus withing the phpBB community that it is), then it's probably more directly organized than Joomla's.

I hope Chris, Mark and anyone who contributes a lot to the wiki don't take this personally. I think you guys are doing a great job, but I think the problem with Joomla's current documentation is because anyone can contribute. At first thought, that seems like an effective way to do it (not to mention that it embraces the idea of a community working together), but when you see the results... it simply isn't cutting the mustard. This isn't just my opinion. It's the opinion of my many clients who give me this feedback. It's the opinion of many more who write comments here on the forum, and all over the web about Joomla's poor documentation. It's why this thread was started.

Now I'm sorry Chris that we've had disagreements in the past. I don't endorse negativity or the behavior like the person who posted in the locked thread. That's not what I'm about, and I think you had my intentions wrong last time around. I'm interested in helping Joomla become better and have no interest in drama. Do you guys want to work together... or is it more important that things get done according to a specific vision that you have, regardless of whether it's working?

Mandville... you should check out Amy's site and think about helping if you have some time. You seem like an expert Joomla Chix (there's a group on her site called that) to me :), and I think we're still a little short of help for the J1.6 doc project. Writers with solid Joomla skills are a must for us.

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: thoughts on making a true Beginners Guide

Post by Chris Davenport » Fri Oct 23, 2009 9:18 pm

More people working on writing documentation are always welcome. :)

The wiki is open to everyone and the material on it is available to everyone under an open license that is very much in the spirit of the GPL.

I know you have been critical of our use of a wiki as the central repository for documentation and I won't repeat the arguments here as the discussion is surely available in the archive somewhere.

In summary, by using an open-source wiki as our documentation repository we make it possible to:
1. Lower barriers to participation. Nobody needs to buy a license to the software tools in order to contribute. The tools are open source and available online for anyone to use. Write access to the wiki is available to anyone with a valid email address.
2. Support and encourage modular documentation, which reduces duplication of effort.
3. Encourage documentation re-use and re-purposing, so that a wide range of material can be generated from the same source.
4. Support output generation in any format where a tool-chain exists to support it.
5. Give people the power to use their own tool-chains to produce their own output documents by allowing open access to the wiki API.
6. Have full version control of all contributions.
7. Easily import contributions from a variety of sources in almost any format.
8. Do all of the above without huge administrative overhead. The wiki handles most of the management automatically.

If you feel that you can work better without a wiki then please go ahead. I look forward to seeing what you can come up with and I hope that your work will make its way onto the wiki at some point (the sooner the better of course). Sadly, I'm already hugely over-committed so I won't have time to contribute to your project myself, but I wish you luck all the same.

Incidentally, there is no such thing as "official" status. There are some minimal rules concerning the material that can be hosted in the joomla.org domain, but they are not onerous and are there mostly to ensure that we maintain an open and inclusive environment.

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Fri Oct 23, 2009 10:30 pm

unleash.it wrote: Mandville... you should check out Amy's site and think about helping if you have some time. You seem like an expert Joomla Chix
I am already in there and she knows it, people just dont look hard enough <grin>
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Sat Oct 24, 2009 12:12 am

I am already in there and she knows it, people just dont look hard enough <grin>
Woe is me!

Chris, thank you for taking the time to explain your reasoning. I do understand your points and think many of them are valid. However, what about the end result? Two years after it's beginnings, there are large gaps and it's kind of a maze of info... and it sounds like you're aware of it. That's not gong to be the case if we can gather enough steam for this manual project. Do I think the scope of this manual can replace what the wiki does? No. As I keep saying... the wiki makes a great reference for all of the reasons you pointed out.

The advantage of a static manual is in it's organization and ease of following along. It can't be updated as often, but revisions are certainly possible. I don't think constant revisions/updates are really that big of a deal. Why would you need them if you can gather and edit the main information ahead of time?

As for official... I guess what I'm asking is whether we might be able to place the document in a prominent location on Joomla (like the home page or the front page of the wiki). But if you know you're not ready to do that from the start, that's ok... maybe you'll change your mind later. But if you're open to putting it somewhere, can you please let me know what the guidelines are again (or point me to a page)?

The one thing I felt was a bit suppressing in the past (although I did actually agree to your terms) was the limitation on linking to resources besides http://www.joomla.org. There are many resources that would be helpful to the users, and limiting that does feel limiting. However, if that's a requirement I'm sure we can live with it.

Thanks again for your help Chris.

One more time... if any of you rare breed doc writers feel the urge, you can be put to good use over at: http://www.alltogetherasawhole.org/grou ... in-the-j16. There's a solid start, but we still need to gather a bit more steam.

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: thoughts on making a true Beginners Guide

Post by AmyStephen » Sat Oct 24, 2009 5:57 am

Jason -

Sounds like the team is interested in a PDF booklet. I'm not concerned about that because we can also copy and paste the material into the Wiki, this isn't a problem. Distribution of the PDF can be done countless ways and I think it will be fun to talk about how to do that. We might find some clever approaches.

It's best not to drop the link for that site here for a few reasons. The most selfish one is the site is only for professionals and one of my least favorite things to do is tell people they aren't welcome. It's growing fast enough a little each day by word of mouth and keeping it intimate helps the work teams, like yours. Also, I would really feel bad if these efforts to help the community reconnect turned out to hurt the feelings of those people I've been working with these past many years.

One thing that will be really helpful, Jason, is to model for people how to collaborate and find ways to involve as many as possible. So, if your team pulls together a table of contents, for example, I'd encourage you to post it here and get feedback from Chris and some of the new learners here. At little points in the process, just bring it in and get some feedback, and show folks how to do that. It's that re-integration we want.

Chris - if you have lists of beginner material you want, certainly point those things out too.

Thanks guys.
Amy

User avatar
mandville
Joomla! Master
Joomla! Master
Posts: 15150
Joined: Mon Mar 20, 2006 1:56 am
Location: The Girly Side of Joomla in Sussex

Re: thoughts on making a true Beginners Guide

Post by mandville » Sat Oct 24, 2009 10:18 am

Amy, just realised some of the newer members of the forum may not know the RL names behind the forum handles.
HU2HY- Poor questions = Poor answer
Un requested Help PM's will be reported, added to the foe list and possibly just deleted
{VEL Team Leader}{TM Auditor }{ Showcase & Security forums Moderator}

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: thoughts on making a true Beginners Guide

Post by AmyStephen » Sat Oct 24, 2009 1:53 pm

Good point, mandville (without the extra E), I should have indicated unleash.it is Jason, before using his name - thanks for helping clarify.

I keep thinking the mistake we (Jason included!) made was not making certain Jason was able to contribute his work. I personally did not try very hard to help and judged him wrongly. It's apparent he feels strongly about the need for an organized guide in a more user-friendly print format and he is willing to make this happen. So, I'm excited we have a chance to fix this.

So, Jason's PDF is a given. And, while it's important we help him meet his needs, we still must respect the community consensus that brought us the Wiki. We should be smart about the process, and the benefits of a well considered, sustainable architecture are clearly documented in the list Chris provided. As I see it, those are the boundaries we are working within.

Then, it dawns on me, is there any reason we can't create well organized booklets out of the Wiki? I did a quick search at Mediawiki and found this PDF book. Chris - if we worked on a test Wiki and tried that extension out, would you be interested in seeing what it might be capable of as another output option for our Wiki? Jason - would that be something we can look at as a way of helping you meet your goal in this effort?

If not, we'll keep working on this. Thanks!
Amy

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: thoughts on making a true Beginners Guide

Post by AmyStephen » Sat Oct 24, 2009 2:09 pm

It was late -- 1:30 or so, last night when I found this thread, and I didn't get a chance to read all of the posts completely. It sounds like there are plans to bring in PDF capability. So, my Captain Obvious comments were kind of dumb. :-P

Jason - these PDF plans are really good to hear. We should be able to easily fit within the community process and get that formatted output.

Chris - is there a sandbox we can work within? Brad's point about making certain we involve others, here, too, is valid. We can meet that need, too. (Jason, don't worry if you want to work in another format - all of this can easily come together.)

Mandville - as to why people didn't come here to have those discussions, I appreciate you recognizing that as a point of concern. In fact, getting to the bottom of that question is the entire point of the site. We are very intentionally reaching out, through email, Skype, Twitter, smoke signals to our professional community members, and helping them return to a contributor status within this project. The GPL talks were devastating to our community and we need to help people come to terms with what happened, come back together, empower themselves as community members again, so we can all move forward.

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: thoughts on making a true Beginners Guide

Post by Chris Davenport » Sat Oct 24, 2009 6:47 pm

I think you're still failing to grasp the point that the wiki is not the only end result. The wiki is just a tool. If you want static manuals (and I totally agree that static manuals would be useful), then you can pull data from the wiki and assemble them. There is an open web API and tools are available to do that. If you don't want to use the tools that are available, well that's your choice; "You can lead a horse to water but you can't make it drink" as the saying goes.

Yes, I am acutely aware of the shortcomings of the current documentation, but I think the answer to that is to get more people filling the gaps and helping with reorganisation of the material rather than starting a parallel project with all the duplication of effort that that entails.

I fully understand that the techniques of single-source, modular documentation may be new to most people and many will never be closely enough involved with the documentation effort that they would learn how to do it. But that's okay, as the problem is in getting original content written rather than in editing, modularisation and assembly.

The rules for linking to other resources are basically the same as the forum. Promotional or self-promotional links will be removed, but we do allow links to clearly impartial resources such as php.net and w3schools. Of course, there will always be a grey area in between and the Doc Team will use its judgement in deciding if a given link can stay.

If you want a PDF document then there are tools that can generate it from the wiki. If you want to start with a table of contents, then where better to do that than the wiki? The wiki is a community resource that is open for anyone in the community to create the documentation they want. Part of my role as Doc Coordinator is to enable people to write the documentation they need. If there is some tool you need to help you to do that, then just ask and we can investigate.

If you're serious about writing documentation then the hard part is planning it and writing it. Getting it into whatever output format you want, be that PDF, Docbook XML, CHM or whatever, is the easy part. My advice to you is to completely forget about output formats and focus on, to begin with, planning the document(s) you want to see. Ask yourself questions like: who will read it, what prior knowledge do they have, what concepts need to be explained and in what order, what tasks need to be described and in what order, and so on. From that you can start to make a list of the "modules" that you will need. That becomes a contents list and a map of module titles (=wiki page titles). Then start writing, being careful to do it in a context-free manner so that modules can be re-used or re-sequenced. Only when you have enough content will it be worthwhile experimenting with assembling the modules into different output documents and different formats and for that I've been considering installing the Collection extension on the wiki (http://www.mediawiki.org/wiki/Extension:Collection).

@Amy. You asked about a sandbox but I don't understand what you are asking for. The wiki is the perfect sandbox for experimenting with documentation. If you don't want to integrate a page into the main corpus of material then simply put it in your user pages until you are happy with it, or put {{underconstruction}} at the top of the page. I know some people are uncomfortable working in the glare of full public view, but you can always work on your local machine and upload when ready.

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Sat Oct 24, 2009 9:49 pm

First of all, I'm not making any final decisions for our group and we'll decide on our direction together. I agree with Amy's point that it would be nice for all of us to have a consensus and work together as much as we can. I also see her site as an extension, rather than a replacement for all of the good stuff that goes on here. In fact, that's why I posted here right at the beginning.

I have no desire to push people against their will in a direction I alone see fit. But, I do feel pretty strongly (well as strongly as I can feel about AN INSTRUCTION MANUAL that I'm thinking about volunteering on) about why I think a separate, static document would be a HUGE BOON for Joomla. Now if everyone here and at Amy's site comes to the consensus that I'm living in the past, I'm not unreasonable... although wikis aren't much in my interest or area of expertise. In any case, I think it's important that we're having this dialog, and I appreciate Chris and Amy or anyone else, your willingness to listen. That more than anything is what felt frustrating before... especially in light of that I had just spent many hours volunteering to provide documentation. I never really felt like any one person was to blame for the problem (and I never felt like a singular victim), but was a bit frustrated by the system in place and just thought it could work better. I feel like those events are past, and am optimistic that change is possible.
So let me move on and try to put this into simple terms by asking a question. Does Joomla want to appeal to designers? How about businesses, non-profits, large organizations? I'm pretty sure you do, but maybe we're just not agreeing on how to reach them.
I think you're still failing to grasp the point that the wiki is not the only end result.
No, I don't think I'm failing to grasp it. I've mentioned this in the past, but I'll say it again. The automated output you might get is not going to be great. It's never going to be either very efficient or pretty. Aesthetics are very key if you want Joomla to be appealing to non-engineer type people... which are actually the vast majority of current and potential Joomla users. I can see where you're going. But I think you're more concerned about the benefits of the software for the workflow and process then the end result. It's my opinion the end result should be given the priority over the process. I don't want to create a religion over this... but a richly formatted manually is going to be much more warm and fuzzy to people (for lack of a better term) then anything the wiki can ever be.

Wordpress and Drupal both have online docs, and IMO are better organized then Joomla's. While Joomla's wiki can improve if the time and energy is available, I do think a separate document is going to appeal to a wider audience. Part of the difference of opinion here is that I think an "old school" print style user manual, even in 2009, is the best format for documentation. It doesn't have some of the advantages that an online app can provide, but it's also more human. Open up a Joomla (or any computer) book and tell me what you see. A good guide will have several recurring themes and patterns like sidebars, images with formatted captions, rich typography that makes it easier to follow, etc. The wiki provides some of this… but not to the level possible that I imagine.

Quick typography fact: studies have proven serif fonts easier to read large amounts of information. Unfortunately, there aren't any great web friendly serif fonts. Georgia is ok, but it's a bit weighty for reading large amounts of text. So mostly you'll find arial/helvetica used online for reading material. There are fonts we could use in a PDF that are better suited both on/off screen and more attractive. Again attractiveness, lets face it, makes us feel warm and fuzzy about Joomla, and will want to keep reading.

Don’t forget that designers (I’m kind of a hybrid, but design is where my roots are) are the ones most likely to want to help with documentation because we’re not so good with PHP. But many of us, put simply, would be bored to have to conform to the staidness of the wiki. We like attractive things and nice end results. I think we will have more fun doing it in the way I have in mind than the wiki. And I think that most people who read the documentation, even if unconsciously, feel the same way. But the bottom line is… if you want help, maybe you ought to think about the need to make it desirable and fun (as it can be) to want to help ;)

Last but not at all least, too many cooks spoil the dish. I just feel like it's a 1000 times easier to get a few minds together in an organized way then to have Joe Beginner come in and do what they want. Sure it's noble and the Joomla way (which I appreciate), but can it really work? I think 2 years later we have our answer to that.

Whew baby, that's getting long. But I think worth it to try to explain where I'm coming from. I believe everyone here is reasonable, we just all have to decide where this should go knowing that we have some different mindsets. I’m thinking the best thing to do would be to see what the majority wants to do. I’d like to present the facts including Chris’s ideas, see what people think and then take a vote. Anyone object to this? If you do, please say so.

I probably haven't addressed everything said, but I think that's enough for now! Some of your ideas about planning I agree with Chris, and whether this will turn into a wiki project or be a stubborn old PDF, I will be learning from the wiki. And if it’s going to be a PDF, certainly if someone wants to take a little time to do the re-purposing it can get fed into the wiki as well. Amy, my apologies about my big mouth, the word is now mum. I didn't realize you felt that way, but I understand where you're coming from on both counts.

I hope you're all enjoying your weekend. The suns beckoning over here... I now need to get out!

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: thoughts on making a true Beginners Guide

Post by AmyStephen » Sat Oct 24, 2009 11:03 pm

Chris Davenport wrote: @Amy. You asked about a sandbox but I don't understand what you are asking for. The wiki is the perfect sandbox for experimenting with documentation.
You are right - we do not need a sandbox. What's the saying? Be bold? We will be bold!
Chris Davenport wrote: The rules for linking to other resources are basically the same as the forum. Promotional or self-promotional links will be removed
That is absolute right. I agree.
Chris Davenport wrote: If you want a PDF document then there are tools that can generate it from the wiki. If you want to start with a table of contents, then where better to do that than the wiki?
Yup.

Jason - No apologies required. This is going to work out well. Let's keep the group going and we'll keep in touch here and make this happen.

Thanks, all!

unleash.it
Joomla! Explorer
Joomla! Explorer
Posts: 268
Joined: Wed Dec 12, 2007 2:40 am
Location: Frisco, CA

Re: thoughts on making a true Beginners Guide

Post by unleash.it » Fri Oct 30, 2009 1:25 am

Just a quick explanation to anyone wondering why a bunch of posts went missing on the new documentation project. I canceled my account, but had no idea the results would mean that other people's (or even my own) posts would be removed. Sorry about that.

Tony if you read this, my leaving certainly wasn't because of you or because we may or may not have seen things a little differently. I left because of the incorrect message I was given by Amy that we as a group had the freedom to decide on our direction. The falsity of this has been made apparent by her contant exective decisions about every aspect of the process.

I started the discussion with an idea to have the end result be a printed manual. In the beginning, other people including Amy supported the idea (both publicly and privately). Yet at the same time she told me she supported my idea, she did her best to push the group back to the standard approach. So without further rambling about how she got me all energized for the second time in 2 years about something that will never be allowed... All you guys have my sincere best wishes with your project. Have a good time.

Jason

p.s. I've said all I have to say and won't be replying here.

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: thoughts on making a true Beginners Guide

Post by AmyStephen » Fri Oct 30, 2009 5:07 am

Jason -

The team is deciding. You just weren't able to convince them to do things your way. I am not the boss. I will not tell the team to stop. You have to advocate your position with them. It's how it works.

Personally, I'm glad they choose to work with Chris and have decided to the wiki. I can't imagine why cooperating with others and collaborating is the wrong thing to do. There's a PDF print capability coming so you should be able to get that booklet you want.

Not sure what else to say. Some people step up and lead and others don't. In the end, when people use Joomla! 1.6, they will want a User's Guide. It looks like because of the efforts of that team, there might be one. Hurray!

Amy

serenity now
Joomla! Apprentice
Joomla! Apprentice
Posts: 21
Joined: Tue Sep 29, 2009 8:07 pm

Re: thoughts on making a true Beginners Guide

Post by serenity now » Thu Nov 05, 2009 10:26 pm

I will read whatever people have written so far and offer feedback (of a non-offensive nature, and fully compliant with this forum's rules).

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: thoughts on making a true Beginners Guide

Post by AmyStephen » Thu Nov 05, 2009 10:41 pm

Awesome! Really glad to have your involvement; much appreciated!


Locked

Return to “docs.joomla.org - Feedback/Information”