The Joomla! Forum ™






Post new topic Reply to topic  [ 96 posts ]  Go to page 1, 2, 3, 4  Next
Author Message
PostPosted: Fri Aug 24, 2007 10:08 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Hi Everyone,

First of all my apologies for the delay in getting this project started.  It's been a particularly busy time for us and the template tutorial had to take second place for a while.  To move things forward Ian and I have now decided to focus on separate areas, so while Ian will be working with the J!101 people, I will be looking after the new template tutorial.

The Doc Team finds itself in the unusual position of having a significant number of volunteers who have expressed an interest in helping us produce the new template tutorials.  Not including Ian and myself we currently have 21 people who have put their names forward.  The question arises as to how we will manage such a large team.  I've given this considerable thought in the last few days and I think we have an ideal opportunity to try something that I've had in mind since the early part of this year.  What I'd like to do with this project is use the technique of "Modular Documentation" to produce modular, re-usable documentation.  There is a learning curve here, for me as much as anyone, but I'm pretty certain that this methodology will produce the most useful result in the time available.  It also lends itself to a team-working environment where people can take on particular roles that suit their particular interests and skills.

The idea is that we do not write a complete document, such as a tutorial, as a monolithic object.  Instead we write small, standalone modules that make sense in any document context and in any reading sequence.  A tutorial, for example, can then be constructed by assembling a subset of these modules, adding only formatting and cross-referencing to make the finished document.  Importantly, a different subset of the same modules can be assembled into a different document for a different purpose or target audience.  This is the essence of re-usability.

So how do we go about writing these modules?  Well, each module answers a basic question: who? what? when? where? why? how?  As a rule, each module answers one question only.  There are several types of answers and each module will answer the question in one way only, although different modules can be constructed to answer the same question in different ways.

Having created the modules, we assemble them into documents in a specific format and for a specific audience.  Examples of such documents would be printed manuals, online help and training materials.  In order to produce the finished document we do not add anything except cross-referencing which can take the form of tables of contents, inline cross-references and indexes.  Apart from the cross-refences all our content takes the form of re-usable modules.

We begin the process by identifying and building "primary" modules.  Each primary module will be of one of the following types (listed alphabetically):

  • Definition lists  These are most commonly used to list components, so for example, we might create a definition list which lists the names of the principal files contained within a template and introduce the purpose of each.
  • Glossaries  These are a specific form of definition list that defines technical terms.
  • Procedures  These are step-by-step instructions that explain how to perform tasks.
  • Processes  These are similar to procedures and topics.  Processes differ from procedures in that they are narrative rather than imperative.  They explain what someone or something does (declarative), not what users should do (imperative).
  • Topics  These are texts that answer specific questions.
  • Troubleshooting scenarios  These are a hybrid of topics and procedures.  Each scenario explains one problem and its solution.

Primary modules may themselves contain secondary modules, such as the following:

  • Examples
  • Figures
  • Itemised lists
  • Notes
  • Tables

These secondary modules can be constructed separately, although they don't have to be.  For example, figures will probably be constructed using a separate graphics package and may well be produced by a graphic artist working independently within the documentation team.  Secondary modules can be re-used within different primary modules.  Documents are assembled from primary modules only; secondary modules must be integrated into primary modules before they are used.

Much in the spirit of "agile programming" in which Joomla! itself is developed, we will try to practice "agile documentation" so that at any point in time it will be possible to generate an output document and quickly see the state of development of the documentation effort.  This can be used to further refine the modules and improve the quality of the end product.  How we generate these "builds" is not entirely certain at the moment and we may need to create new tools to support this process, but hey, we have access to some of the smartest developers on the planet so anything is possible.

There has already been some brainstorming going on in this thread: http://forum.joomla.org/index.php/topic,201431.0.html.  Let's continue throwing up ideas but in particular let's look at the kinds of modules that we might construct.

And for those that haven't already introduced themselves, please add a little something to this thread: http://forum.joomla.org/index.php/topic,201429.0.html.  Oh, I guess that should include me....

