Structure of the XBMC Online Manual (wiki)

[neeltje57]

Hello everyone,

I am using XBMC for many years (2 modded xbox's) and now i am using it on a PC with a 46Inch LCD. I am a big fan of XBMC and was afraid it would die together with the XBOX-hardware. I am glad i was wrong. I wanted to contribute to this community and put in a few hours already with updating the manual.

I visited the manual a few times before but, although there was a lot of information in it, i got lost each time because i could not recognize the structure in it. I thought that must be easier to do and i made a table of contents (toc) on each page.

I probably made a mistake by not holding this against the team members (that is what rwparris told me in the #xbmc channel, i should do).

So here i am. I think i already did a bang up job, but that is ofcourse me. Some pages are locked so they don't have the same look and feel with an easy toc on the right side. If you like this approach please unlock the pages or give me the proper authority to edit them.

There is still a lot of work to do because the manual is wrapped around the old xbox, no offence, and there are more flavours these days. Some stuff is outdated, double, or in the wrong place when you use a toc.

Please give me your gentle opinion.

neeltje57

[jmarshall]

We appreciate the effort, but yes, before doing widespread changes, please discuss first - we have a team of people who work on and have plans for the manual and thus discussion prior to doing massive reorganisation is useful, if only to avoid stepping on toes.

I personally don't see the need for the TOC of the entire manual on the right, but I can see how it might help some - particularly if the whole thing was organised in a more cohesive manner.

For instance, I think we still need a "local" TOC on many of the longer pages, and a consistent style in this respect is better than anything.

Perhaps you could outline exactly how you see the entire manual organisation and look being done, and we can then get a discussion going from there.

Cheers,
Jonathan

[neeltje57]

Yes, i understand, me bad . I did not know how this all worked, but here i am now. On the other hand when you start talking about something everyone has to say something and in the end nothing will change ever ...

The idea is simple though. If you don't have a toc or otherwise a straightforwarded pdf-like manual you get lost, especially when you are new. And new-ones are the target of a manual.

So the toc must be something like:
-Introduction
-Installation
-User manual
-Advanced
-Development
-Appendixes

Beside that, a more explicit division, when appropriate, for the different flavours there are (linux, Mac, Windows, Live). When you see the current toc i made, without knowing anything about xbmc, you already get an idea about how it is structured, i think. and browsing the manual is much easier. Maybe not for the experienced users who know where to look but i am pretty sure for the newbies.

Thank you for your gentle response,

neeltje57

[sho]

I agree, to the uninitiated, it's probably a huge multi-dimensional spider web.
About the only thing I miss from the old Wacko Wiki (shiver) was the convention of always showing where you came from, that is partly solved by your approach.
(With Mediawiki you can use the "what links here" as a substitute, but the likelyhood of these being used by the average casual reader are minimal).

The layout is surely all over the place, the oldest pages show that they were moved from the old wiki, restructuring ideas and help are more than welcome

But I also noticed that in some instances you removed the page toc while adding the inline main toc, was that intentional? Because I am not sure that is a good way going forward.

While I appreciate your work and input, please run things by us before undertaking anything major (or even minor to begin with).
I am very sporadically on IRC, so this would be the preferred venue.

PS What pages are locked besides the "front" pages?

[althekiller]

Originally Posted by sho

I agree, to the uninitiated, it's probably a huge multi-dimensional spider web.

I must still be uninitiated

TheUni has a pretty good plan for what the wiki needs to be IMO (I may have influenced him just a wee bit ). Maybe the three of you should get together on IRC and get on the same page before taking things further?

[rwparris2]

Agree with all:
-A global TOC is useful, but the one you've added now is large and still daunting imo (a collapsible tree menu would be awesome)

-The page-spefic TOC is nearly always useful and shouldn't be removed

-What I've seen of theuni's changes were well done. Perhaps a wiki-team is in order if the plan is a proper restructuring.

EDIT: This could help with not getting lost: http://www.mediawiki.org/wiki/Extension:BreadCrumbs2
EDIT2: this would actually be even better: http://www.mediawiki.org/wiki/Extension:TreeAndMenu

[theuni]

I spent a few nights hacking away at the front page to get some organization, but was quickly overburdened by the size of the task. Surely some help would be appreciated.

I've setup a temp wiki on my own server to do some big changes and get some ideas. I originally had the intention of redoing the whole thing, but I quickly realized that wouldn't be possible in my lifetime.

IMO, if we changed the front page to something sane, eliminated the xbox references, and changed the sections to something more user-centric (focusing on someone who has no idea how xbmc works, rather than hammering them with code and xml) it would go a long way.

neeltje57, if you're interested, send me a pm and we'll go from there. We need to keep the big changes off the live wiki until they can be reviewd by the rest of the team.

Thanks for your interest. Trust me, it's a bigger project than you realize :-)

TheUni

[neeltje57]

Thank you all for your responses. I agree to the approach of bringing big changes in this forum, this is the last time i apologize for being bad . But i was invited to update the wiki on the first page of that same wiki. Maybe i took it too literal.

-I also noticed that in the bigger pages the local toc was very handy and i was already putting it back.

-The locked pages i found so far:
http://xbmc.org/wiki/?title=Introduction
http://xbmc.org/wiki/?title=Team_XBMC_and_Others
http://xbmc.org/wiki/?title=Frequently_Asked_Questions
http://xbmc.org/wiki/?title=Troubleshooting
http://xbmc.org/wiki/?title=HOW-TO_w...ugins_for_XBMC
http://xbmc.org/wiki/?title=Disclaimer
http://xbmc.org/wiki/?title=Thanks

-I think i do release how much work it is to make a nice looking manual. It will probably take me a few months or even more, if you let me. I though have no intention of changing the real content of the pages i don't even know what it is about. I am more a user, no developer. But even the pages i don't understand must have the same look and feel.

-The approach of Breadcrumbs or the TreeAndMenu look very promissing, i will try that out (don't worry, no one will see it before you all agree, haha) and come back to this place later.

-theuni, I will come back to this place before i make more big changes, and i am more than glad with help from this forum. I don't know how far you are with a mirror wiki, i think it is well possible to do this in a live environment, then you don't miss the newest updates too.

-Beside the current wiki, i am sure that there is a lot of information in this forum too, which should be brought into the wiki. There are also lost pages in the wiki, which should be brought back, i assume.

Thank you all so far, i have to rush now to go to work.

neeltje57.

[rwparris2]

> http://xbmc.org/wiki/?title=HOW-TO_w...ugins_for_XBMC
your toc is already in there, definitely not locked

[althekiller]

Most of those pages shouldn't even be in the wiki IMO but on the webpage. The info in them is reasonably static and the users have business changing them. FAQ and the plugins thing aside of course.