Improving the wiki? - page 2 - General Chat - CHDK Forum
« previous next »
Pages: 1 [2] 3 4   Go Down

Improving the wiki?

  • 32 Replies
  • 11770 Views
*

Offline mattkime

  • ****
  • 299
Re: Improving the wiki?
« Reply #10 on: 29 / November / 2009, 20:31:01 »
Advertisements
reyalp - I'll take into consideration everything you've said.

I think we've hit on a point of contention with the build server. We need to be able to point new users to stable builds. Currently, we can only point them to the auto build server. If someone is new to chdk, i don't want to point them to a build and then say "...but it might or might not work 'cause people are changing things constantly so you might want to go to the forum". If we're concerned that recent builds will explode, then we need to point to something stable until we're certain about recent changes.

To summarize - caveats don't mean a thing. There's no room for weasel words. I'm pointing user to the auto build server until i'm provided with something more stable.
Logged
*

Offline an0n

  • ***
  • 152
Re: Improving the wiki?
« Reply #11 on: 29 / November / 2009, 20:36:23 »
Dear mattkime,

You are taking on an heroic, monumental task, and you are applauded, but do you realise how much? I have a fair
amount of free time and I could possibly give some to the project. For some time now I have wanted to convert the
"Quick Start User Guide" to the Wiki, but where would it go? amongst the clutter it would probably go unnoticed,
I consider it the most up to date (English) information for usage, so publishing on the Wiki could be useful. As
reyalp said, features are not that well documented and what we have we rely on for information in the manuals, the
trick is to coax the people with the knowledge to spend more of their (limited) time to help with extended documentation,
not necessarily text book equivalent, but a little more extended.

IMO you are correct to start with the Home page, it is just a lot of clutter, trying to say too much, surely there would be
someone amongst us who is adept at graphic design to refurbish it, perhaps suggest some design parameters and see
what is forthcoming, if nothing suitable then you would have the clean slate. :)

A suggestion - To make an Historical section and just dump all the old stuff in there for future sorting, that would
clean up quite a bit. If you give a few days for responses to the idea and there is little, then I would say you have a
green light to go ahead, most will wish you good luck and hope you can accomplish the job.

Cheers and best wishes,
An0n.
Logged
A720IS.
*

Offline mattkime

  • ****
  • 299
Re: Improving the wiki?
« Reply #12 on: 29 / November / 2009, 21:19:32 »
>>You are taking on an heroic, monumental task

that is why i'm recommending that i take bite sized pieces on a regular basis and see where i get with it. i'm not taking on heroic tasks but a series of bite sized steps. its the only way to move forward.

i've noticed your quick start guide although i haven't looked at it yet. if it meets the goals set by its title, it should certainly be front and center. I should take a look at it shortly since a natural starting point is easing the entry point for newbies. i'd appreciate it if you have advice on merging its contents with the wiki. i certainly don't want this to be about my ideas, i want it to be about moving forward. if people have ideas on how o approach certain parts of the wiki then i'm more than willing to back off.
Logged
*

Offline reyalp

  • ******
  • 14126
Re: Improving the wiki?
« Reply #13 on: 29 / November / 2009, 21:32:36 »
Quote from: an0n on 29 / November / 2009, 20:36:23
Dear mattkime,

