Documentation hackfest in Barcelona
 

Hi all,

We're planning a documentation hackefest in Barcelona as part of the
Barcelona weekend in December (2.5 short weeks away), and you are all
active in community documentation efforts (or have been in the past).

Anyone interested in attending for the documentation hackfest should
register ASAP indicating that you wish to attend so that we can gauge
numbers. We're looking forward to a productive session defining the
needs of developer documentation in Maemo, and working together to
improve the existing documentation as well over the weekend - maybe the
Intro pages for maemo.org?

Some people from Lionbridge, a company contracted by Nokia to work on docs, will be co-ordinating the developer docs workshop and they have some objectives that they would like to see us accomplish at the event.

Cheers,
Dave.

Re: Documentation hackfest in Barcelona
 

Something that this documentation workshop could kick off is the TOC of the Maemo 6 Developer Guide.

http://wiki.maemo.org/Documentation/...eveloper_Guide is ok, but it can be done better in Harmattan. For instance, we will have different tools for application developers and platform developers, therefore it makes sense to have also a clear division between documentation of the platform itself, what can application developers do with it an then the documentation of the own developer tools.

The Harmattan SDK releases are approaching and it would be good to know what are the expectations and the best way to organize the draft documentation that will come with them.

Re: Documentation hackfest in Barcelona
 

I'm going to be there for this. Right now, I'm thinking about the 'tree' for the Maemo beginners' wiki, to make it fully 'average Joe' friendly.

Looking forward to looking at some of the new documents, too.

Re: Documentation hackfest in Barcelona
 

I've brought this up in a couple of threads in respect to user group meetups and larger events: what do we have in the way of Maemo whitepapers? It would be nice to have something well-formatted, with a consistent theme across a series (if more than one, as I would assume).

The same goes for glossy full-color flyers that can be distributed at such assemblies. I don't mind doing design work on the latter.

Re: Documentation hackfest in Barcelona
 

Hi,

I'm one of the people co-ordinating the Barcelona documentation event. Glad to see that you have already made good suggestions on the topics to be covered in Barcelona. Keep them coming!
And I agree, the event is a good opportunity for us to take a look at some of the existing documentation together and think about how it could be improved.

Mary and I are eager to receive your comments and improvement ideas concerning the existing Maemo documentation. We want to get a thorough picture of how the existing Maemo documentation meets the needs of readers as well as contributors.


Cheers,
Titta

Re: Documentation hackfest in Barcelona
 

Hi Titta,

(and welcome to t.m.o!)

You might want to look at this conversation we had about the Bugzilla. There were some useful concrete suggestions in there for making it more 'end-user friendly'. I feel we need to do the same with the 'maemo basics' or 'new users' materials: create documentation that doesn't assume so much. :)

Without dividing the community between techies and non-techies, we do need to have some stuff that is aimed at the user who picks up a maemo device just because it's a really good device, without knowing much about OSS etc. I do recognise that the technical experts also need documents that are technically clear, too.

Re: Documentation hackfest in Barcelona
 

Thanks, Kathy! Clarity and simplicity are definitely the cornerstones of any good technical documentation. Good documentation is to-the-point and gives the right amount to information - not too much but not too little, either.

One thing to remember is that many of the Maemo documentation readers are not native English speakers. Using clear and unambiguous language prevents misunderstandings and open up the content to a wider audience.

Even though our main focus in Barcelona will be on the technically oriented people, making the existing material more user-friendly would certainly benefit everyone.

Re: Documentation hackfest in Barcelona
 

I have just seen http://wiki.maemo.org/Maemo-Barcelon.../Documentation

Great! Please have a look to the other subpages in order to follow some pattern (that now still doesn't exist) ;) Who coordinates, main topics, participants with links to their profiles, etc.

Can you please polish the Documentation entry at http://wiki.maemo.org/Maemo-Barcelon...#Documentation following the example of the previous entries?

And finally, please help feeding the general agenda. Probably useful for yourselves to see when your sessions fit best: http://wiki.maemo.org/Maemo-Barcelon...Weekend/Agenda

Re: Documentation hackfest in Barcelona
 

Hi,

By polish, you mean reduce to one sentence?

OK! Will do.

Dave.

Re: Documentation hackfest in Barcelona
 

Thanks, everyone, for a great weekend! We got some really good work done, too.

Sorry I didn't have time to say good bye to all of you.. Mary finally came and dragged me from Citilab to the airport. :)

Those of you who took pictures of our post-it notes - it would be great if you could send them to me?

Hope you got back home safely!

Titta

Re: Documentation hackfest in Barcelona
 

Hi Titta, I've posted a shot of the post it notes to Mary. If you want, I can pm it to you.

Thanks should go to you and Mary for facilitating the workshops. And for all the fun.

I agree about not getting the chance to say goodbye to people properly: courtesy of the way people left to get home, I felt I didn't manage to say 'goodbye' to most people. We should have had a docs team group hug. ;)

Re: Documentation hackfest in Barcelona
 

Please post the results of your work. It would be ironic if your work went undocumented... ;)

Re: Documentation hackfest in Barcelona
 

I plan to post a 'Maemo n00b's story' blog of my first ever Maemo event, though it won't have full details of the work. I think DNeary probably needs to post a proper digest of the achievements. I'll drop a link in here when my blog is updated.

Re: Documentation hackfest in Barcelona
 

Ok... it's longer than even I expected. The first 1500 words are here. No, I haven't aggregated my blog before you ask. I haven't been blogging on Maemo long enough and anyway I'm too tired to worry about putting my pic on my .org profile tonight! :p

