Tell me what documentation you want and I'll send an exclusive umbraco t-shirt

Monday, December 22, 2008 by Administrator

Everybody talks about the need of documentation and 2008 has indeed been a year where it has improved a lot. But I want to work more on documentation in 2009 and I want to know what you need. So here's a pretty good offer:

Mail me your top three of articles you want or wished was there when you started. You'll need to be very specific (a how to build a website or how to make a Facebook clone won't do!) and you should also tell me why you need it to help me get a better understanding.

In return there's not only a very good chance that I'll make sure it gets written, but the five best/most thorough ideas will also get the exclusive super cool Umbraco T-shirt from CodeGarden 08 (I got sizes from medium to extra large - I'll ship world wide).

Mail me at nh AT umbraco [.], add doc2tshirt as the subject.

18 comment(s) for “Tell me what documentation you want and I'll send an exclusive umbraco t-shirt”

Jamei Says:
22 Dec 08 @ 10:07 GMT+1
I really wish there was a good book on umbraco like the other popular CMS systems out there.

I tried umbraco a lot of times and I'm using it for simple sites, but every time i tried to get more involved in the core umbraco framework I gave up because of a lack in documentation.
Jan Aagaard Says:
22 Dec 08 @ 11:06 GMT+1
I think Umbraco has a steep leaning curve, so what I would like to see is some documentation that explains how it works underneeth. Specifically:

==The Structure of the Interface

I never understood the diffenrentiation between 'Settings' and 'Developer', so this got me of a very bad start upon my first test run of Umbraco. So I would like an article that take you through the creation of a document type, a template and some content, explaining the concepts along the way. Examples: The document type describes what the document contains, but nothing about the layout. A document type is not constrained to be a web page, but could also be part of a page. The content navigation navigates the semantic structure of the website, and not the presentation of the webpages.

==The XSLT Macros

Even though I'm able to use and program simple XLST macros, I have yet to completely understand the XML that lies behind them. I would like an explanation based on an simple example like the breadcrumb macro. Show the full XML of the currentPage variable, how the XPath grabs specific parts of it, and what the variables contain throughout the build of the navigation path. Why is the [ ] necessary? What does actually match? Could you have reached the same result in different ways?

==Specific Examples

I would like to see some more, specific examples, that are ready for copy-n-paste fast solutions to common problems. Make different navigation XLST, that produce the typical horizontal and vertical navigation types. Let the output be easy to skin by following something like Listamatic's syntax (http://css.maxdesign.com.au/listamatic/). Show how you could create the standard 'employee' web page. An alphabetical index of all the web pages. The same index, but in two or three columns. A simple 'top 5 pages' gadget. A sidebar that easy to reuse across pages.
Warren Buckley Says:
23 Dec 08 @ 09:28 GMT+1
Hiya all.
OK my documentation requests would be as follows.

1 - A document explaining ALL the umbraco.library methods with real life examples on how they could be used. (From an XSLT perspective)

For example in V4 I have seen addJquery() how does it work, what version of jQuery does it add and so forth?

Warren :)
Ruben Verborgh Says:
24 Dec 08 @ 12:09 GMT+1
Hi Niels,

Great initiative!

I think we should do some thinking about documentation. We would need some documentation standard form, guidelines, a checklist for a correct documentation document... I've seen some pretty good examples and I think we have the right community to create this.

Ruben
Richard Soeteman Says:
24 Dec 08 @ 10:10 GMT+1
Hi Niels,

I think documentation needs to be in the form of a book. Suggested Title "Implementing websites with Umbraco" ;-) which explains how to implement a website in Umbraco and takes a new Umbraco user from no knowledge at all to the level that he or she can implement a basic website. I think this needs to cover the topics: Umbraco Interface, how to install, Usermanagement Document Types, Templating, Macro's, the packages concept, boost, Nitro's and maybe a little bit of .NET Code.

After this book I also think there needs to be a book that covers the more advanced topics such as API documentation, how to implement certain interfaces, Dashboard controls, custom datatypes, xslt Extensions.

I personally think the main focus should be on the first book. This will get new Umbraco users up to speed. This is also the group that is complaing the most.

Other popular CMS systems allready have certain books and I don't like their systems but I think that they are more popular because you can buy a book that explains the system.

Richard
Elson - Brazil Says:
24 Dec 08 @ 03:03 GMT+1
I suggest that you do documentation as:

How to do a site using umbraco CMS end-to-end.

Basic and directioned documentation to beginners.

Thanks!
Simon Justesen Says:
25 Dec 08 @ 01:25 GMT+1
Jan Aagaard:

Many of the subjects you list is already covered in the online documentation -> the 'books' section:

