I made a frontend template based on the Admin default template in another thread.
I then started thinking about how well the new admin has been received by the community. Why not use the same concept for the documentation?
I did some tests, and you can see from the attached screenshot what I mean. (I just pasted some text into the last page. It should be much cleaner in the final version). As you can see I added comments as well.
Any opinion?
[attachment deleted by admin]
Template for documentation
-
westis
Re: Template for documentation
Hi jah!
Looks great. However, on the new site soon to be launched the documentation is integrated into the site layout. You can have a look at http://test.cmsmadesimple.org/Documentation.shtml
I have taken some of your ideas for the structure and added to the strucutre as it is now. What do you think? You are most welcome to have a look at the structure on the above-mentioned link and suggest changes/additions!
And I would be more than happy for any kind of contributions to the writing of the docs too, especially the installation part!
And by the way, the comments module is already added to the docs pages too, as well as a link the General Help forum if people have questions.
/westis
Looks great. However, on the new site soon to be launched the documentation is integrated into the site layout. You can have a look at http://test.cmsmadesimple.org/Documentation.shtml
I have taken some of your ideas for the structure and added to the strucutre as it is now. What do you think? You are most welcome to have a look at the structure on the above-mentioned link and suggest changes/additions!
And I would be more than happy for any kind of contributions to the writing of the docs too, especially the installation part!
And by the way, the comments module is already added to the docs pages too, as well as a link the General Help forum if people have questions.
/westis
Re: Template for documentation
Great that there will be a central place where all the documentation is kept. I hope that all the other helpful contributions that are now in the wiki and on the forum will have a place here and that therafter all those contributions will be deleleted so that all is well organized and will be replaced with a link to this central place. That way one has to search at only one place and there will no longer obsolete instructions and tips.
-
westis
Re: Template for documentation
Hans,
Yes, we'll try to gather useful info from the forums to answer common questions in the FAQ and Tips & Tricks sections on the new site, as well as to include it in the general docs.
As we are very few people working on this currently (I'm kind of the only one working with it on a regular basis...) I would be very thankful if some of you would like to collect links to useful posts in the forum that could be used for the docs!
You could post such links here on the Documentation forum and I'll have a loko and add it to the proper pages of teh documentation. I will browse the forums myself too of course, but time is limited to do both that and to write the documentation...
Thanks for your input!!
Yes, we'll try to gather useful info from the forums to answer common questions in the FAQ and Tips & Tricks sections on the new site, as well as to include it in the general docs.
As we are very few people working on this currently (I'm kind of the only one working with it on a regular basis...) I would be very thankful if some of you would like to collect links to useful posts in the forum that could be used for the docs!
You could post such links here on the Documentation forum and I'll have a loko and add it to the proper pages of teh documentation. I will browse the forums myself too of course, but time is limited to do both that and to write the documentation...
Thanks for your input!!
Re: Template for documentation
Hi Westis
as I am using different cms's for my sites and floow the discussions in the forums of those cms's, I know that (lack of) documentation is one of the core reasons for people to choose a particular cms or not.
I just recently discovered CMSMS and I like it very much, but also here: there are so many places you have to look for answers!
Therefore, as I like this script, i am very willing to post (on an irregular basis) tips and tricks and other useful stuff I discover here on the forum and other places so that you can decide to have it in the documentation or not.
What will hapen to the wiki then?
Hans
as I am using different cms's for my sites and floow the discussions in the forums of those cms's, I know that (lack of) documentation is one of the core reasons for people to choose a particular cms or not.
I just recently discovered CMSMS and I like it very much, but also here: there are so many places you have to look for answers!
Therefore, as I like this script, i am very willing to post (on an irregular basis) tips and tricks and other useful stuff I discover here on the forum and other places so that you can decide to have it in the documentation or not.
What will hapen to the wiki then?
Hans
-
westis
Re: Template for documentation
Fantastic! Thanks, Hans!
The Wiki will die a slow death, I suppose...
All the modules and tags/plugins will be on the main site as well. The idea with the Wiki was to have people add to the documentation in an easy way, but apparently it did not work as intended (I'm actually quite new to CMSMS myself).
I agree that proper documentation is very important when people select a CMS to use. Instructions on how to use it must be easily found in a structured way, although there will always be unanswered questions anyway... (which the forum is great for). But to find ALL the info by yourself or in the forum can be a bit time-consuming...
The Wiki will die a slow death, I suppose...
All the modules and tags/plugins will be on the main site as well. The idea with the Wiki was to have people add to the documentation in an easy way, but apparently it did not work as intended (I'm actually quite new to CMSMS myself).I agree that proper documentation is very important when people select a CMS to use. Instructions on how to use it must be easily found in a structured way, although there will always be unanswered questions anyway... (which the forum is great for). But to find ALL the info by yourself or in the forum can be a bit time-consuming...
Re: Template for documentation
Hi Westis,
I'm impressed with what you have accomplished with the documentation so far. Keep going! The test pages look very good. I didn't know about them. Getting all the information in one place will be a huge improvement.
When it comes to structure, I see that it is very much in line with the admin menu structure. When we describe each menu item it is becoming a reference book for CMSMS. Nothing wrong with that, but I feel that something is missing.
If I was a newcomer, I would also like to se a more process-oriented documentation telling me what to do first, next .....etc. This would include installation, customization, administration and usage.
Then potential users of CMSMS would understand the philosophy of the product by reading this overview.
The process oriented documentation should link into the reference documentation whenever it comes to a topic that needs more details. This was the intention of my Quick-Start menu item.
I don't think this is in conflict with the existing structure, but this overview should be very easy to find. Maybe something like this could be added to the existing structure.
I'll try to contribute to the documentation if I find some time.
Jon
I'm impressed with what you have accomplished with the documentation so far. Keep going! The test pages look very good. I didn't know about them. Getting all the information in one place will be a huge improvement.
When it comes to structure, I see that it is very much in line with the admin menu structure. When we describe each menu item it is becoming a reference book for CMSMS. Nothing wrong with that, but I feel that something is missing.
If I was a newcomer, I would also like to se a more process-oriented documentation telling me what to do first, next .....etc. This would include installation, customization, administration and usage.
Then potential users of CMSMS would understand the philosophy of the product by reading this overview.
The process oriented documentation should link into the reference documentation whenever it comes to a topic that needs more details. This was the intention of my Quick-Start menu item.
I don't think this is in conflict with the existing structure, but this overview should be very easy to find. Maybe something like this could be added to the existing structure.
I'll try to contribute to the documentation if I find some time.
Jon
-
ratzavlatz
Re: Template for documentation
Maybe a tutorial is a good idea?
Just a step by step guide on installing, creating a simple template and installing/implementing some modules/tags into the created template.
Wish I had the time to do this though:S
Just a step by step guide on installing, creating a simple template and installing/implementing some modules/tags into the created template.
Wish I had the time to do this though:S
-
westis
Re: Template for documentation
Jah & ratzavlatz,
I appreciate your input!!
Yes, I agree with both of you that a more step-by-step how-to approach is the best, with a reference guide as just that, a reference to what each menu item in the admin panel holds.
My idea with the Getting Started section is similar to Jah's idea with the Quick Start section, the first basic steps how to create your first site with CMSMS (adding/editing content, adding news, styling your site with templates & CSS). I think that's basically all that is necessary in that section, as I think Installation needs a section on its own. Anyone who wants to set up his/her own site with CMSMS needs to install it anyway and for those who will just use CMSMS to add content and news they only need to read the Getting Started section.
What would you think if we add one section after Getting Started, where we continue with the same step-by-step approach as in the Getting Started section, but for more advanced use, like templates in detail, modules, users & groups etc.? Actually, this was what I intended to use the Admin Panel section for, since the information basically will be the same anyway...
It's also good if we don't put too many sections there, which might confuse the user who won't know where to read. My suggestion is the followig general structure:
1. Installation (requirements, the installation process, optional settings, troubleshooting)
2. Getting Started (adding/editing pages, adding news, introduction to templates & stylesheets. This would then also be the user's guide for those who are not administering the site)
3. Administrator's Guide (how to's for the administrator, continues from Getting Started)
4. Reference (going through all menu items in the admin panel and explain what they are about)
5. Extensions (Manuals to modules & tags/plugins)
6. Tips & Tricks (how to accomplish some useful stuff, tips from users)
7. Glossary of Terms (common terms explained, klind of a reference guide too but with a list of common terms and what they mean)
8. Developer's Guide (for the ambitious user who would like to contribute to the development of CMSMS: describing the API, how to create modules & tags, making modifications in the core etc.)
But are these too many sections?!? And the problem with the reference guide is that most of the info that is there will already have been covered in the Administrator's Guide. We really need to decide on a structure now to be able to fill it with content as soon as possible! Because these things have been discussed in and out since long before I joined here....
Basically, there are are two approaches:
It seems to me like most people, including myself, prefer the first approach. But when Matt Jason H set up the structure for the new handbook (http://docs.cmsmadesimple.org) he tried to combine this approach with a walkthrough of the admin.
So, to conclude, I guess the discussion is mainly about what will follow after the Getting Started section:
1. Should we keep the Reference Guide/Admin Panel walkthrough (which includes step-by-step instructions too)?
2. Should we rather use an Administrator's Guide/tutorial?
3. Should we use both 1 & 2, which may include a lot of overlapping information?
Opinions?
I appreciate your input!!
Yes, I agree with both of you that a more step-by-step how-to approach is the best, with a reference guide as just that, a reference to what each menu item in the admin panel holds.
My idea with the Getting Started section is similar to Jah's idea with the Quick Start section, the first basic steps how to create your first site with CMSMS (adding/editing content, adding news, styling your site with templates & CSS). I think that's basically all that is necessary in that section, as I think Installation needs a section on its own. Anyone who wants to set up his/her own site with CMSMS needs to install it anyway and for those who will just use CMSMS to add content and news they only need to read the Getting Started section.
What would you think if we add one section after Getting Started, where we continue with the same step-by-step approach as in the Getting Started section, but for more advanced use, like templates in detail, modules, users & groups etc.? Actually, this was what I intended to use the Admin Panel section for, since the information basically will be the same anyway...
It's also good if we don't put too many sections there, which might confuse the user who won't know where to read. My suggestion is the followig general structure:
1. Installation (requirements, the installation process, optional settings, troubleshooting)
2. Getting Started (adding/editing pages, adding news, introduction to templates & stylesheets. This would then also be the user's guide for those who are not administering the site)
3. Administrator's Guide (how to's for the administrator, continues from Getting Started)
4. Reference (going through all menu items in the admin panel and explain what they are about)
5. Extensions (Manuals to modules & tags/plugins)
6. Tips & Tricks (how to accomplish some useful stuff, tips from users)
7. Glossary of Terms (common terms explained, klind of a reference guide too but with a list of common terms and what they mean)
8. Developer's Guide (for the ambitious user who would like to contribute to the development of CMSMS: describing the API, how to create modules & tags, making modifications in the core etc.)
But are these too many sections?!? And the problem with the reference guide is that most of the info that is there will already have been covered in the Administrator's Guide. We really need to decide on a structure now to be able to fill it with content as soon as possible! Because these things have been discussed in and out since long before I joined here....
Basically, there are are two approaches:
- Task-oriented step-by-step approach
- Content-oriented approach, walkthrough of the admin menu, descirbing what's in each menu
It seems to me like most people, including myself, prefer the first approach. But when Matt Jason H set up the structure for the new handbook (http://docs.cmsmadesimple.org) he tried to combine this approach with a walkthrough of the admin.
So, to conclude, I guess the discussion is mainly about what will follow after the Getting Started section:
1. Should we keep the Reference Guide/Admin Panel walkthrough (which includes step-by-step instructions too)?
2. Should we rather use an Administrator's Guide/tutorial?
3. Should we use both 1 & 2, which may include a lot of overlapping information?
Opinions?
Re: Template for documentation
I'm aware that there has been too long discussions, so I think we should focus on providing content, rather than structure now.
Reconsidering my last reply, I see that the question is more related to "who do we write the getting started section for"? My first thought was that this was for the web-designer rather than the user of the system. Maybe we should provide information for both by forcing the reader to select between "I am a user" and "I am a web-designer"?
I don't think these getting started sections should be too long. Rather, they could be a kind of map from where it is possible to step into the detailed documentation along the way.
This way overlap would not be a problem.
Reconsidering my last reply, I see that the question is more related to "who do we write the getting started section for"? My first thought was that this was for the web-designer rather than the user of the system. Maybe we should provide information for both by forcing the reader to select between "I am a user" and "I am a web-designer"?
I don't think these getting started sections should be too long. Rather, they could be a kind of map from where it is possible to step into the detailed documentation along the way.
This way overlap would not be a problem.
-
westis
Re: Template for documentation
Good point! Is web-designer a better word to use than administrator? I mean the administrator might not necessarily see himself as a web-designer, but more of a developer.jah wrote: Maybe we should provide information for both by forcing the reader to select between "I am a user" and "I am a web-designer"?
But then again, to complicate matters even more, there could be the user (just updating content & news), the web-designer (making templates & stylesheets) and the administrator (administering users, adding modules etc.).
Agree! What should be in the Getting Started section is just what's enough to get a site up. Then those who are interested can dig into the details.jah wrote: I don't think these getting started sections should be too long. Rather, they could be a kind of map from where it is possible to step into the detailed documentation along the way.
Do you think that with this approach it is enough with a Getting Started section followed by the Admin Panel walkthrough/Reference Guide?
Re: Template for documentation
I think we must assume that people understand that they can play different roles.
I'm not very much into what the names of the roles are. I'm sure others can answer that. Maybe we have the three roles that you describe? This also has to do with the philosophy of how CMSMS is used.
Lets assume a new module is installed. As I see it, this can involve the Web-designer, the Administrator and the User roles.
It would be nice to have some opinions on this.
I'm not very much into what the names of the roles are. I'm sure others can answer that. Maybe we have the three roles that you describe? This also has to do with the philosophy of how CMSMS is used.
Lets assume a new module is installed. As I see it, this can involve the Web-designer, the Administrator and the User roles.
It would be nice to have some opinions on this.
Yes, that would be fine with me.westis wrote: Do you think that with this approach it is enough with a Getting Started section followed by the Admin Panel walkthrough/Reference Guide?