Let's get started and have some fun!

Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Fri Aug 24, 2007 10:48 pm 
Joomla! Apprentice
Joomla! Apprentice

Joined: Sat Aug 04, 2007 3:03 am
Posts: 45
This is a helpful post

I'm wondering: when you say module, do you mean that in the Joomla sense of the word, or as a general concept?

Also, where should we start? Is the wiki our drawing board? or do we submit content to the forum?


Top
 Profile  
 
PostPosted: Fri Aug 24, 2007 10:56 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
The "module" in "modular documentation" is just a chunk of documentation and is not related to Joomla! modules.  Present thinking is that each module will be stored as a single wiki page.

For the moment I'd like to throw some ideas around about what modules need to be written and we can do that in the forum.  I plan to set up an area on the developer wiki where we can all create and save our modules once we get started actually writing them.

Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Sat Aug 25, 2007 1:01 am 
Joomla! Apprentice
Joomla! Apprentice

Joined: Sat Aug 04, 2007 3:03 am
Posts: 45
What would you think about just calling them "wiki pages" instead of modules? Both terms: "Joomla Modules" and "Modular Documentation" have precedent, but I figure that homonyms are innately confusing. Experienced documentarians can think of the "wiki pages" as "modules" but using separate terms will prevent confusion for the majority of people who've never heard of "Modular documentation."

I got curious, and started googling for search terms:

"Joomla Module"
"Modular Documentation"
"Documentation Module"

"Joomla Module" had the most hits...

And interestingly, for "Documentation Module" first search result was drupal.org... where as far as I can tell, the term "module" was used to to describe code.

My proposal is in the spirit of limiting potential confusion...


Top
 Profile  
 
PostPosted: Sat Aug 25, 2007 10:33 am 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Alas, the word "module" is much over-used I think.  The term "modular documentation" has been around just as long as "Joomla! module" and no doubt there are even earlier uses of the word.  Just something we have to live with.

But I take your point that there may be some confusion.  Calling them "wiki pages" would be tying them to a specific implementation.  Some modules will not be wiki pages at all.  Images can be thought of as secondary (documentation) modules and we might want to include documentation from external sources, such as DocBook.

Perhaps we could call them "fragments" or "snippets" or something like that?  I'm open to suggestions.  :)

Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Sat Aug 25, 2007 12:26 pm 
User avatar
Joomla! Explorer
Joomla! Explorer

Joined: Mon Dec 12, 2005 5:34 pm
Posts: 418
I like "fragments" 'cos that's what they appear to be: incomplete.
Chris Davenport wrote:
I'm open to suggestions.  :)

"unit" ?

What are your plans/ideas to cross-link/-reference/-whatever those fragments? Adding a hyperlink is one thing, including them physically into something larger, readable in one go, is another.

That's why I suggested to go with DocBook "back then", as it allows you to do exactly what you're planing to do: write modular documentation.
CirTap wrote:
Frankly, I doubt that the current tools, J! 1.0.x(!) and Wiki, will be capable to handle this on the long run. IMHO, a decision has to be made in the very near future which way to go, or the idea of providing "the best documentation" will turn into a maintenance nightmare with doc-members writing parsers and such to do their job.
No matter what, I believe using DocBook provides more flexibility and a new possiblities to/for the project.


Have fun,
CirTap

_________________
You can have programs written fast, well, and cheap, but you only get to pick 2 ...

"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams


Top
 Profile  
 
PostPosted: Sat Aug 25, 2007 1:51 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Hi CirTap,

Yeah, "unit" is possible too.  I think "doc fragments" sounds about right.  As you say, they will be incomplete.

I had thought of using DocBook but the lack of a good open source WYSIWYG editor led me think of using other tools to create the fragments then translate them to DocBook using a bit of software.  I agree that DocBook would solve a lot of problems.

I'm now following up on your suggestion that we look at the vex editor.  Looking good so far.  Thanks.  :)

