|
Author
|
Message
|
|
Bård Farstad
|
Thursday 12 June 2003 10:29:15 am
We had a meeting at eZ systems today about the new versions of eZ publish. One of the points we were discussing was the documentation. The documentation is the weakest point of eZ publish, that's a fact. We want to improve this and have scheduled time for it in the 3.2 development cycle. We think that the community documentation here really works, it has grown really fast and it's really simple to update. What we were discussing was to merge the current documentation and the community documentation here at ez.no. This would make it simple to update the documentation and it would always be available. We would need to extend the community documentation a bit and create exports to make the manual available offline ( atleast html and pdf ). We could even use the translation feature of eZ publish to translate the documentation ( if there are any interest for that ). Any thoughts about that? Do you think it's a good idèa? --bård
Documentation: http://ez.no/doc
|
|
Paul Borgermans
|
Thursday 12 June 2003 10:52:02 am
Yes, if we can continue to update it ourselves! (merging ez and community docs). Maybe use a an extra xml attribute "community contributed" which we can use if you do not think ez and us should edit the same content (but hey, what are versions for?). --paul
eZ Publish, eZ Find, Solr expert consulting and training
http://twitter.com/paulborgermans
|
|
Bård Farstad
|
Thursday 12 June 2003 11:06:06 am
We thought that it could be a shared effort. When we make a new feature we will add it to the docs and people can update it when they test features and see missing information from the docs the same way as the community doc. We would need to work on the structure of the documentation though. Any suggestions for structure? -bård
Documentation: http://ez.no/doc
|
|
Paul Forsyth
|
Thursday 12 June 2003 2:13:20 pm
One suggestion for structure would be to use comments for each piece of documentation much like they use it on php.net. In this way we may have docs describing some feature and users can add examples of usage in different situations. However, for large docs this may be problematic... Hmmm! I know there are some places on ez.no where comments are enabled but they have yet to be enabled for contributed docs. paul
|
|
Bruce Morrison
|
Thursday 12 June 2003 4:09:46 pm
I'm currently writing some documentation for in house use. One issue that I am having is that the documentation is scattered between the SDK, Manual, Community and forums. I'm tiring to pull it together into something coherent. The current outline I have is
Introduction
Terminology
URL meaning
+Different parts and what they mean.
+Nice URLS and issues associated with these
Content Types
Sections
+Layout
+Relation to Roles / Permissions
Related Objects
+When to use related objects and when to use child objects
Configuration
+How the configuration files work
Templates
+How the system works
++page layout
++classes
++attributes
++xml elements
+Overrides
++section
++class
++node
++view
+Functions
+Operators
+Common Solutions
Permissions
+Anonymous user
+Roles
+Different views depending on the user logged in. Of course there is also Workflow,Shop and probably many more items that need addressing, but I believe that this is a good start that covers the basics. I think that designIT would be happy to share the end results.
Cheers
Bruce
designIT
My Blog: http://www.stuffandcontent.com/
Follow me on twitter: http://twitter.com/brucemorrison
Consolidated eZ Publish Feed : http://friendfeed.com/rooms/ez-publish
|
|
Bård Farstad
|
Thursday 12 June 2003 11:55:58 pm
I would like to merge a structure like that with the current community doc. Could we start off with top levels like this?
Introduction
Installation
Technology - Basics
Day to day usage ( how to use the admin )
How-Tos
+ Classes
+ Objects
+ Datatypes
+ Templates
+ Permission
+ ...
Typical problems and solutions
Step by step guide ( aka tutorials )
Optimization
Reference doc ( automatically generated API doc ) Mabye we can simplify this a bit? --bård
Documentation: http://ez.no/doc
|
|
Björn Dieding@xrow.de
|
Friday 13 June 2003 12:24:03 am
All of this sounds good. I just see 1 points where we should really take care of. When it comes to the point where the community updates the official documentation, we will see much more redundant Text(Information). How are you gonna handle this? Will there be a primary contact that watches over the docs?
ALso...
What about chm files... I love their search funtionality. I want them too :-)
Looking for a new job? http://www.xrow.com/xrow-GmbH/Jobs
Looking for hosting? http://hostingezpublish.com
-----------------------------------------------------------------------------
GMT +01:00 Hannover, Germany
Web: http://www.xrow.com/
|
|
Bård Farstad
|
Friday 13 June 2003 12:44:03 am
We would need to create a documentation group which is responsible for tidying up the documentation if it gets bloated. eZ systems would of course take the responsibility here, but I think we would get the best result if we would combine our efforts. I think we should have the documentation editable by every registered user, then we should add aditional permissions to a documentation group. This groups should consist of eZ people and people from the community. The group could e.g. restructure documents, revert versions and do diffing etc.. eZ systems would then export the documentation and bundle it with the eZ publish distribution on every release. Regarding the CFM format, yes, this would be nice. We should create an export function for this as well. --bård
Documentation: http://ez.no/doc
|
|
Gabriel Ambuehl
|
Friday 13 June 2003 2:55:01 am
I think Paul is right. Something along the lines of PHP.net manual comments would be very nice. Maybe make it possible for users to just add new nodes below a given feature describing real world implementations, problems and caveats encountered etc.
Visit http://triligon.org
|
|
Ekkehard Dörre
|
Friday 13 June 2003 9:38:15 am
Structure:
[...]
Day to day usage ( how to use the admin )
Development:
+ Classes
- How To build classes
- Tutorial "My first Class"
- more Information (Functions)
- more more Information (Link to relating SDK page)
+ Objects
[...] Keep everything for one Point in one Place, the Theme is the heart no the Documentation Form (HowTo, Tutorial,...) Greetings ekke
http://www.coolscreen.de - Over 40 years of certified eZ Publish know-how: http://www.cjw-network.com
CJW Newsletter: http://projects.ez.no/cjw_newsletter - http://cjw-network.com/en/ez-publ...w-newsletter-multi-channel-marketing
|
|
Paul Borgermans
|
Friday 13 June 2003 11:18:00 am
Dear Bård,
The structure you propose is from a developer point of view addressing the needs of different audiences simultaneously. I think at least you should put something like "Start here" to the top which guides the different groups of end-users. This should contain:
- definitions of what is a CMS from the ezp point of view,
- the fact that ez publish is also a powerful develoment framework (like you do slightly in the presentations on ezp by explaining the architecture)
- !!what to do to according to different *scenarios* that correspond to the the profiles of end users!! From what I learned over the past 1.5 years on these forums and the needs at various organisations, these *scenarios* can be reduced to: - building a dynamic web site where few people can post articles and similar content, but where lots of others can "participate" through forum-like things (including comments, annotations, ratings, ...). This is where the 2.x series are strong out of the box (and covering probably 60% of ezp end-user needs) and in this way you provide a transition for 2.x users too. You may want to include some basic templates to start from (the demo does not fulfill this goal, they are OK for developers who want to learn ezp3 without docs). - building intranets/extranets for small and large organisations where you explain the flexibility of the templates, classes, sections, rolse, .... Here you (or we) should provide the pointers to specific and in-depth documentation on templates and the possibilities of the other components illustrated with "real-life" examples. Examples are very important and should contain ready to use as well as more abstracted ways of explaining functionality - advanced development: going beyond the traditional use of CMS and intranet/extranet sites. Here you should explain the priciples and architecture behind the various kernel modules, how to build your own modules, how to keep ezp releases in sync with your own development, .. Here some of the ezp community members need to help you since you may not be fully aware of the potential applications of ezp3. In one sentence: "The docs should reflect the needs of end-users in a layered fashion; from simple to complex uses and from basic to very powerful features of the various ezp3 components." In this way you can both provide an answer to current needs of end-users and let them even discover solutions to problems they were not even aware of. Enjoy your weekend and thanks again for your hard work! --paul
eZ Publish, eZ Find, Solr expert consulting and training
http://twitter.com/paulborgermans
|
|
Marco Zinn
|
Friday 13 June 2003 12:05:34 pm
Hey there, I'm happy, that the ezCrew makes an effort to set up a good documentation and adresses the upcomming "problems" right away (Comments, Versions...).
My 2 cents:
- Write the documentation for the audience, not for yourself. That means: Do a structure, which adresses the needs of the audience and that does not necessarily reflect the architecture of the software.
- I liked the audience (target group) for the ez2 documentation:
1. Server Admins (Requirements for and setting up OS, Web Server, DB, PHP, ezPublish.
2. Desginers (Concepts of Sections, Templates, Rendering engine, complete Template language with lots of tutorials)
3. End Users (Should be small by now. Describe handling the OE (you want to sell this!), then describe the XML tags, when Server has no OE).
- For each of these 3 manuals, I suggest this rough meta-structure
1. Who is the audience for this paper (a good title will help, too ;) ) ?
2. What will be handled in the manual. What will not be handled (cross-reference to other docs)
3. Show, what terms and facts a user should know, before continuing ("Required knowledge"). For those, who don't know this: Describe the most common thing/abbriviations. Give (online) references for in-depth docu.
4. Write how to do the "common tasks" for the audience of THIS paper.
5. List and answer FAQs for that audience Besides that docu, you should keep on writing the marketing stuff (presentations and "commercials"). Speaking about that: I like your new grafix on the website. This said, i must tell you, that I'm unhappy, that some important parts of the ezP2(!) docu have not been finished. Mainly, I miss a complete docu of all the site.ini settings (article module's missing!!!) and the "Tech manuals". Marco
Marco
http://www.hyperroad-design.com
|
|
Bruce Morrison
|
Tuesday 24 June 2003 3:14:12 pm
Has eZ considered hiring a technical writer to produce or at least organise the documentation?
My Blog: http://www.stuffandcontent.com/
Follow me on twitter: http://twitter.com/brucemorrison
Consolidated eZ Publish Feed : http://friendfeed.com/rooms/ez-publish
|