Omnimaga

Calculator Community => TI Calculators => Axe => Topic started by: josh landers on March 18, 2014, 05:39:12 pm

Title: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 18, 2014, 05:39:12 pm
***I realize that this may be somewhat controversial and I wish that everyone just give thier opinions without blowing up.

As I have been going throughout this forum I see a major difference between the forum for TI-BASIC & Axe. The key is in the way people have responded to the different types of programming problems.  Now I'm not saying axe parser is anything like the syntax of ti-basic, its not. What happens is the forum for tibasic need only be searched to find out how to do something.  But in this forum I see a common problem with the answers people give....
1) read the manual
2) a link to something that may not even be in axe, with the promise its similar

What I find even worse than that is when someone responds with the irc chatbox and doesn't put the solution on the topic.

This all boils down to one thing.... does axe parser need better documentation.  As such should we have a better command list with more details about each of the commands.  Why does the community need this? Because there is always the small chance that we scare off someone who really wants to learn it but may not have the ability to access our site every day.
I urge you to repond appropriately to this thread, stay on topic,  and help each other find a solution.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Hayleia on March 18, 2014, 05:48:13 pm
But in this forum I see a common problem with the answers people give....
1) read the manual
2) a link to something that may not even be in axe, with the promise its similar
Could you give examples of those ? Because I don't think I ever saw 2, and whenever I saw 1, it was not just "RTFM" but "this command is what you want (which answers the question), see the manual for more reference (not 'RTFM' but 'I can't tell you everything better than it's said, and now that you know where to look, you don't need my help anymore')".
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Matrefeytontias on March 18, 2014, 05:52:12 pm
In my opinion, the current commands list is very fine, and complete enough to give you everything you need to know about Axe commands.

Sometimes, people ask questions that make me (personally) think that they never bothered trying to solve their problem with reading the command list, although I usually try to answer with clarity (I hope so at least. Not a big fan of RTFM).

Also, learning is not about getting things done by other people. If you come and say "hey I would want some code that does that", we're expecting you to be wanting to learn things, so we say "here, this algorithm is what you want, implementing it in Axe will be a good exercise and will make you progress and understand the whole thing". If we just gave you the code, well good, you successfully copied text from one place to another.

So in my opinion, if we respond like that, there's a reason.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 18, 2014, 11:04:50 pm
I dont want to step on anyone's toes. All im saying in a nut shell is this...
Why if the syntax for a simple command such as bitmaps not even mention that you need a header... I dont think that thats good documentation for a command.
Now I'm certain that the command list has no single mention of what you have to do to make tilemapping work... and on top of that most of the tutorials never even say that you have to use hexadecimal notation for your tilemap declaration pointer.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: willrandship on March 18, 2014, 11:32:42 pm
Tilemapping isn't a mode, in that you'd have to write the routine yourself. In this regard, the lack of documentation for it is because it's not part of the language. You're not going to find official documentation on how to make gravity physics either, because they're not a built-in feature.

I would agree with you more on the bitmap command if there was actually any justifiable reason to use it. I regard it as a fairly worthless instruction, since stacking Pt-Ons is faster and the same number of bytes.

More documentation, with better details, would be better, though that can be said for many programming languages, not the least of which is x86 assembler, or, for another example, low-level openGL.

The thing about small community projects like this is that the list of people who can do the things you want is very small, and the list of people who are willing to is even smaller. If you want something changed, you'll generally have to do it yourself, since the fact that it hasn't yet been done is evidence that it's not going to happen.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: TIfanx1999 on March 19, 2014, 01:10:22 am
Will is correct. There really isn't any reason the command list should include how to make a tilemap work. That's more of a general programming thing, and I know I've seen a tilemapping tutorial or two floating around here. It seems like you are more interested in general tutorials, and specifically ones that cater to AXE. Would it be nice? Yea, but then again, people need to find the time and drive to do them. We actually used to have a tutorial section... I wonder where that went. ???
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Hayleia on March 19, 2014, 02:10:20 am
most of the tutorials never even say that you have to use hexadecimal notation for your tilemap declaration pointer.
You don't have to. You can put any part of your data between brackets, in a Data() command or between quotes (a bit harder to use, you need to know the correspondence). Usually, quotes are used for text data because it is a bit more convenient to write/read for the user writing/reading the source code. And hex is used for sprites because it doesn't take much space in the code. But you don't have to, you can declare your sprite like this if you want:

[]→°SquareSprite
Data(π 11111111 )
Data(π 10000001 )
Data(π 10000001 )
Data(π 10000001 )
Data(π 10000001 )
Data(π 10000001 )
Data(π 10000001 )
Data(π 11111111 )

This is much more convenient to read (everybody can see that this is the sprite of a square), but it is a bit annoying to scroll through (even though not annoying at all with zStart's jump to label feature).

My point is that there are always an infinite number of ways to achieve one thing, so the documentation would have to cover all those ways to be complete, which is impossible. Hence why it is "incomplete".
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on March 19, 2014, 02:35:37 am
There used to be Axe tutorials in the site navigation, but now they're all scattered through the Axe sub-forum and some non-tutorial articles are no longer viewable, thanks to the upgrade. I agree with most people who replied, although I agree with Josh about the IRC/shoutbox thing, since if someone only responds there and the user doesn't notice right away, it will get lost in the logs.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 19, 2014, 07:13:54 pm
Ok all great points, I think that when we do have such a small community of axe users we should maximize the potential for understanding how it works. As ive thought about this alot... how about a more verbose command list.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Runer112 on March 19, 2014, 08:01:38 pm
As I have been going throughout this forum I see a major difference between the forum for TI-BASIC & Axe. The key is in the way people have responded to the different types of programming problems.  Now I'm not saying axe parser is anything like the syntax of ti-basic, its not. What happens is the forum for tibasic need only be searched to find out how to do something.  But in this forum I see a common problem with the answers people give....
1) read the manual
2) a link to something that may not even be in axe, with the promise its similar

I can't say I've noticed this. If people do this, then they're being somewhat rude. I certainly try not do it myself, or if I do tell the asker to look at an external resource, I tell them exactly what part relates to your problem and how. I generally see others providing helpful answers as well.


What I find even worse than that is when someone responds with the irc chatbox and doesn't put the solution on the topic.

I know I tend to try to provide programming help over IRC a lot more than on the forums. That's usually because I can quickly and interactively solve the problem with the person experiencing it, working out any issues that may arise as they come. But if you'd prefer a solution be posted on the forums, just ask! I'm sure most people would be happy to oblige.


Why if the syntax for a simple command such as bitmaps not even mention that you need a header... I dont think that thats good documentation for a command.

It certainly does:

Quote from: Commands.html
Draws a bitmap to (X,Y) on the main buffer, back buffer, or specified buffer respectively. The bitmap data should have in order: width (1 byte), then height (1 byte), then the rows of the image padded with zeros to the nearest byte. Mode 0 is "Pt-On" logic and Mode 1 is "Pt-Change" logic. Mode 0 is used if unspecified.


Now I'm certain that the command list has no single mention of what you have to do to make tilemapping work...

As others have said, tilemapping is an algorithm that a coder must implement, not a built-in feature of the language. Therefore, I wouldn't expect it to be described in the language's documentation. Also as others have said, basic tilemapping implementations are described and provided in a number of tutorials on the site. Finding them now is just a bit trickier, since the new site removed its explicit index of tutorials, which I agree is not a great situation.


and on top of that most of the tutorials never even say that you have to use hexadecimal notation for your tilemap declaration pointer.

You don't have to use a hexadecimal string to include data, but it's certainly an easy way. The hexadecimal data inclusion syntax is present in the command list, and it appears in numerous fully-explained code examples in the documentation (Documentation.pdf). Also included and documented in both is another common way to include data, Data().


I think that when we do have such a small community of axe users we should maximize the potential for understanding how it works. As ive thought about this alot... how about a more verbose command list.