Regards,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Sat Aug 25, 2007 2:29 pm 
Joomla! Apprentice
Joomla! Apprentice

Joined: Tue Aug 07, 2007 5:53 pm
Posts: 38
Location: India
Hi!
I got your private message :) & like everyone I also have plan about template documentation ;) but still now I am not able to understand or may be the picture for this path of documentation not clear to me ??? yet I truly realize that all member are putting their up most effort but still I am not able to find any picture for path of documentation work is that already posted on any forum [even if for 1.0.x]?

_________________
Sukalyan Banga


Top
 Profile  
 
PostPosted: Sat Aug 25, 2007 9:05 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Hi jserver,

That's okay, I was expecting to have to do some explaining. :-)

The idea is that we break the documentation into small chunks, let's call them "fragments".  When we put the chunks together we get a complete document which could be a tutorial, or it could be some kind of online help, or anything really.  These different kinds of documents will use a lot of the same fragments but may assemble them in a different order and will apply different kinds of cross-referencing and will certainly use different styling.  But by writing the fragments in a way that is independent of the context in which they will be used we save ourselves a lot of work since we don't have to rewrite anything.  We can easily re-use the fragments in different documents.

To give you a flavour of what I'm thinking I've started setting up a "fragment repository" on the developer wiki.  You can find it here: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,tutorials:templates/.  I have organised the fragments according to type, so for example, if you click on the "Topics" link you will see a page of links to all the fragments of that type.  Of course, the list is nowhere near complete; I've only put up a few entries as examples.

What I think we need to do at this stage is produce an initial list of the fragments that need to be written.  This initial list won't be definitive and we'll adapt and extend it as time goes on, but it will be enough to get us started.  People can then pick fragments up and start working on them as they choose.  You see how breaking the documentation into fragments makes it easier for many people to work on the documentation simultaneously?  I know this method of working is new to most of us and I know there will be a learning curve to go up.  So please feel free to ask questions and I'll try to answer them.

Thanks,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Sun Aug 26, 2007 2:52 pm 
User avatar
Joomla! Apprentice
Joomla! Apprentice

Joined: Thu Aug 09, 2007 3:13 pm
Posts: 9
Location: East Providence, RI
Chris Davenport wrote:

The idea is that we break the documentation into small chunks, let's call them "fragments". 


I like the term "Chunks."  It's not really used for much and it's a bit more substantial than fragments.  Also fragment implies something that is incomplete, while "Chunk" is a small piece, but with an implication that it can stand somewhat on its own.  We could call them jchunks, which, if you pronounce the j as its sound and not it's letter name, sounds sort of like something falling into place.

As far as a list of topics, I am still learning about templates, but a "procedure" or "how to" jchunk for every step in the process to build one would be great!

We also need jchunks for the basic ideas a person has to understand before they can even start.

Starting an open source "DocBook" is certainly way out of scope, but this would be great advertising for them, and we may be able to work something out with them.  I don't know if anyone has any contacts with them, but either way, I would be happy to call them up and see what they can do.

Jennifer


Top
 Profile  
 
PostPosted: Sun Aug 26, 2007 3:10 pm 
User avatar
Joomla! Apprentice
Joomla! Apprentice

Joined: Thu Aug 09, 2007 3:13 pm
Posts: 9
Location: East Providence, RI
Also, we should watch the "Templates" section, and cull out of those questions issues that warrant specific mention in the documentation.  Maybe in a Question & Answer section. 

Some college or another didn't put any paths in until they saw which way the grass was worn.  It may not be the most aesthetic result, but it was certainly functional!

J


Top
 Profile  
 
PostPosted: Sun Aug 26, 2007 4:46 pm 
User avatar
Joomla! Explorer
Joomla! Explorer

Joined: Mon Dec 12, 2005 5:34 pm
Posts: 418
Hi,

