Home Download Buy Blog Forum Support

Documentation!

Documentation!

Postby spadgos on Sat Feb 18, 2012 5:12 pm

Hey everyone. As I'm sure anyone who has tried writing a plugin has discovered, the documentation of the API is somewhat lacking. Without the source available (?), nor decent docs, there's a lot time wasted. Using this forum can be useful, but forums are a poor format for discovery or even Q&A. Anyway, I think there should be more effort put into the documentation, but at the same time, I don't want jps held back with writing docs when he can be making cool features for ST... Also, just demanding more documentation isn't going to make it happen -- you gotta do these things yourself, right?

I propose an open wiki for API documentation (or similar... whatever has the least barriers for us users hacking around in the docs to share knowledge). Actually, I don't even think a wiki is a great format for documentation (since it's easy to make information very hard to discover), but the important concept is that Joe Hacker can add and improve it with minimum fuss.

I'd really like to hear thoughts and opinions on this, and if there's enough consensus a) that it's a good idea, and b) how it should work, then I'd be happy to start this project with whoever else is interested.
spadgos
 
Posts: 121
Joined: Thu Oct 06, 2011 12:49 am

Re: Documentation!

Postby C0D312 on Sat Feb 18, 2012 6:32 pm

I agree. As awesome as sublimetext.info is, the documentation needs to continue to grow as new features are added in every build. In my opinion, though, I think we should just have a website publicly hosted through github (i.e. Sublimetext.github.com). It could be through the sublime text organization. That way, anyone can fix mistakes or errors through a pull request, most people are familiar with github, there would be notifications of changes, and all members of the sublime text organization on github would help to maintain the site. How's that sound?
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Documentation!

Postby spadgos on Sat Feb 18, 2012 8:28 pm

Yeah, great idea.

In terms of format, I'm a big fan of the single-page documentation. Makes doing a find very easy. Something like Backbone's documentation is a good example of this.
spadgos
 
Posts: 121
Joined: Thu Oct 06, 2011 12:49 am

Re: Documentation!

Postby tanepiper on Sat Feb 18, 2012 11:37 pm

Great ideas - some stuff i'd like to see:

* How to create a window with specific dimensions and locations to use as console and stdout data
* Async processes (like running python, nodejs, ruby) that don't hold up main thread - interactive for running scripts
* Language defs with tmBundles

I want to re-write my nodejs plugin to be more useful for debugging and would love to implement these features, but not sure how.
tanepiper
 
Posts: 68
Joined: Sun Nov 06, 2011 6:40 am

Re: Documentation!

Postby guillermooo on Sun Feb 19, 2012 12:37 am

If everybody thinks open sourcing the docs is the best thing to do, I'm fine with donating what I've done up to now. I'm doing a poor job of updating sublimetext.info these days anyway. However, scattering the docs even more won't help anybody. I was thinking I could put everything up on GitHub and people would send pull requests, but if we go for a GitHub-only solution, that's fine too, but I think GitHub might be too intimidating for non-technical users. The really important thing IMO is that everything is in one single place.

There's also readthedocs.org if we're sticking with Sphinx (that's what I'm using now).

As far as organizing the docs, I think there should be a series of main topics and then a sort of a knowledge base where self-contained tutorials, troubleshooting etc. would go.
guillermooo
 
Posts: 718
Joined: Thu Jul 23, 2009 9:06 am

Re: Documentation!

Postby C0D312 on Sun Feb 19, 2012 4:27 am

but if we go for a GitHub-only solution, that's fine too, but I think GitHub might be too intimidating for non-technical users


Well, what's nice about github is they allow everything to stay together. We could host a basic site through them (see twitter.github.com for an example) and the only time someone would need to interact with git and github would be if they wanted to contribute with a pull request. If anyone has a better wiki based solution, I'd be interested. Github was just the first thing I thought of because many Sublime developers (aka people able and willing to contribute to the ST knowledge base) already use github.

Github makes it pretty simple to set of a site too: http://sublimetext.github.com/ (setup instructions are on the page)

scattering the docs even more won't help anybody

I completely agree. It's hard enough that there is Sublime Text 1 and 2 docs hosted here and then more information available through sublimetext.info
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Documentation!

Postby skaet on Sun Feb 19, 2012 9:42 am

I agree that a github based solution is probably better than the previous wiki idea. I was hesitant to set up a wiki straight away since no one voiced much support, and it would only serve to fragment the documentation community.

Happy to offer any assistance putting together docs.
skaet
 
Posts: 93
Joined: Thu Sep 16, 2010 3:37 pm

Re: Documentation!

Postby guillermooo on Sun Feb 19, 2012 9:22 pm

Ok, so what's the next step? I don't know anything about setting up a static site on GH, so someone else has to step in.

Open questions:

* are we sticking to Sphinx?

Sphinx gets my vote. Sometimes it feels too heavy-weight, but it keeps links working and gives you a decent interface and search almost for free. I don't see any major shortcomings to keep using Sphinx, but others might disagree. We should reach an agreement asap on this; the goal's to write stuff! ;) I think nothing stops us from sticking with Sphinx now and gradually migrate the content to a better system if one emerges. And maybe GH imposes some specific format, which actually would makes things easier in a way.

* license?

All this time I've been thinking about eventually releasing the docs source (not that it would be hard to get it now anyway), and for some reason I thought a Creative Commons license would work well. In reality, I couldn't care less about licenses, but if anybody has strong arguments in favor of one of them, I'm all ears.

* my next steps

I'll try and commit the drafts I have lying around so that work, however rough, doesn't get lost.
guillermooo
 
Posts: 718
Joined: Thu Jul 23, 2009 9:06 am

Re: Documentation!

Postby C0D312 on Sun Feb 19, 2012 11:21 pm

There is now a blank github page for sublimetext.github.com
The code (if there was any) can be found here: https://github.com/SublimeText/sublimetext.github.com

@guillermooo
I'm not familiar with Sphinx so it would probably make sense for you to set up the basic project/structure so that I don't butcher the entire thing. But I'll do some more reading about Sphinx so I can help as soon as something's up.

As for licensing, It really makes no difference to me. I'll just let someone else deal with that :)
C0D312
 
Posts: 1063
Joined: Sun Jul 10, 2011 3:23 am

Re: Documentation!

Postby skaet on Mon Feb 20, 2012 12:07 am

Licensing issues may arise from shared code snippets or even full packages. While the site itself can be safely licensed under Creative Commons, individual package documentation would remain under the author's own licensing terms according to their license file/file header etc. For general site content and contributed code snippets, I lean toward the Attribution-ShareAlike license as it allows commercial use but requires attribution to the original site/author as well as licensing any derivatives under the same terms. I'm fairly open in this regard in that I feel only a derivative code block should be ShareAlike CC-licensed instead of the whole work (unless the whole package is based on a shared code snippet, that is!).

To publish a GH hosted site, we only need to commit an index.html file (+CSS/JS/IMG if not using a CDN) to a repo named sublimetext.github.com. I can see one has already been made so that's not a problem. What I suggest for package documentation is to have a basic predefined template in a "gh-pages" branch. An author wishing to contribute their own documentation may be added to the SublimeText organisation so they can create their own "gh-pages" branch, or they can fork the template and submit a pull request. The 2nd option is my recommendation for quality control and security.

I prefer Markdown for documentation as it's well supported by github and a little easier (semantically) than Sphinx. I also quite like the online tool to convert to HTML, making it less complicated to build.
skaet
 
Posts: 93
Joined: Thu Sep 16, 2010 3:37 pm

Next

Return to Plugin Development

Who is online

Users browsing this forum: No registered users and 3 guests

cron