GitHub Documentation
sizzlemctwizzle opened this issue · comments
I definitely think there needs to be some GitHub documetation for GM_config. So far the majority of features are largely undocumented and several things have changed over time.
Currently the most documentation we have is the stuff I wrote on the group page, but that just covers the most basic usage. There is a guide but it only does a little explaining(most of which is out of date) and then sort of goes off on a tangent and talks about a bunch of extensions to GM_config the author wrote which is just overwhelming.
There is currently no source of comprehensive documentation. I've decided that github pages would be a good idea so people can easily contribute to it.
Thanks... I was going to suggest this too ;)
Do you think I should go wiki or github pages?
Depends on if you want open help or contributor help. Maybe a balance of both... have an open wiki and then you and contributors pluck out what is needed for the official pages? I think the wiki is still available even if it's not "turned on"... sooooooo tis up to you. :)
Also a good point to start is with a FAQ... that will probably be the most volatile article at first since guess who is here asking questions! ;) I can drum up tons of questions if you like since I'm the noob but they'll come in at the rate that I think of them. I was thinking of starting a wiki on my fork and then you could look at stuff. Note I don't use much of gh's mark down because it's quite buggy although not all of it.
Forgot to add... Basically this is the GM_config toolkit... because that's what this does. There are several methods of building docs... the first being a reference type manual which is usually for the techies and includes the API.. .and the other is a "wizard" style which is what explains in plain english how to use something from start to finish. :)
I turned off the wiki. You can still go to the page, but you can't edit it. I prefer contributor help over open help for documentation purposes. This makes sense to me since not many people know much about GMC. I don't actually use markdown either, but I think we should for the github pages. I think there should be one page that has all the basic information to get started and that page should just link to other pages that give specific in depth details.
Just remember that documentation is usually highly volatile (e.g. changes a lot) especially since there isn't much in the first place... but the polished product can be on pages. One of my main concerns with GM docs is that Anthony likes to break links by changing the bookmarks... He's not very wise in that respect... So the polished product should maintain the same bookmarks for external reference regardless... It's very simple on GH to do this... one can even have several bookmarks applied to the same subsection.
Just as a FYI the "beta" wiki is in effect... some kinks are being worked out still. The beta wiki is migratable from your Admin button on this repo...
BEFORE YOU DO THIS... some notes to consider
- Since you haven't created one yet it appears to be permanently disabled with a .htaccess style redirect for the classic
- If you do enable the "classic" wiki there are some differences between the "beta" and it.
- Do not use bookmark anchors with unusual characters... I haven't determined what their full encoding scheme is but I know at least the colon (:) doesn't work. I use standard mediawiki encoding here but that's up to what you choose... encoding is
.XX(dot hex hex and I assume unicode can be used but I've never seen a unicode mediawiki yet) - Do not use hyphens... Hyphens on filenames are currently changed into spaces... so if you want a hyphen as of right now, you are out of luck.
- periods (.) do not work in classic but do work in the beta
- The "beta" wiki can be used exactly the same way a SCM repo is used... clone it and then people can clone yours and submit changes. About time they implemented my feature request from mid-last year. ;)
- Premature estimate is in about 25 days it will become "non-beta" and all "classic" wikis will be deleted.
- After deletion of classic wikis, they claim that they will redirect external links but who knows for how long.
- textile is the least buggy and they appear to have fixed all their case-sensitive issues with their proxy/url parser but I'm still checking. Markdown is still very buggy and has way less features compared to textile.
- In short.. you will need to decide if you want to use this instead of pages... having it included in this repo would be a plus for development as it would categorize it a bit better then pages. You will also need to choose what mark/up-down language to have this project in... granted you can probably mix them but usually it's based off the *.md filename for markdown and *.textile for textile and probably a few others when people download the wiki repo. I would prefer to work in one an only one per project... but the choice is yours.
- PLEASE pick an FOSS documentation license as well.
I'll add/change to this some more if I find any other huge problems... Just thought you should know :)
When and if you enable "beta" wikis... your url will be http://github.com/sizzlemctwizzle/GM_config/wiki
Thanks for all the very useful information Marti. I've decided to enable the "beta" wiki. Since GitHub is already really Markdown centric I suspect overtime it will be the most complete markup language for use on the wiki. So I'm going to go with Markdown. I really like that the wiki has been integrated with the repo.
LOL I am unable to clone it. Anyhow... buggy GH markdown from buggy inexperienced coders at GH it is then. ;)
EDIT There we go had to create it first on mine... Also disabling of classic wiki disables beta wiki... whether it's linked or not we'll see.
EDIT It's not... unable to fetch upstream to you. I'll try destroying my repo fork again.
EDIT LOL Nope. Amazing that they even get paid for this kind of solid coding ;) Guess I'll try later as well as try out some other more stable SCM sites soon.
Wow, I really need to list all the types of data GM_config accepts and how pass them to init().
hehe Indeed. It's taken me a bit just to discover what is available myself and I'm sure I'm missing something too.
Improving the wiki will continue to be an ongoing mission, but it's in much better shape now so I'm going to close this issue. Help from anyone will be greatly appreciated.