among many, many documents, help screens, and who-knows-what-else. the User Documentation Team has written some excellent guides on writing "their" documents, available for download (PDF) at the UDT Documentation Guides help page.
Despite it's official focus on "User and Administrator" documents, one guide contains many useful hints, thoughts, and recommendations to write (more) consistant documents for Joomla!, so please download and read their Editorial Style Guide. In particular, I'd like to point each forthcomming tutorial author to the last chapter "Words to Watch", and it's goal to standardize the Joomla! terminology.

A very tiny excerpt (accepted vs. unaccepted words):
- Front-end vs. front-end, frontend
- Back-end vs. back-end, backend
- Extension(s) vs. extension(s)
- Plugin(s) vs. plugin(s)
- Module(s) vs module(s)
...


Happy reading,

CirTap

_________________
You can have programs written fast, well, and cheap, but you only get to pick 2 ...

"I love deadlines. I like the whooshing sound they make as they fly by." Douglas Adams


Top
 Profile  
 
PostPosted: Sun Aug 26, 2007 7:01 pm 
User avatar
Joomla! Apprentice
Joomla! Apprentice

Joined: Thu Aug 09, 2007 3:13 pm
Posts: 9
Location: East Providence, RI
Great Stuff!! Thanks! Jennifer


Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 6:51 am 
Joomla! Apprentice
Joomla! Apprentice

Joined: Mon Sep 04, 2006 1:49 pm
Posts: 24
Hi,

Great idea. I was taking a look at what you have set up Chris, it looks great but (there is always a but) arnt "procedures" and "processes" overlapping? Isnt "Proces" a combination of several modules?

Some ideas for definition:
-What are parameters?
-What is CSS
-What is WC3

Also I think the module "How to create a template package installation file" can be split up even further as it contains many more subjects like:
-What is an installation package (definition)
-How to create an xml install file (procedure)
...Followed by several modules of the type "procedures"

Regards, Ian

_________________
Are you pondering what I am pondering ... Pinky


Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 1:26 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Smithicus wrote:
Great idea. I was taking a look at what you have set up Chris, it looks great but (there is always a but) arnt "procedures" and "processes" overlapping? Isnt "Proces" a combination of several modules?

That's the spirit!  The list needs a HUGE amount of expansion.  I only put a few ideas up so people can see where I'm going.

Processes and procedures are very similar, differing only in how they are written.  A procedure is a series of steps that "you" must perform.  The language is imperative, for example: "Step 1: Do this; step 2: Do that; step 3: Do something else".  There is always an implied "you" doing something.  A process is more akin to a topic in that it is narrative rather than imperative.  For example: "The process includes the following steps: Step 1 is to take the widget and do this with it; step 2 is to assemble the gadget and apply it to the widget; step 3 is to package the widget assembly and affix the left-handed sprocket flange".  The difference is a bit subtle and it may be that we only produce one and not the other.  Time will tell.

Smithicus wrote:
Some ideas for definition:
-What are parameters?
-What is CSS
-What is WC3


That's good.  Get them coming!

Smithicus wrote:
Also I think the module "How to create a template package installation file" can be split up even further as it contains many more subjects like:
-What is an installation package (definition)
-How to create an xml install file (procedure)
...Followed by several modules of the type "procedures"

Yes, you're right.  Can you write up a list of these?  I think we need to get down to quite small modules/fragments/chunks for this to work properly.

Thanks Ian.

Regards,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 1:41 pm 
Joomla! Apprentice
Joomla! Apprentice

Joined: Mon Sep 04, 2006 1:49 pm
Posts: 24
Glad i could be of some help, will reply with more of my ideas tonight. I am "officially" working at a client now :)

Cheers,

Ian

_________________
Are you pondering what I am pondering ... Pinky


Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 4:39 pm 
Joomla! Apprentice
Joomla! Apprentice

Joined: Mon Sep 04, 2006 1:49 pm
Posts: 24
Well I thought up a few things partially thinking about subject "How to make a template package"

