Posts: 357
Joined: Nov 2004
Reputation:
0
the user's guide content will feel elementary; the idea of the user guide is to review the product and "coach" the user on how to use the features that exist and what they are typically used for.
once the outline is up, we need to get some feedback on it before entering content. once we get a general consensus, i'll put in a first pass at the introduction section. that should help set the overall tone of the ug. once the tone is established, contributors will find it easier to place content. i figure the "team" will look at the content, make editing changes, and adjust it as necessary.
i agree with you that we need to establish some "standards"; we also need to involve the developers as they have to be aware that when they change the gui or functionality it impacts the documentation. we can look to possibly create a "bucket" that developers can use to provide us information on the changes they made to a feature; we can then take that content and "massage" it into the guide.
initially, we need an overall consensus on:
- default xbmc settings
- default skin
- options offered/displayed per feature
this will go also go a long way towards qa & debugging efforts.
you're doing fine as far the sentencing goes ... specially with a stabbed hand an all ;-) i would think we want to be as professional as possible when putting the content and guides together but still have fun in the process of doing that.
there will be typos and grammar mistakes along the way ... kinda like debugging - ya know ...
oh, and yes, i work in all aspect of the it industry (documentation, qa, design, development, and deployment).
cheers,
kz
Posts: 17
Joined: Aug 2005
Reputation:
0
bobst
Junior Member
Posts: 17
i can help to translate manual of xbmc software?
Posts: 357
Joined: Nov 2004
Reputation:
0
hi pike and loto,
i think we can get a user's guide and possibly a customization guide for xbmc 2.0. on that note, i personally find the online web version difficult to navigate - guess i'm old fashioned ;-)
i love the idea that the wikki manual is online ... i most certainly am not suggesting we do away with it by any means.
to that end, what do you think about the following strategy:
- create an ms word document (chapter per/file); i can set up a standardized template to bring the final files together into a book
- convert the final product to web format (wikki - not quite sure how)
- convert the final product to .pdf
to proceed, we also need a "buy-in" from the xbmc team pertaining to the following:
- official skin (project mayem iii right?)
- official contents of the xbmc build (t3ch bare bones?)
- a source repository location to check-in/check-out the ms word document files (sourceforge cvs?)
lastly, i feel we need to break the documentation into three types of books:
- the user's guide (similar to manual that comes with a tv, vcr, etc.)
- the customization guide (for the more advanced folks)
- the compilation/programming guide (for the users that know how to build a cvs of xbmc, etc.)
cheers,
kz
Posts: 177
Joined: May 2005
Reputation:
0
i'd love to jump in the ring and give a hand with the printable version. i agree that there should be more than one guide as said above. it seems like a much more professional approach to documentation, and that is what xbmc needs. i also like the idea of having a simple manual for those that are less adventurous and just want to get it up and running.
for the record, there is a 'bucket' where the devs keep up to date on all changed to the functionality--the changelog.
has a solution been found as far as a cvs or similar solution for the word versions of the content? i agree that something of that nature is essential to this project being successful. i think that the best route would be to create a separate folder within the existing cvs and grant dev access to just that portion for those of us working on the documentation, for obvious reasons. have we gotten any feedback from the pm's regarding this possibility?
kzr1y2, it seems as though you've got a great plan of attack laid out for this project, and i'd love to chip in in any way i can. let me know what i can do.
Always ensure that you read the faq and the online manual before posting support requests.
This post was brought to you by the fine folks at the Heineken Brewing Company.
Posts: 177
Joined: May 2005
Reputation:
0
on another note...don't want to seem as though i'm rambling here though...is there any reason that the new wikki seems to have come to a halt? it doesn't appear that there have been any substantial progress in the v2 manual for almost a month! i don't want to beat anyone up here, but if the devs went for a solid month without commiting any meaningful changes to cvs, the entire xbmc community would be demanding their heads!
i realize that i'm as guilty as the next guy...my first changes to the manual were today and i've been avidly using xbmc for two years, but we must appreciate the advantages of good documentation, and contribute to it. think of all of the 'stupid' questions that get answered daily in the support forum. if the program was properly documented, i'm sure that we'd have to field a hell of a lot less of them.
also, at present, kzr1y2 is trying to spearhead an effort to put together a print/pdf version of the manual. if we don't give him a solid online manual with a standardized format, what does he have to work with? are we expecting him to write half of the thing himself?
xbmc is nearing its first solid point release in over a year and a half. in order to be considered a viable product, it needs to be properly documented, open source or not.
the developers, pms, skinners, and everyone else involved in the project have made their contributions to the project. it's time we pull our weight and do the same.
on a side note, i understand that there's been an issue with the hosting for the images for the new manual. has that been resolved? have we been given space on xboxmediacenter.com to host them? if so, then what is the procedure for utilizing it? if not, do we need space? i would be more than happy to provide hosting for the project. i'll just need a ballpark on what sort of storage / bandwidth requirements that it'll require so that i know what to get.
ok, ok...i'm rambling, i know...
Always ensure that you read the faq and the online manual before posting support requests.
This post was brought to you by the fine folks at the Heineken Brewing Company.
Posts: 357
Joined: Nov 2004
Reputation:
0
hi dankula,
haven't had any other responses as of yet; i'm willing to start but i was hoping for more "buy-in" from the project folks as to the value of what i'm proposing.
cheers,
kz
Posts: 5,008
Joined: Sep 2003
Reputation:
30
pike
Team Kodi Admin
Posts: 5,008
hi there. im sorry but i don't have much time to invest in manual myself, but i did inform loto of this thread, i was kinda hoping he was interrested. loto hasn't contacted you has he ?
Posts: 177
Joined: May 2005
Reputation:
0
lord marshall has spoken, and his faithful minions carried out the deed.
Always ensure that you read the faq and the online manual before posting support requests.
This post was brought to you by the fine folks at the Heineken Brewing Company.
Posts: 357
Joined: Nov 2004
Reputation:
0
good kick-off ...
cheers,
kz
Posts: 4,132
Joined: May 2004
Reputation:
4
sho
Team-XBMC Member
Posts: 4,132
Maybe it´s time to unsticky this thread, and create a new one for the Wiki manual?
Also I think it would be worth considering if we should have 2 versions of the manuals online.
One for the stable version (2.x?), where the documentation is also stable and according to that version, and then another for the daily builds, which evolve organicly and often look and behave nothing like the manual describes.
i am good with organization, but don't have a whole lot of experience writing manuals so i am thinking we need a place to chat about this outside the threads here to devise a plan and set some standards for writing and adding to the manual for future expansion.
hifty:
