Documentation improvement

[arxpoetica]

[See https://github.com/socketstream/socketstream/issues/513 as a precursor to this.]

I've created a feature/doc-updates branch. I think it was @RomanMinkin who did a tremendous effort in going through our docs and trying to get them in a better state. However, after having given them a good look over, I think we've over complicated the task by throwing an angular wrapper around the documentation section—it makes them difficult to maintain.

For example, I went to go work on the documentation this evening and spent way too long trying to figure things out when all I wanted to do was write.

I think we could work on trying to make the process simpler, and I appreciate @thepian's view about getting the community involved to that end. (It's probably a catch 22—need to make it easier first to get people to start helping.)

Here are some starting suggestions.

1. Lets swap out ngdocs for something that doesn't rely on Angular, and is a little more accessible and established, like JSDocs.
2. For authored docs, markdown is probably the best bet. There are techniques for converting .md files into HTML, and markdown is the flavor, too, of GitHub. That way we're not repeating our efforts, and the docs can exist in two places. (Good for when servers are down.)
3. Also, maybe we could all just divvy up some of the missing or incomplete topics and take a stab at authoring single pages—I've said I plan on working on the docs a lot, but the knowledge of how things work is in everyone's minds. If everyone takes a stab at a draft (it can be messy!), I can be editorial and clean and organize things. (I come from a pack of literary wolves and editors, as evidenced by all my verbose GitHub comments.)

Those are some initial thoughts. Please add you own ideas, and I'll work around the communities' needs.

[arxpoetica]

Just to give everyone a quick "for example," I can't find anywhere that gives an installation guide for setting up SocketStream to do development work on the app itself. Fortunately, with a little trial and error I was able to figure it out on my own (npm link!). But there should be a 101 on this. I started writing it. Anyone want to modify it? Did I do it right?

# Developing on SocketStream

Fork SocketStream on Github.

Then install and link the forked SocketStream

    git clone [email protected]:[your-fork]/socketstream.git
    cd socketstream/
    npm link

Generate your app:

    socketstream new -m [app-name]

(Additional app generate options include `-c` if you prefer CoffeeScript, `-j` if you prefer Jade, and `-s` for Stylus or `-l` for Less if you prefer a CSS precompiler.)

Next, run the following commands:

    cd [app-name]
    npm install

And start your app:

    node app.js


[...more to come, details on pull requests, build process, etc., etc...]

I know @kulicuu said once he was going to get me running out the gate, but I finally got around to doing it on my own...all these years... ;)

[thepian]

Could you try to branch of next rather than master, I've put quite a bit of additional documentation in there.

I really do not feel like merging all those comments and converting them to JSDoc.

I expect that 0.4 topics will be complete within the next month, so that would mean that there is a release candidate for it then in the existing NG Docs format.

---

On NG vs JS docs.

NGDocs don't seem to fit that well with the Socketstream source structure, so the API docs generated are a bit odd, but mostly O.K.

I'm not that sure that JSDocs is an improvement. When I last worked with it (granted quite a long time ago) they generated quite unattractive output with at structure that wasn't terribly powerful. I recall them as a straight imitation of JavaDoc, which was cool when it came out, but hasn't really evolved in terms of usability.

For the examples/tutorials I can imagine we could do better. I assume you are not aiming to use JSDoc for this?

[RomanMinkin]

Hey guys, when I was adding ng-docs I also was looking for a better solution, but i did not find anything better at that tome. I was targeting two goals:

1. Make docs searchable with no back-end required
2. Internal SecketStream API support, since it's an open source project

So ng-docs to me is more like docs provider than docs generator.

Right now I would take a look at https://stripe.com/docs for 101/Guides and for API make sense to keep ng-docs. Here is a big difference between people who whats to use SS and who wants to contribute.

[RomanMinkin]

...forgot to add that I also bright ng-docs for automated change log generation https://github.com/socketstream/socketstream/blob/master/CHANGELOG.md

[thepian]

I just used bourbon.io ; it's quite nice, I wonder what they made it with

[arxpoetica]

@thepian I'll delete the working docs branch and rebranch off of next—I haven't done anything significant yet—but I do plan on working with markdown.

This may be a useful tool for us: https://fiddle.md

We can take up considerations about JSDocs vs ngdocs vs something else at a later date; it's not the most important aspect of documentation, I agree.

[arxpoetica]

updated docs branch: https://github.com/socketstream/socketstream/tree/feature/doc-updates-0.4

[thepian]

Great

[arxpoetica]

Hey—so I set up a workspace on Hackpad for a collaborative place to edit docs-in-the-works.

Naturally, the best place to have the docs is still in .md files under the /docs folder committed in this github repo. But I wanted somewhere where it would be easy to edit stuff a little more on the fly and in a collaborative way. Hackpad is pretty awesome for this kind of stuff (it's better than Google Docs, but that's another topic).

It's private, so if you want an invite, just let me know your email (see mine over here: https://github.com/arxpoetica) and I can add you: https://socketstream.hackpad.com/

[paulbjensen]

Thanks @arxpoetica. Yeah markdown is still a great way to do docs.

Looking at the thread, I agree with @thepian that getting articles on SocketStream would have a big impact on growing the community. I'd like to assist but time is of short supply for the next 2 months at least (finishing client work and writing book).

Id also like to get the SocketStream Twitter account in more hands - I looked at Buffer to manage this but was wondering if there are any other tools that can do the same thing (teams accessing social media accounts), I also looked at Hootsuite. If anyone sees anything then please let me know.

[thepian]

I think the fundamental strategy should be

1. Keep a steady stream of improvements to Socketstream (at a manageable pace)
2. Satisfy one existing fronted dev community at a time

IMO streaming is a niche feature, so pitching to the converted is not the best use of time. Better to show the usefulness to people that are not used to it.

I'd like for instance to show really good support for Angular to that community, and then move on to another community.

[thepian]

http://samwize.com/2014/01/31/the-best-documentation-generator-for-node/

http://underscorejs.org/docs/underscore.html