Definition:
• What is CSS
• What is PHP
• What is XML
• What is WC3
• What is HTML
• What is XHTML
• What is a parameter
• What are positions
• What is a template (not sure about this one it may be it bit to global)
• What is the typical template directory structure
• What is the typical XML install file structure
• What is a XML install file

Procedures (How to)
• How to make a XML install file (come to think about it, this maybe to global too :) )
• .. make parameters
• .. make positions
• .. place images
• .. use CSS

Troubleshooting (difficult category as the answer is often very broad)
• .. hmm will be thinking about this one..

What do you guys think.. lets get this show on the road :)

Cheers,

Ian

_________________
Are you pondering what I am pondering ... Pinky


Last edited by Smithicus on Mon Aug 27, 2007 4:42 pm, edited 1 time in total.

Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 6:11 pm 
User avatar
Joomla! Apprentice
Joomla! Apprentice

Joined: Thu Aug 09, 2007 3:13 pm
Posts: 9
Location: East Providence, RI
I think your topics are great!  Here's some feedback:

Smithicus wrote:
• What is a template (not sure about this one it may be it bit to global)


For lots of people/reasons we need this one so newcomers can orient themselves to the environment.  I just think we should break it up into smaller "jchunks"

  • What is the purpose of a Template?
  • When can you use Templates?
  • When should you use Templates?
  • Who do Templates help?
  • What are Templates, technically speaking?
  • What are the features of a Template?
  • etc.


Also on the trouble shooting issue:

Smithicus wrote:
Troubleshooting (difficult category as the answer is often very broad)
•  .. hmm will be thinking about this one..


I think we should just use raw data from the boards (real life questions from the forum) and see if we see certain patterns that we can organize into a trouble shooting or "common problems" section.  This could be a "lessons learned" component of the documentation that keeps growing ... we include the best sample lessons from what transpires in real life.

Just a thought.

Jennifer


Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 11:06 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Smithicus wrote:
• What is CSS
• What is PHP
• What is XML
• What is WC3
• What is HTML
• What is XHTML
• What is a parameter
• What are positions
• What is a template (not sure about this one it may be it bit to global)
• What is the typical template directory structure
• What is the typical XML install file structure
• What is a XML install file

I've added most of these to the wiki.

Smithicus wrote:
Procedures (How to)
• How to make a XML install file (come to think about it, this maybe to global too :) )
• .. make parameters
• .. make positions
• .. place images
• .. use CSS

I think some of these need breaking down.  "use CSS" in particular!  Topics for "How to use CSS to achieve xxx effect" maybe, although that might be better worded without referring to CSS, so simply "How to achieve xxx effect".  For example, "How to get rounded corners on modules".

Thanks,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Mon Aug 27, 2007 11:18 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
jmiddleton wrote:
  • When can you use Templates?
  • When should you use Templates?
  • Who do Templates help?

Hmm.  Not sure what you would achieve with these.  Templates are always used as they control output of both front-end and back-end.  And they help everyone.  Maybe something along these lines would be better:-

  • Why would you modify a template?
  • What can you achieve by modifying a template?

jmiddleton wrote:
I think we should just use raw data from the boards (real life questions from the forum) and see if we see certain patterns that we can organize into a trouble shooting or "common problems" section.  This could be a "lessons learned" component of the documentation that keeps growing ... we include the best sample lessons from what transpires in real life.

My thinking exactly.

Thanks,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Tue Aug 28, 2007 6:38 am 
Joomla! Apprentice
Joomla! Apprentice

Joined: Mon Sep 04, 2006 1:49 pm
Posts: 24
Thanks for the feedback. Will be posting again tonight (its working time atm :) ) But just a quick reaction:

Quote:
I think we should just use raw data from the boards (real life questions from the forum) and see if we see certain patterns that we can organize into a trouble shooting or "common problems" section.  This could be a "lessons learned" component of the documentation that keeps growing ... we include the best sample lessons from what transpires in real life.


Good idea!! It is going to be a challenge to keep the primairy questions/answers short and to the point but should be doable.