What kind of verbosity are you looking for here? As far as I'm concerned, the Commands.html file does exactly what it's supposed to do, providing succinct but complete explanations of what each individual command/operator/syntactical element does.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 19, 2014, 11:54:13 pm
They are shrouded in a cloud of possibilities.  Which are endless, but what I think is a good example is needed for each one with all possible arguments.
And the arguments could be colorized to make sence of what is required for the command to work and whats not. Some commands leand themselves to this in the descriptions but some do not. One such example is pxl-on and then you have Bitmap which gives you the options but doesnt tell you how to make bmp in the option.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Eeems on March 20, 2014, 12:00:51 am
They are shrouded in a cloud of possibilities.  Which are endless, but what I think is a good example is needed for each one with all possible arguments.
And the arguments could be colorized to make sence of what is required for the command to work and whats not. Some commands leand themselves to this in the descriptions but some do not. One such example is pxl-on and then you have Bitmap which gives you the options but doesnt tell you how to make bmp in the option.
bmp files are pretty standard. http://en.wikipedia.org/wiki/BMP_file_format I'd assume that it's a sequential piece of data in which bits with a value of 1 turns the pixel on and 0 off.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Runer112 on March 20, 2014, 12:37:03 am
They are shrouded in a cloud of possibilities.  Which are endless, but what I think is a good example is needed for each one with all possible arguments.

I think the descriptions speak for themselves. The examples for most commands would just be pretty pointless anyways, like Pxl-On(95,63), Pxl-On(40,20)r, Pxl-On(7,0,L1).


And the arguments could be colorized to make sence of what is required for the command to work and whats not.

Signatures are colorized, the colors just represent different syntactical elements or data types. And every valid form of each command is shown, so what's required for a command to work is for it to be of one of the given forms.


Some commands leand themselves to this in the descriptions but some do not. One such example is pxl-on and then you have Bitmap which gives you the options but doesnt tell you how to make bmp in the option.

