Talk:Tutorials and documentation

From Pandora Wiki
Revision as of 20:29, 22 July 2010 by Cheese (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The change from just "tutorials" to "tutorials and documentation"

I thought I should justify why I renamed this page. This page was serving about the same purpose before, but not everything listed was a tutorial, so it wouldn't be obvious to look on this page for general information and having a separate page for documentation/general info doesn't seem necessary. What I'd like to see is this page become is sort of the next page people go to after looking through the user manual, a hub connecting users to all the information they want. For the most part the information is already out there, but it's often difficult to find.

Later on it would make sense to further break down the lists to "Basic tutorials/information" and "Advanced tutorials/information", so stuff most users would be interested in would be in basic while information only some people are interested in would be in advanced. But that's just my idea for organization, if anyone has a better one please share it.
--Cheese 07:11, 6 July 2010 (MEST)

Good idea. If necessary, this page can later become a wrapper for other more specific pages (and I think there will be several iterations of that process)
--Tsh 11:10, 6 July 2010 (MEST)

User/Dev split

I guess this is as good a place as any to raise this question. The wiki has grown up with the view of serving two groups of people, users and devs. It is also split into hardware and software views of the pandora. I am struggling with this then it comes to organising some of the information. Rather than split users i think it makes sense to partition information into the different levels of experience, dispense with the idea of a hardware vs software split (where does 'power' fit in that domain) and split hardware modding/fixing (extra leds, button fixes, nub replacement) off into a 5th area. We'd then end up with this sort of categorisation (and maybe group them together to start):

  • (User) Troubleshooting (brand new user can't power up)
  • (User) All users (menu managers, installing apps, day to day usage, games, installable apps, peripherals)
  • (User+) Advanced User (Linux guides, editing configs, SD boots, recovery, opkg, extend, toolchain, scripts, pnd packaging)
  • (AppDev) Application developer (pandora libraries - so more specific than user+)
  • (Firmware) OS and Firmware contributor (develop, debug, improve)
  • (Hardware) Modifications (case, nubs, leds. Anything involving soldering or a dremel)

I'd then put battery stuff under firmware, and there is a nicer split between user OS hacking, and OS stuff which is likely to be pushed into the GIT and back out as a new release. --Tsh 14:04, 16 July 2010 (MEST)

I like this idea, I was trying to come up with a better way to organize this stuff myself. The line between what's documentation and what's a tutorial isn't always clear enough. I don't know if you missed it, but on the Wiki TODO talk page I mentioned scrapping the InfoIndex page (well actually, merging it with Community Links) and then making tutorials and documentation the new information index. The page itself wouldn't really change it's purpose, it would just let us link to things which aren't quite tutorials or documentation, like a few of the orphaned pages. --Cheese 19:18, 16 July 2010 (MEST)
Troubleshooting seems more deserving of a separate FAQ type page rather than a list. Going to try to reorganize this page now. --Cheese 06:41, 17 July 2010 (MEST)
OK, you'll probably want to make some changes, but it's done. I put a link to Other resources which takes care of an orphaned page, but that page is actually so out of date it's nearly useless. The good stuff should can be moved to this page and that page removed. --Cheese 07:40, 17 July 2010 (MEST)
Troubleshooting gave me an idea for the wifi page, which is a 2nd level reference, pulling together everything we have on WiFi (plus we can keep direct links on this page where it makes sense, giving an easy route to a page for different people) --Tsh 13:05, 19 July 2010 (MEST)
Is the firmware section going to be development only stuff? If not, I can see a couple things which could be listed there. --Cheese 08:01, 20 July 2010 (MEST)
My view is that firmware is the package which gets pushed out by OpenPandora, so in terms of booting, it would include uBoot (the bootloader), but not the boot.txt files. It isn't the right area for 'how do I configure my filesystem/keymapping', but it is probably the right area for something like an alternative keyboard/nub driver. Firmware is more of a context than a component - so I think it is in the developer domain. What were you thinking of adding?--Tsh 12:55, 20 July 2010 (MEST)
I was thinking maybe the Extend utils page or the intro page. I do agree with you on the definition of firmware, but it seems like it's been unofficially defined by the community to also include the root filesystem. --Cheese 18:49, 20 July 2010 (MEST)
Extend is not firmware in my mind, it's a user topic (probably advanced, although that could change if it is stable). My point is we need a category that is what I class as firmware, making it too wide is just confusing. I think the community may have picked up some bad nomenclature from the wiki, so we could attempt to rescue that. Certainly the firmware topics can link to Extend where relevant because there is overlap in some areas. We could make the topic 'Firmware Development Topics' and see if there is a need for any other divisions. I did want really to avoid making the firmware section appear 'restricted', since there is scope for beta testing and such in there too.
Well, the community made the wiki in the first place so a few people must have started it and now it's spread. I don't really see it being reversible at this point, but I'll try to prevent it further through my editing. How about if I see an opportunity then I'll change text that's improperly calling the OS firmware? --Cheese 10:17, 22 July 2010 (MEST)
I did have a quick search, and didn't see much that seemed very wrong - just something to try and keep in mind for future edits really? --Tsh 12:01, 22 July 2010 (MEST)
Oh, maybe I just misunderstood your definition you posted earlier. So package released by OpenPandora we are calling firmware, does this include Angstrom? You went on to talk about uBoot and stuff and on regular laptops and desktops the OS is typically not called firmware so that's where my confusion came from them. I would consider the kernel to be firmware since, to my knowledge, it's pretty customized for the device. But I'd be reluctant to call the custom version of Angstrom firmware, even though it seems almost everyone else seems to think of it as firmware. Can you give me a couple more examples of what you wouldn't call firmware? --Cheese 20:29, 22 July 2010 (MEST)
I think we need a "set up" or "configuring" or maybe just an "intermediate" sort of section for some of the slightly more advanced, but not too advanced things. Or the topics which are aren't going to be of interest to everyone. For the pages describing how to set up things (like gps's), the linux guide, the USB reference page, stuff like that. Those are things I wouldn't consider too advanced and they're not going to be something every Pandora owner would want to look at. --Cheese 10:17, 22 July 2010 (MEST)
Agreed. Sort of difficult to name the category when it is nearly empty though. Maybe in depth guides. It needs to not sound scary, but shouldn't be in the most obvious 'all users' list. We might also want to give some thought to splitting this into several pages. I already added some global (gui/audio) pages for the all users list. In depth guides could be a similar page. Be careful of making this too optimised at this point though, we should get a few more wiki editors when shipments resume. --Tsh 12:01, 22 July 2010 (MEST)
Too optimized eh? I'll leave it as is for now until we get some more pages on the wiki and it starts become a problem. --Cheese 20:29, 22 July 2010 (MEST)