Chris do you have a documentation link on modulair documenting ? I would like to learn more about the subject.

Thx,

Ian

_________________
Are you pondering what I am pondering ... Pinky


Top
 Profile  
 
PostPosted: Tue Aug 28, 2007 10:54 am 
User avatar
Joomla! Apprentice
Joomla! Apprentice

Joined: Thu Aug 09, 2007 3:13 pm
Posts: 9
Location: East Providence, RI
Chris Davenport wrote:
Hmm.  Not sure what you would achieve with these.  Templates are always used as they control output of both front-end and back-end.  And they help everyone.  Maybe something along these lines would be better:-

  • Why would you modify a template?
  • What can you achieve by modifying a template?



That is both the advantage and disadvantage of not knowing anything at all.  What you wrote about Templates here is actually a big help.  What I was trying to get at (not very well) is a functional description of what they are, trying to [drive] down on Ian's bullet.  But surely we can help by answering questions like:

  • When/Why would you write your own template?
  • What do Templates allow you to control?

My impression (having never done anything) is that templates are both a visual/content control, but with this release have much more functionality.  We need to delineate the different purposes/uses of a template, or ways they can be used. 

Anyway, I will do my homework this weekend so I can be more useful.

Thanks!  Jennifer


Top
 Profile  
 
PostPosted: Tue Aug 28, 2007 7:15 pm 
Joomla! Apprentice
Joomla! Apprentice

Joined: Mon Sep 04, 2006 1:49 pm
Posts: 24
Quote:
My impression (having never done anything) is that templates are both a visual/content control, but with this release have much more functionality.  We need to delineate the different purposes/uses of a template, or ways they can be used. 


I agree, but I think you are referring to more global documentation subjects which will consist of the primairy modules. So to answer the question: "When should u use a template" (from the perspective of a graphic artisit) several primairy moules can be used, for example, "what is a template" (definition) and "how to make rounded corners" (procedure).

However I do feel that Jennifer makes a good point, the point I am getting is; be aware of what the document subjects are going to be. Only then will we be able to define and make usefull primairy modules, which eventually can be used in other documents.

Cheers,

Ian

_________________
Are you pondering what I am pondering ... Pinky


Last edited by Smithicus on Tue Aug 28, 2007 7:18 pm, edited 1 time in total.

Top
 Profile  
 
PostPosted: Tue Aug 28, 2007 9:37 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Smithicus wrote:
Chris do you have a documentation link on modulair documenting ? I would like to learn more about the subject.

I spent a good part of today looking for some references and I'm very glad I did, because I happened to come across DITA.  I'm sure this wasn't around last time I looked.  The internet is like that!

Anyway, here are some more or less useful references.  There's not much on the net, probably because most of the knowledge is locked away in corporate documentation teams.

This book is excellent and is the "bible" of modular documentation: http://www.amazon.com/Single-Sourcing-Building-Modular-Documentation/dp/0815514913
A few interesting snippets in here: http://www.idealliance.org/papers/xml20 ... er.htm#N88
DITA: http://en.wikipedia.org/wiki/DITA
DITA Storm: http://www.ditastorm.com

I've downloaded a copy of the DITA Storm editor and I'll look at getting it integrated into Joomla! when I have time.  It looks seriously useful.  However, let's not be deflected from working on the tutorial using the tools we already have.

Hope this helps.

Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Wed Aug 29, 2007 7:28 am 
Joomla! Apprentice
Joomla! Apprentice

Joined: Mon Sep 04, 2006 1:49 pm
Posts: 24
Super Chris!! Going to explore those links right now. By thw way John had some good ideas aswell regarding your point Jennifer

Quote:
How is this for a first kick at an outline?


Introduction:
- scope of this document
+ how to use
  - if you are in a hurry
  - working efficiently
  - issues important for the developer
  - issues important to the graphic designer
- making suggestions
- getting help

# Milestone 1

Quickstart:
- before we begin
- the essentail overview
- the quick and dirty
- css
- modules and components