I thought it was pretty straightforward, a pointer to the bitmap width byte, followed by the bitmap height byte, followed by the image data in the standard, row-major format, with each row padded with 0 bits at the end if necessary to fill a whole number of bytes. Here (http://www.cemetech.net/forum/viewtopic.php?t=9215&start=42)'s a post I made on Cemetech giving an example.

If any command's syntax isn't clear, just ask.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 20, 2014, 01:16:06 pm
Example:
Code: [Select]
Before: EXP▶Hex     Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Eeems on March 20, 2014, 01:21:26 pm
Example:
Code: [Select]
Before: EXP▶Hex     Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.
You know you start modifying the documentation with stuff like that and then submit it to Runer112 to include in the official releases.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Matrefeytontias on March 20, 2014, 01:26:53 pm
Example:
Code: [Select]
Before: EXP▶Hex     Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.
Unnecessarily verbose in my opinion. It's exactly saying with more words what was written already, without any further explanation. Also, you're supposed to know how to read the rest of the documentation and see that you can store numbers into variables.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: thepenguin77 on March 20, 2014, 01:49:03 pm

Instead of fighting about this, can we just agree that although the current documentation is complete, more could be desired?


For instance, if we compare the axe commands to the android documentation we can see that the android documentation is very thorough to the point that after reading it, you really shouldn't have any questions. (this is the documentation for Camera.open()) (http://developer.android.com/reference/android/hardware/Camera.html#open(int)).


But, if you look at the android documentation, you'll see that it takes more than half of your screen for one command. The purpose of commands.html is to put everything in front of you in a concise way so sometimes the 100% complete explanation isn't given.


Whatever happened to that axe wiki? I feel like that's probably the best place for the kind of information you want. A wiki can be as verbose as you like and can provide the actual 100% explanation.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: alberthrocks on March 20, 2014, 01:50:28 pm
On the topic of Axe documentation...

We used to have an Axe wiki, where this kind of stuff (tutorials and “better” documentation) can be found. Mediawiki needed to be updated 24/7 though, and things got messy so fast (spambot fiesta!) that it was eventually shut down.

(See: http://www.omnimaga.org/news/axe-parser-wiki-opens-its-doors/msg220368/#msg220368)

I don’t think we’ll ever put up another wiki again (unless it’s some other wiki software, NOT Mediawiki). But if you’re really interested in improving documentation, you can either modify the current one (that one HTML file), or get your hands messy by creating another one!

Sphinx (http://sphinx-doc.org/) is a documentation format that creates pretty documentation from simple markup. LOTS of projects use it, and although it is a little overkill for a project like Axe, you can certainly use it to provide meatier details about Axe, including tutorials and the likes. I’d love to see a https://axe.readthedocs.org/ one day!

EDIT: Looks like thep ninja'd me!
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Eeems on March 20, 2014, 01:57:24 pm
On the topic of Axe documentation...

We used to have an Axe wiki, where this kind of stuff (tutorials and “better” documentation) can be found. Mediawiki needed to be updated 24/7 though, and things got messy so fast (spambot fiesta!) that it was eventually shut down.

(See: http://www.omnimaga.org/news/axe-parser-wiki-opens-its-doors/msg220368/#msg220368)

I don’t think we’ll ever put up another wiki again (unless it’s some other wiki software, NOT Mediawiki). But if you’re really interested in improving documentation, you can either modify the current one (that one HTML file), or get your hands messy by creating another one!

Sphinx (http://sphinx-doc.org/) is a documentation format that creates pretty documentation from simple markup. LOTS of projects use it, and although it is a little overkill for a project like Axe, you can certainly use it to provide meatier details about Axe, including tutorials and the likes. I’d love to see a https://axe.readthedocs.org/ one day!

EDIT: Looks like thep ninja'd me!
Nothing wrong with mediawiki, you just have to secure it properly. It's what the largest wiki in the world uses after all (Wikipedia).
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: JWinslow23 on March 20, 2014, 02:05:36 pm

Instead of fighting about this, can we just agree that although the current documentation is complete, more could be desired?


For instance, if we compare the axe commands to the android documentation we can see that the android documentation is very thorough to the point that after reading it, you really shouldn't have any questions. (this is the documentation for Camera.open()) (http://developer.android.com/reference/android/hardware/Camera.html#open(int)).


But, if you look at the android documentation, you'll see that it takes more than half of your screen for one command. The purpose of commands.html is to put everything in front of you in a concise way so sometimes the 100% complete explanation isn't given.


Whatever happened to that axe wiki? I feel like that's probably the best place for the kind of information you want. A wiki can be as verbose as you like and can provide the actual 100% explanation.
+1'd. What happened?
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: alberthrocks on March 20, 2014, 02:13:51 pm
Nothing wrong with mediawiki, you just have to secure it properly. It's what the largest wiki in the world uses after all (Wikipedia).
Of course Wikipedia uses it - but they monitor their site 24/7 and patch things up quickly. If we install MediaWiki, someone needs to make sure that it's secure, and that updates are installed ASAP. Last time that didn't really happen...

Personally, I'm more of a "set-and-forget" kind of person. Mediawiki is more of a "set-and-maintain" software.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Hayleia on March 20, 2014, 03:57:37 pm
Example:
Code: [Select]
Before: EXP▶Hex     Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.
I don't agree that this should be written, or at least not by default, because maybe you don't want to store that pointer, maybe you just want to use it once and you'll just write for example Text(0,,18▶Hex), so your "→Ptr" appears nowhere.
However, something that could be done (but probably annoying to do) is a button next to each command that expands a box showing examples about how to use that command or more information or whatever. But I still think that the current presentation is fine, with only one concise line about what it takes and what it returns showed by default, hence why I'd say there should be that button (a bit like with spoilers on forums in fact).
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on March 21, 2014, 12:15:40 pm
Also I think Axe wiki was hosted on Juju server, so after too much downtime and spam it was pretty much forgotten, along with the original PrizmWiki.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 21, 2014, 12:36:12 pm
Example:
Code: [Select]
Before: EXP▶Hex     Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.
You know you start modifying the documentation with stuff like that and then submit it to Runer112 to include in the official releases.
I would love too! But one problem, I cant just jump into that and expect no errors, I myself dont know all the possible formats ect but i will take a shot at it!

Edit: somithing happend and I didnt see all the posts... thanks for all the input!

On the topic of Axe documentation...

We used to have an Axe wiki, where this kind of stuff (tutorials and “better” documentation) can be found. Mediawiki needed to be updated 24/7 though, and things got messy so fast (spambot fiesta!) that it was eventually shut down.

(See: http://www.omnimaga.org/news/axe-parser-wiki-opens-its-doors/msg220368/#msg220368)

I don’t think we’ll ever put up another wiki again (unless it’s some other wiki software, NOT Mediawiki). But if you’re really interested in improving documentation, you can either modify the current one (that one HTML file), or get your hands messy by creating another one!

Sphinx (http://sphinx-doc.org/) is a documentation format that creates pretty documentation from simple markup. LOTS of projects use it, and although it is a little overkill for a project like Axe, you can certainly use it to provide meatier details about Axe, including tutorials and the likes. I’d love to see a https://axe.readthedocs.org/ one day!

EDIT: Looks like thep ninja'd me!
Nothing wrong with mediawiki, you just have to secure it properly. It's what the largest wiki in the world uses after all (Wikipedia).
I shall take a look
And

Example:
Code: [Select]
Before: EXP▶Hex     Converts the number to hexadecimal and returns the pointer to that string.
Code: [Select]
After: EXP▶[HEX] -> PTR  Converts the expression to hexadecimal and if a pointer is declared it will be available at named pointer.The red is not needed, but if you want the pointer to go somewhere you should provide this information.
I don't agree that this should be written, or at least not by default, because maybe you don't want to store that pointer, maybe you just want to use it once and you'll just write for example Text(0,,18▶Hex), so your "→Ptr" appears nowhere.
However, something that could be done (but probably annoying to do) is a button next to each command that expands a box showing examples about how to use that command or more information or whatever. But I still think that the current presentation is fine, with only one concise line about what it takes and what it returns showed by default, hence why I'd say there should be that button (a bit like with spoilers on forums in fact).
The  -> ptr was suppose to be red but that didnt happen... sorry it makes more sence if it was red though.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 24, 2014, 12:55:48 am
Possibly the solution?

An Axe Parser textbook.
It will have a section on all the parts of Axe Documentation, from commands to reqierments. I will be wotking on this shortly but in the meantime I shall share my outline with the community.

(1)  An Introduction to Axe Parser
     I. History of Axe 
     II. Releases and Major Improvements
     III. Requirements for Learning Axe Language
(2)  Axe Parser from an inside perspective
     I. How TI-OS handles Axe Source
     II. What can one create in Axe
     III. Math and Numerical Systems
     IV. Compiled Axe Source
(3)  Axe Parser Commands
     I. Syntax
     II. The Rules of Axe
     III.  Commands for Version 1.2.2
(4)  Advanced Features of Axe
     I. Optimizations
     II. ASM( )
     III. Axioms
(5) Troubles with Axe Parser
      I. Frequently Asked Routines
     II. Problems and Solutions
(Index)
(Credits)
(Resources)

Just let me know if any part needs explanation and I will try and explain.

This Textbook will be free and I plan on it being around 250-270 pages.
It will have examples and such but will not be a go-to guide. All of the information that I will put in it will coe from this site and the documentation for axe that is used presently in the zip file.
Why am I doing this? Because I feel like the current docs dont supply enough information to have axe parser ready to fly out of the boxn I had to spend three solud months of trial and error doing simple tasks.
If anyone wants to DIRECTLY involve themselves in this textbook or would like to help with translation to other languages please PM me.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: TIfanx1999 on March 24, 2014, 01:21:26 am
My personal opinion: If it's that long, no one will read it. Ever. I think that's a bit much. Honestly, if the wiki were maintained again I think that would be the best solution. It would also allow multiple people to add content, so the burden isn't on just one person.

Another good idea would be to bring the tutorial section back here, or at least have a stickied topic that lists (and links to) all tuorials.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 24, 2014, 01:25:05 am
Thats just my estimate because if a 1 page per command but some commands come in groups of three or two so it will be lighter then that. Its just a way of saying heads up its gonna take some time for me to do. Sorry if that sounded scary large.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Streetwalrus on March 24, 2014, 02:10:35 am
I agree that the tutorial that comes with Axe need to be updated and that we need more details about commands for beginners as well as advanced tricks. I'll consider setting up a wiki. Not Media Wiki though.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on March 24, 2014, 02:23:26 am
It would be better if the wiki was hosted on Omni server, though, or maybe soru's, since those seems likely to be around in a few years. Otherwise, we never know when the wiki will go down again.

Btw, are there any backups of the old Axe wiki?
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Streetwalrus on March 24, 2014, 12:42:17 pm
Well yeah. If it's on Omni I think Omni admins will manage it but if Soru hosts it and he doesn't want to bother with administration I'm volunteer.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 24, 2014, 04:13:44 pm
Could a new board be startrd and maybe have stricter rules of who can post, example if a person has posted x amount of times in an axe related board then they can post in the axe wiki that way you have to have a certain amount of posts that have been helpfull beforehand.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Streetwalrus on March 24, 2014, 05:47:43 pm
Or a GitHub repo with markdown format doc. Only people part of the "team" can freely edit stuff, others have to make a pull request which will be reviewed by said team.
It's easy enough to revert changes or see previous versions of it too.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 26, 2014, 10:05:44 am
Err, Github isnt really a good way for what is needed unless axe parser became open source for everyone to see. However the site is a really organized way to see code. What if we just had a select group of Axe users to provide documentation and information. A group of 10 would be the max and 5 minimum.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: alberthrocks on March 26, 2014, 10:28:56 am
Err, Github isnt really a good way for what is needed unless axe parser became open source for everyone to see. However the site is a really organized way to see code. What if we just had a select group of Axe users to provide documentation and information. A group of 10 would be the max and 5 minimum.
Just because it isn't open source (which is not necessarily true) doesn't mean you can't create open documentation on a website like GitHub. Like I mentioned before, you can generate Sphinx documentation, put it on GitHub, and have a site like readthedocs.org generate and host it.

As for the wiki, if someone can support it, why not? :) Are we going to stick with MediaWiki though, or use another wiki engine?
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Streetwalrus on March 26, 2014, 12:42:10 pm
If mediawiki then it should be like on WikiTI where you have to privately ask for an account to prevent spam bots from even reaching the site.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on March 26, 2014, 02:02:50 pm
I think it would be better if the wiki was modified so that it shares the same account as your Omni one or at least modify Omni so when you sign up, it automatically creates a Mediawiki account. If you have 1 Omni post, it would let you edit the wiki. I think that's how Cemetech's Doors CS wiki operates, but I could be wrong.

Else, requesting for an account could work, as long as the ones in charge of the wiki won't constantly disappear, forcing users to wait months or forever before their account is finally approved.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 26, 2014, 02:32:51 pm
That sounds reasonable... but the wiki admins shouldnt be omni admins. That way the current admins dont get bogged down in approvals.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on March 26, 2014, 03:47:32 pm
Well, although more admins fluent in Axe would be a good idea, also having the Omni admins as wiki admins would make sense because they are the ones in charge of running the site. I don't think it would make any sense if the owners of this website had zero control on what content is allowed in the Axe wiki, other than the fact only three admins (that are no longer active) ever used Axe. That way, they can also solve issues if the wiki crashes or anything.

Also those who aren't in charge of Omni that becomes wiki admins should be long-time Axe users that are still active and trustable. Remember that one Omni staff that tried to delete the entire Axe sub-forum and banned everyone from the IRC chatroom just because one of the Omni admins was Christian. They should definitively have the same rules as the rest of the staff and their activity monitored (for example, if they stop posting for months or if they often start drama).
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Streetwalrus on March 26, 2014, 05:08:33 pm
I think there should be a link in your account settings if you have over 5 posts to create a wiki account instantly. That should prevent spam, avoid over 9000 unused accounts and still be an easy way. Of course one could still mail the wiki admins to get an account created.
Also according to your criteria I qualify as a wiki admin/staff. ;)
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Eeems on March 26, 2014, 08:21:03 pm
For having Omnimaga host an integrated wiki, somebody can put in a request for that. I'd have to talk it over with the other admins, and make sure the integration was understood by enough of us that I (or whoever built the integration) am not the only one who can support it.

Having an integrated wiki that requires an Omnimaga account to register would be nice, but honestly I think if we want to start adding more documentation for things on a wiki, wikiti (http://wikiti.brandonw.net/) is a better option.

For this it would probably be better to use github like albert mentioned.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: willrandship on March 26, 2014, 08:23:59 pm
@street 5 seems a little low. Why not have it be the same as omnom? It's not like you need an account to look at the wiki, just to edit it.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on March 26, 2014, 08:24:49 pm
Yeah I sent a request earlier today :)

That said, now that you mention WikiTI, I guess that could be a nice alternative if people don't mind WikiTI drifting away from its ASM near-exclusivity, since originally WikiTI was created just for Z80 ASM.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: Streetwalrus on March 27, 2014, 02:18:38 am
@street 5 seems a little low. Why not have it be the same as omnom? It's not like you need an account to look at the wiki, just to edit it.
Yeah that's true. However I always thought OmnomIRC needed post count was a bit high.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DrDnar on March 27, 2014, 02:57:56 am
That said, now that you mention WikiTI, I guess that could be a nice alternative if people don't mind WikiTI drifting away from its ASM near-exclusivity, since originally WikiTI was created just for Z80 ASM.
I'm the only WikiTI admin that matters (I'm the only one you have a decent chance of contacting), and I don't mind. There's USB8X documentation on the Wiki, and there's even a BASIC section (http://wikiti.brandonw.net/index.php?title=Category:83Plus:Basic) on the Wiki, although it's pretty poor.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: TIfanx1999 on March 27, 2014, 09:33:23 am
If we were to set up one internally here (a wiki) I wouldn't mind helping manage it. I'd guess it can't be too difficult. Don't know about integration to the site or how that would work though.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 27, 2014, 07:46:14 pm
How about nested admins? The omni admins have control over axe wiki admins, and only axe wiki admins can create a page. Then only people who have posted in this axe parser support forum over 20 times can edit, whereas only people who have posted five times in the forum can comment and anyone can request a command or topic to be wikied.


Edited for clarity!
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: TIfanx1999 on March 27, 2014, 09:26:39 pm
If it gets to be too much of a pain for people, no one will contribute. We don't want to over complicate the process. Also, punctuation would make your post a lot clearer.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on March 31, 2014, 07:12:01 pm
Ok I edited it for clarification.  I think if we sticked a topic that linked to say a Google Doc page, then we could have a documentation presented on a familiar format. The people with access to edit the page are given so by invitation only. And the page can be read or printed freely.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: DJ Omnimaga on April 03, 2014, 03:03:29 pm
How about nested admins? The omni admins have control over axe wiki admins, and only axe wiki admins can create a page. Then only people who have posted in this axe parser support forum over 20 times can edit, whereas only people who have posted five times in the forum can comment and anyone can request a command or topic to be wikied.


Edited for clarity!
I don't see why Omni admins shouldn't be able to create a page. All Omni admins should have 100% control on everything hosted on Omnimaga, so if Axe wiki admins starts breaking havoc or something or they start using atrocious grammar, then the Omni admins can walk in then fix broken pages/kick out/ban troublesome users/admins.

Else, it would be like if Eeems/Geekboy1011 had FTP access on Omni, yet couldn't edit my posts if I upload shock images.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on April 04, 2014, 06:04:44 pm
That's what I said. .. nested.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: TIfanx1999 on April 05, 2014, 09:43:27 pm
Yes, but then you said:
Quote from: josh landers
and only axe wiki admins can create a page
which makes it seem like axe wiki admins would have greater power. It was still a bit unclear, that's all.
Title: Re: [Controversial] Better Axe Documentation Could Be Needed
Post by: josh landers on April 06, 2014, 01:22:26 am
Yes, but then you said:
Quote from: josh landers
and only axe wiki admins can create a page
which makes it seem like axe wiki admins would have greater power. It was still a bit unclear, that's all.
Oh sorry I meant that omni still has power over the wiki but they woulnt need to control it directly.