+- Kodi Community Forum (https://forum.kodi.tv)
+-- Forum: Support (https://forum.kodi.tv/forumdisplay.php?fid=33)
+--- Forum: General Support (https://forum.kodi.tv/forumdisplay.php?fid=111)
+---- Forum: OS independent / Other (https://forum.kodi.tv/forumdisplay.php?fid=228)
+---- Thread: XBMC Official Online Manual (Wiki) (/showthread.php?tid=3528)
- los93sol - 2005-07-18
just wanted to let you know that i got it and am going to go through it tomorrow. looks promising...i started writing a little and scrapped what i had because i felt like some of it was explaining things that are so elementary it would become overwhelmingly large. i guess since we are breaking the information down into seperate manuals for different things it will be alright, but i think it's best if we figure it all out and revise how pages are laid out while we are at it so it fits the new style we want in the manual. i agree with you that we should start with the user's guide and then outline the next manual and tackle it so we aren't overwhelming ourselves with too much and it will be easier to keep it all sorted.
by the way, do you write manuals for a living or something? just asking because of your comments about deadlines previously in this thread.
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.regards,
los93sol
ps. please forgive my poorly formed sentences tonight, got stabbed in the hand earlier today so typing is not so comfortable at the moment
hifty:
- kzr1y2 - 2005-07-18
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
- bobst - 2006-04-07
i can help to translate manual of xbmc software?
- kzr1y2 - 2006-04-09
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
- Dankula - 2006-04-15
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.
- Dankula - 2006-04-17
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...
- kzr1y2 - 2006-04-17
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
- pike - 2006-04-17
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 ?
- Dankula - 2006-04-18
may i suggest that we modify the main page of the wikki? as we all know, contributions to the new manual have been minimal, and i feel as though we need to draw more attention to it.
the new manual, although far from complete, has progressed from its infancy to its childhood. although it still has many incomplete sections, those that are complete are superior to the old one, with current screenshots and more up to date and better organized information.
i propose that from now until the new manual is complete, we list the table of contents for both manuals side by side. this will make it easier to choose between the two for information and hopefully garner more support for the rewrite.
this is how i envision it looking, albeit with a little more polish.
what do we think, yay or nay?
- sCAPe - 2006-04-18
looks good dankula
this way we see easily what is already done and has to be done in the new manual!
- jmarshall - 2006-04-18
go for it
- Dankula - 2006-04-19
lord marshall has spoken, and his faithful minions carried out the deed.
- kzr1y2 - 2006-04-19
good kick-off ...
cheers,
kz
- Dankula - 2006-06-28
ok...many moons later...here it is. still needs a bit of work, but it's a step in the right direction.
the new new new online manual...live it, love it.
- sho - 2007-04-06
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.