**Document Types:**
http://www.umbraco.org/documentation/books/document-types-explained

**Templates:**
http://www.umbraco.org/documentation/books/templates-explained

**XSLT Basics:**
http://www.umbraco.org/documentation/books/xslt-basics
Samir Varteji Says:
26 Dec 08 @ 08:06 GMT+1
Hi,

I am new to Umbraco. I want to prepare one web site with Multi Country and with in each country there is multi language.

I have prepared tree structure for each country and user will redirected to home page based on selected country.

Now my problem is how to implement multi lingual functionality with in each country.

Can you please provide any documentation or Book on Multi Country / Multi Language web site structures..

I will be very thank full to you...
Biagio Paruolo Says:
26 Dec 08 @ 11:42 GMT+1
Hi,

I wish a good documentation for developping new datatypes.

Happy Christmas!
Sakai Says:
29 Dec 08 @ 05:19 GMT+1
- Docs for integrating LiveID and OpenID authentication methods.
Wendall Mosemann Says:
06 Jan 09 @ 06:40 GMT+1
I'd really like to see some documentation on the following:

1. How to integrate a DEV and PRODUCTION version of Umbraco. For example, How can I keep a DEV and PROD site in sync [what pieces (db?, umbraco.config, etc) do I need to move?] and how do I move that new custom media type from DEV to PROD without re-creating it?

2. How to backup Umbraco's various pieces.

a) Backup of entire site
b) Backup of content only
c) Where is each piece of Umbraco stored. I'm still not clear where the content data is stored/sync'ed (database or umbraco.config file)?

3. Documentation that walks through how to configure a site to use SSL for authenticating users.

4. From a perspective of someone who doesn't know .net architecture, how do I make a custom widget that interfaces with a current system (say an Oracle database of employee data) and integrate it with Umbraco.

5. Best Practices/Lesson's learned.
I'd like to hear of others who have tried things and then found that there was a better way to do it.

These are some of the "how do I..." questions we've asked as we've started looking at Umbraco...
Dirk Says:
09 Jan 09 @ 01:55 GMT+1
It would be nice to have/see some sort of umbraco Page Lifecycle document. How does umbraco render pages from the initial request to the last bit received!

And don't suggest to add ?umbdebugshowtrace=true

/Dirk
Finn Says:
09 Jan 09 @ 03:43 GMT+1
All the above requests for documentation cover the developing of at site.

In my world developing is concentrated on few persons, whereas writers and editors is a lot of people +40.

So documentation for creating new nodes, using the media section, insert pictures, insert macros, using the property tab (publish, unpublish), renaming nodes and so on would also be an asset to Umbraco documentation.
Jay Greasley Says:
11 Jan 09 @ 03:07 GMT+1
This is purely personal preference but hopefully would be useful for others.

1. I agree with Dirk, an overview of the Umbraco life cycle would be very useful. Go through all the touchpoints so we can get a real feel for what resources are used and when.

2. A best practice for backing up and restoring live sites. (Possibly out there already).

3. A developers guide on how to check out code, set up A VS environment, build and deploy a new version.

For me these are important topics for a Systems Integrator to be able to offer their customer a professional service as well as an excellent CMS.

Keep up the good work Niels, Per, core team and Community.
Rick Gibson Says:
18 Jan 09 @ 09:46 GMT+1
Ok, I am swallowing my pride here, but I want an easier way to install Umbraco. I know there are probably people thinking that it is easy already. I am running XP Pro VS 2008 and I installed umbraco 4. I found some docs explaining how to install umbraco 4 on Vista. I think there is something simple I missed, but I can't help thinking that the install process can be made more simple. If any knows of what I might be missing please resond - I didn't install the AJAX because I am using 3.5. Also, I didn't setup IIS since I am using the web server software that comes with Visual Studio. Looking forward to digging in. Rick
Ricardo Says:
18 Feb 09 @ 06:15 GMT+1
Hi Niels,
We are looking 17 posts so far but no t-shirt winners list yet :P
Thanks to worry about documentation!
santosh Says:
25 Feb 09 @ 01:16 GMT+1
Documentation along with implementation of the features would be greatful to provide an in depth view of the api.
Rajeevan Says:
24 May 11 @ 04:42 GMT+1
Complete documentation which will help any body to begin with Umbraco based on a Sample website( of Medium complexity) development with Umbraco (without using starter kit).
This should Include
- Installation and configuration manually
- Setting up the development environment
- Step by Step guide for each task in the web site creation process
- Deployment of the website
- Steps to update the live website (incremental)

There are documentations available for different steps. But a detailed documentation based on a website creation will help any body to adapt Umbraco very fast.

-Raj