# Milestone 2

For the Developer

# Milestone 3

For the Graphic Artist

# Milestone 4

Appendices;
- working on your template
- the two column with header and footer
- the three column with header and footer
- the developer
- the graphic designer
- joomla glossary
- usefull links and references

# Milestone 5


_________________
Are you pondering what I am pondering ... Pinky


Top
 Profile  
 
PostPosted: Wed Aug 29, 2007 1:31 pm 
User avatar
Joomla! Intern
Joomla! Intern

Joined: Fri Dec 30, 2005 2:32 am
Posts: 58
Is there going to be a certain amout of delegation done?  If the documentation is modular (good idea,btw)...I assume part of implementation is because you don't want people duplicating work.  Are we to have a task lisk or something of the like?  Also, what is the criteria for the writing?  If someone types up a module and it is horrendous...does the documentation team have to vote it out or what?

_________________
Rick Blalock
XiD


Top
 Profile  
 
PostPosted: Wed Aug 29, 2007 2:04 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Hi Rick,

Yes, I anticipate that different people will be working on different aspects of the tutorials at the same time.  Depending on the skills and interests that people have we can divide the work up in different ways, but it's still a little early to start doing that.  Different people can be working on different modules or groups of modules; but we may also have different people working on infrastructural needs such as the build process; others may be working on maintaining cross-referencing data or keeping the module repository in good order, or even developing new tools.  It just depends on what people are good at and what they want to do.

rblalock wrote:
If someone types up a module and it is horrendous...does the documentation team have to vote it out or what?

It's a bit like writing software; bad code gets eliminated by the community because others come along and rewrite it or improve it.  In the process the original author will hopefully have learned something and will write better code/text next time.  You see, there's an educational element to this effort too.  We will all be learning something as we go.  I'm not a professional writer, so that includes me.

Regards,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
PostPosted: Wed Aug 29, 2007 2:27 pm 
User avatar
Joomla! Apprentice
Joomla! Apprentice

Joined: Thu Aug 09, 2007 3:13 pm
Posts: 9
Location: East Providence, RI
Great links, Chris!  I am going to start reading up this weekend.  I have a lot to learn before I can be useful!  Jennifer


Top
 Profile  
 
PostPosted: Wed Aug 29, 2007 4:50 pm 
User avatar
Joomla! Intern
Joomla! Intern

Joined: Fri Dec 30, 2005 2:32 am
Posts: 58
Ok great.  So what's the next step?  Are we just posting ideas on a forum at the moment?  Do we have something more solidified to work from at the moment?  Is there a time frame for this?

_________________
Rick Blalock
XiD


Top
 Profile  
 
PostPosted: Wed Aug 29, 2007 5:43 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1382
Location: Shrewsbury, Shropshire, United Kingdom
Right now I'd like to get a comprehensive list of the topics that need to be covered.  It will get added to and amended as we go of course, but it will give us a starting point.  We'll have to annotate the list with information about what level to cast each topic at (eg. beginner, intermediate, advanced; and the same topic could be covered at more than one level) and for what audience.

One way to get this started is to think about "storyboarding" one or more tutorials (or even other types of document), then look at what modules/fragments we need to create.  We can build documents from the modules even if they are not finished and this will give us feedback on how we are doing.  It's like Joomla! itself: we have "nightly builds" which people can download, test and report problems with.  The developers fix the problems and we keep going round the loop.  That's open source development; what I'm after is "open source documentation" where we can all contribute to different parts of the cycle and different parts of the documentation and we have the tools to bring it all together.

Timeframe?  We'll I'd really like to see something pretty solid by the time 1.5 goes Stable, so not a lot of time, but hopefully enough. :-)

Regards,
Chris.

_________________
Chris Davenport - Joomla Production Leadership Team

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


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 96 posts ]  Go to page 1, 2, 3, 4  Next



Who is online

Users browsing this forum: No registered users and 6 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Jump to:  
Powered by phpBB® Forum Software © phpBB Group