Re: Documentation hackfest in Barcelona
 

Indeed, it was really a great weekend. Big thanks to everybody involved!

Re: Documentation hackfest in Barcelona
 

Pics or GeneralAntilles wasn't there! ;)

Re: Documentation hackfest in Barcelona
 

Dave got a really nice one of Kathy and me being productive. It may be up on his photostream. I'm on WiFi at 34,000' on the last leg of my trip, so I may just check.

Aha! I've also got a bunch of docs pics up on my photostream and most everything available should be tagged with maebar.

Re: Documentation hackfest in Barcelona
 

Really enjoyed the blog :) - nicely done - can't wait to see the documentation :)

Re: Documentation hackfest in Barcelona
 

I'm specially impatient to know your thoughts about the Harmattan Developer Guide ToC, if any.

Good to see the Long Weekend was worth!

Re: Documentation hackfest in Barcelona
 

I don't have the link to what the folks looking at the Developer Guide for Harmattan created - I'll see if I can get it. They generated a 'contents' page for their ideal guide. I'll post about my part in the work later (that page is half written) and then a third entry of my general reflections.

I could seriously use some tips on getting good pics from the n900 anyone up for creating that for the wiki? Oh... and how to ftp from the n900 would help, too.

Re: Documentation hackfest in Barcelona
 

Maybe this is a little of topic here. But one thing that I have been struggling with during the pasts weeks is that Qt documentation for Fremantle is quite confusing after the change from 4.5 community supported, to 4.6 technical previews from nokia.
a lot of things simply do not make sense now or are a little bit confusing.
It was discussed in the documentation track in the Barcelona long weekend? ( I attended the programming one )
If not discussed, what do you think about the idea?

Regards

Re: Documentation hackfest in Barcelona
 

Some of you were eager to see the Maemo Developer Guide TOC created during the Barcelona long weekend. Attached, the TOC as a TXT file. Any comments on the TOC are greatly appreciated!

Re: Documentation hackfest in Barcelona
 

Ok, I've finally completed it all. My travelogue of the trip to Barcelona in full on my LJ is available.

Part one: Thursday and Friday are here. (And the pics are live now, but they are big images)

Part two: Saturday and Sunday are here.

Part three: Reflective Meanderings here.

Somehow, I can't capture how amazing it was in words, however hard I try. Not in words they get typed, anyway. When they work out a way to send enthusiasm and energy over tcp/ip, let me know.

Re: Documentation hackfest in Barcelona
 

1) I'd love to have documents like this posted on a public wiki page so that there is read/write access for the community... Not all of the documentation types went to Barcelona... :)

2) Lego?

Re: Documentation hackfest in Barcelona
 

Lego = building blocks.

And I agree about putting the doc somewhere public. :)

Re: Documentation hackfest in Barcelona
 

:D :D I know that! I've got heaps of the stuff.

It just doesn't have a lot of context around it, it isn't entirely clear what that word "Lego" means on a line by itself...

Re: Documentation hackfest in Barcelona
 

Thank your for the TOC!

The TOC deserves a wiki page, sure. Well, it will BE a wiki page just like the Maemo 6 Developer Guide it's bootstrapping. And a separate thread for discussion in the Development forum.

I must say that after a first quick look I honestly disagree :) but before starting the review it would be good to hear the rationale and some opinions from developers. In the new thread.

Re: Documentation hackfest in Barcelona
 

My bad! I failed to provide any information as to the context and the idea behind this exercise.

The TOC was created from scratch, which means that the Fremantle version was not used as a basis. The idea was to think of the kind of information that a new Maemo developer would need in order to start developing applications on top of Maemo. The idea was not to create a detailed and ready structure for Harmattan, but more to get a first draft of ideal content that would be needed.

The next step is to continue the planning in Wiki + in a new Talk thread. I'll be posting the links here as soon as I've found appropriate places for them. :)

Re: Documentation hackfest in Barcelona
 

Hey everyone! Big thanks from me too, for the excellent input and ideas and for your enthusiasm. It was a great introduction to community working, plus one of the finer doc architecture workshops I've ever participated in.

Good company at dinners was highly appreciated too, especially that very small intimate dinner of 19 people we had on Saturday =8-)

Re: Documentation hackfest in Barcelona
 

Hi Titta!

I have put my notes from the session in the wiki, and it would be great if we could also gather your notes, and the notes/recollections of Ryan, Kathy, David, Daniel and others who took part.

I also moved the TOC to its own page: http://wiki.maemo.org/Developer_Guide_table_of_contents It should get linked from somewhere other than the documentation summit page. Not sure where...

Thanks,
Dave.

Re: Documentation hackfest in Barcelona
 

Could we have a link to that please, Dave? The only reference to the weekend I can find is the planning/agenda page.

Thanks!

Re: Documentation hackfest in Barcelona
 

Great, I have started a new thread to discuss the ToC of the Maemo 6 Developer Guide: http://talk.maemo.org/showthread.php?p=421680

Re: Documentation hackfest in Barcelona
 

http://wiki.maemo.org/Maemo-Barcelon.../Documentation

Cheers,
Dave.

Re: Documentation hackfest in Barcelona
 

There are some very familiar faces behind yerga in this video.

Re: Documentation hackfest in Barcelona
 

Oh yes. That was where we got set up, and then they came and filmed with us as a background... and promptly asked us to keep our voices down. We debated livening up the video by having a fight or making out on the table, but settled for just lowering our voices.

Good video though - they've done an excellent job.