You are taking on an heroic, monumental task, and you are applauded, but do you realise how much? I have a fair amount of free time and I could possibly give some to the project. For some time now I have wanted to convert the "Quick Start User Guide" to the Wiki, but where would it go?
Kill all the existing manuals with fire, and replace them with your content (well, coordinate the attack with mattkime if he's going to work on them too). Really! It's a wiki, nothing is lost forever. You can move the old stuff to a historical section if people want, but the wiki already keeps every version.
Quote
As reyalp said, features are not that well documented and what we have we rely on for information in the manuals, the trick is to coax the people with the knowledge to spend more of their (limited) time to help with extended documentation, not necessarily text book equivalent, but a little more extended.
If things were organized in a more manageable fashion, it would be a lot easier for people to spend a little time correcting one or two things IMO.
Quote
IMO you are correct to start with the Home page, it is just a lot of clutter, trying to say too much
Agreed.

Lots of out of date, inaccurate "information" is not really more useful than a much smaller amount of more accurate information. There has been a tendency to add and add without ever removing anything, I guess because people are worried causing offense or losing something slightly useful, but this can't go on forever.

BTW, if my last post sounded negative on this project, that was not the intention. If anyone is willing to devote time to this, it would be great.
Quote from: mattkime on 29 / November / 2009, 20:31:01
"...but it might or might not work 'cause people are changing things constantly so you might want to go to the forum".

If we're concerned that recent builds will explode, then we need to point to something stable until we're certain about recent changes.
I prefer an unpleasant fact to something that is untrue. That quote exactly describes the current situation, and because of the fact we have almost 100 different variants and no way to test them systematically, it will always be true if anyone is doing any serious development that affects cameras they don't own. Pretending that the autobuilds are stable will not do anyone any favors. We've done fairly well so far, but they do blow up on occasion, and sometimes no one notices a particular camera or feature has been broken for weeks or months.
Quote
To summarize - caveats don't mean a thing. There's no room for weasel words. I'm pointing user to the auto build server until i'm provided with something more stable.
Which is exactly why I want to go back to having a stable branch.
Logged
Don't forget what the H stands for.
*

Offline mattkime

  • ****
  • 299
Re: Improving the wiki?
« Reply #14 on: 29 / November / 2009, 22:05:40 »
>>I prefer an unpleasant fact to something that is untrue.

I agree with this. The problem is that new users aren't able to properly digest this information. Unless we want an intermediate page which warns users that they may damage their camera then nothing else is going to get their attention. Further, if we have such a page, it will discourage new users. At least a few people wouldn't want to take the risk.

unfortunately i see the break down as
- warning which scares off users
- no warning, perhaps some users will find chdk broken when they try to use it. (is it possible they'd break their camera?)

Lets figure out how we can move forward on this with the understanding that the worst outcome is to point a user to a revision that may break their camera.

>>Which is exactly why I want to go back to having a stable branch.

how do we make that happen?

---

edit - I also wanted to apologize in advance if some find my tone abrasive. I don't intend to be, but I must be direct about the issues i'm trying to fix.
« Last Edit: 29 / November / 2009, 22:22:16 by mattkime »
Logged
*

Offline reyalp

  • ******
  • 14126
Re: Improving the wiki?
« Reply #15 on: 29 / November / 2009, 22:53:02 »
Quote from: mattkime on 29 / November / 2009, 22:05:40
unfortunately i see the break down as
- warning which scares off users
- no warning, perhaps some users will find chdk broken when they try to use it. (is it possible they'd break their camera?)
I don't see scaring some users off as a huge deal. CHDK is about being useful for the people who find it useful, not getting the most users. The warning doesn't need to be extreme. It just needs to say something like "This is a development snapshot. We try to keep it working well enough for every day use, but sometimes things break. If you have trouble, visit the forum."

It's pretty unlikely that any CHDK build would damage someones camera, but if there ever was a bug that did that somehow, it would hit the autobuilds first. The much greater "risk" is they will go and download the autobuild, and they will happen to get one that is broken in some way. Then they will come here and say "But the wiki said this is this version is stable!". Or they will just assume that it doesn't work and give up.
Quote
>>Which is exactly why I want to go back to having a stable branch.

how do we make that happen?
Would need someone to host builds for it. I don't know if hacki would want to host another set or not. This could either be another autobuild on a particular branch, or something manually updated. There's also some question of when stuff gets moved from unstable to stable.
Logged
Don't forget what the H stands for.
*

Offline mattkime

  • ****
  • 299
Re: Improving the wiki?
« Reply #16 on: 01 / December / 2009, 07:22:24 »
I took a look at the quick start guide and while it has a lot of great info for new users, it doesn't include install directions. Does anyone know if we have good install directions somewhere? Looking at the current wiki info, users need to go to at least 3-4 wiki pages to get chdk running. i'd like to get it all on to one.
« Last Edit: 01 / December / 2009, 07:29:29 by mattkime »
Logged
*

Offline fe50

  • ******
  • 3152
  • IXUS50 & 860, SX10 Star WARs-Star RAWs
    • fe50
Re: Improving the wiki?
« Reply #17 on: 01 / December / 2009, 08:26:38 »
Logged
*

Offline mattkime

  • ****
  • 299
Re: Improving the wiki?
« Reply #18 on: 01 / December / 2009, 10:39:24 »
fe50 - thanks! thats the sort of material i want to start with.

It really does look like we have plenty of material, it just needs to be curated. If I'm lucky, I can do this without writing anything at all!
Logged
*

Offline reyalp

  • ******
  • 14126
Re: Improving the wiki?
« Reply #19 on: 02 / December / 2009, 18:15:58 »
Some thoughts on the scripting sections:
http://chdk.wikia.com/wiki/LUA/LUA_Reference
http://chdk.wikia.com/wiki/LUA
http://chdk.wikia.com/wiki/UBASIC/TutorialScratchpad
http://chdk.wikia.com/wiki/CHDK_firmware_usage/MoreBest#New_uBASIC_and_LUA_Scripting_Commands.21
http://chdk.wikia.com/wiki/UBASIC/uBASIC_syntax

Having full examples inline with the function description (as in LUA_Reference for example) makes things less readable and bloats the page. Usage examples on a reference page should be no more than 3-4 lines. Larger examples should be links to another page, or a file download. Ideally, any fully functional example should be a file download (or a description of where to find it in the full CHDK package). Pages for examples should be there to explain the example, not as a place to get the code.

Language syntax and camera functions should be addressed separately. The distinction isn't quite as clear in UBASIC as it is in lua, but a reasonable division can be made.

Both syntax and camera function reference should be written at a level that assumes familiarity with basic programming and photography concepts. Attempting to have the reference be an absolute beginners tutorial just bloats it and makes it harder to read. Introductory scripting howtos should be separate pages, and relatively advanced concepts should be addressed with links to appropriate documentation. Some IMO good examples of this division are
- the official lua manual http://www.lua.org/manual/5.1/ vs. more tutorial http://www.inf.puc-rio.br/~roberto/pil2/
- perldoc manages the distinction well, although finding the exact category you are looking for can be difficult

The reference should be broken up into sections e.g.
shooting parameters (things like av/tv/iso/sd overrides)
keboard input handling
button emulation
camera status
...

Many of the functions are simple enough that a 4-5 line reference should be enough. Others require fairly detailed discussion. I'm not completely sure how to break this up: The detailed discussions should definitely be on individual pages, but having one page per function would be overkill for the simple ones. A fair bit of the discussion will apply to whole groups of functions. This suggest to me
- A list of all functions with just enough description to get an idea of what the function does
- Pages for each category of function, with any information that applies to the whole category, plus a reference to each function.

A further problem is that there is both significant overlap and incompatibility between lua an UBASIC. A lot of stuff is identical, but there are important difference, and we can expect them to diverge more in the future. This also leads to a question of how to organize it on the wiki, e.g. UBASIC/Reference/Shooting_Functions wouldn't really be appropriate for something that addresses both lua and UBASIC.

Somewhere, we should document how the whole script process operates, e.g. how it runs in kbd_task, why it needs to wait for various operations to complete, when the overrides are applied etc.
Logged
Don't forget what the H stands for.
Pages: 1 [2] 3 4   Go Up
« previous next »
 

Related Topics


SimplePortal © 2008-2014, SimplePortal