User Supported Wiki / Documentation

[Logicwrath]

Is there currently any kind of wiki or user contributed documentation system setup?  This forum is helpful and great, however, it would also be great if we centralize our independent documentation of configurations, best practices, scripts, innovations etc.. in some kind of wiki.

I have seen members post good ideas, work arounds, and best practices in the forum.  However, threaded conversations are not ideal.  Is there any plan to create a community driven documentation system like a wiki?

If I spend a long time testing and creating something I am typically going to be documenting it on my end.  It seems like this documentation would be better served if it were shared with the entire community.

[Darren Schreiber]

Great question! There is! It's a bit in transition at the moment but you can participate.

We used to use Confluence. The problem we had with confluence was:
* No way to use our own CSS / HTML. While the tool itself lets you do that, they overwrite/force you to import the default themes they have and randomly update them which breaks customization. And no custom JS is allowed, no modifications to the nav bar (so that you can quickly link to other sources), etc. So, yeah, it's a problem.
* No great way to have public/private/paid customer material without super complex users/groups that don't integrate to single sign-on
* Wiki markup was not ideal, a lot of times we want to imbed JS or apps or test tools and we can't easily unless it's a supported plug-in.
* No versioning
* The default TOC format is OK but it's hard to make a reference manual or printable / brandable manual out of it.
* etc.


So, we met about this about 6 months ago and started an endeavor to move documentation into the product itself. Right now, if you go to https://github.com/2600hz/kazoo and while the screen is open, push the letter 't'. Then type "doc". You will get a list of doc folders and locations. If you strictly want API documentation, which I'm guessing is what you want, check out https://github.com/2600hz/kazoo/tree/master/applications/crossbar/doc which contains documentation on each API crossbar supports. Note that not all APIs are available on the shared hosted environment.

Why are these in Github? Why is it better? A bunch of reasons.
1) It supports Markdown format, which is common
2) You can edit things directly on the site and submit them back for inclusion in the docs
3) It's version controlled. The docs on branch 3.22 will be what was programmed/available on 3.22
4) We've built a crawler that takes these files and turns it into a nicer, more polished website (well, work in progress, but pending)
5) You can skin it with custom CSS / HTML later and call it your own!

We will likely eventually expand this out to more then just API documentation, such as including tutorials and other items.

Give it a try. It may be scary looking but it's actually really easy to do.

You can reference James's post on the Google mailing list about the more intricate details of how this works:  https://groups.google.com/forum/#!topic/2600hz-dev/qKKrHh0Aznc . 

[Logicwrath]

Thanks.  I will consider submitting inclusions if necessary.  I have mostly been able to find API documentation between the Google Dev group and the different project related websites.

I was thinking more about community related configurations documentations. For example: How to properly configure a Yealink or Bria phone with DNS-NAPTR or How to create a simple pivot script that enables specific functionality that gets requested.

Addtionally, I will be posting things from time to time in the forums on how to do something specific and it would be nice if it was open for users to improve and versioned.  Reading a thread on how to setup something and then having to read 20 more threads with improvements or bug fixes is more work than a versioned user submitted how to article.

[Darren Schreiber]

What if we create a set of Github folders for this? Someone started such a project that they were calling the Great Book of Kazoo which we're considering including for this very reason. It would use the same strategy - you'd chat on here, but you'd update the permanent docs via Github on, well, Github. That way we get the benefits of versioning, ease-of-use, being able to download it, and we can run it through a script which formats it and makes it look pretty.

Is that not sufficient or is it just too foreign a concept over a Wiki? The reality of the Wiki is we had one before, and people submitted mostly junk, often anonymously, and it required constant work to keep it up to date, had no versioning, and was work for us to maintain the site itself.

[Logicwrath]

I think Github would work fine for me.  I don't typically use Github and I tend to be more of a hobby programmer and copy/paste/hack kind of guy so it would be best if there were at least a couple sample submissions so I could get an idea on how things should be included and formatted etc..

I think another important piece is having a big obvious link somewhere in the community to this location so other people get involved.  For me Github is fine, however, it might intimidate other folks and it would likely not get used if it was not searchable in the community or at the very least prominently showcased.

When I read my response, I think the important detail is having it searchable in the community so more people get involved, but I am just guessing.

[Darren Schreiber]

I appreciate your comments, and I agree! That is infact one of the reasons we're leaving Confluence - we can't modify the nav bar!

Very shortly (hopefully by end of week) we will be rolling out a new website. The new design has nav links that go to all resources, and the nav bar will be available on almost everything we do. It will hopefully make things much easier to find. That's the goal, anyway.

[Darren Schreiber]

Also, once the roll-out is complete, we'd love you to look at it again and provide feedback. If it's worse/better and if there are more improvements possible.

[Logicwrath]

Yes, I will review.  I am working on something right now, that I planned on posting in the forum, maybe it will be a good fit for this new section on Github.  Thanks!

[FASTDEVICE]

Darren, on a side note...at some point your business model is to support 3rd party applications through an apps store of sorts. Where can resellers that develop these apps or layered services that extend 2600hz offerings appropriately begin discussions? I'd like to get feedback on what my team is building and perhaps have the community drive some of the direction.  

[Darren Schreiber]

Hi there,
     We are literally writing two documents right now, so good question!

1) A partner program, for people who want to CONTRIBUTE code back to the project. The idea is to give you credit for what you contribute which you can use for consulting, hosted services, etc. That way people are encouraged to contribute more. Right now there's a huge lack of contributions and I blame us for not making it easier and rewarding so we're working pretty hard on that.

2) The App Store program. As you can see, in Kazoo UI we had a thing called App Store that was anything but, but we've always had that idea. In Monster we actually flushed it out. Now we're working on the transaction services behind it and rules for using it. If you have an app you already want to put in, contact me offline and maybe you can trial the idea with us. The apps would be available to everyone - open-source and closed - who use the platform.


As for the original question re: wiki/documentation, we discussed this internally. We discussed Confluence (which we used before) but it's sooooo hard to modify the HTML/CSS/etc. unless you run your own copy, which we don't want to have to manage (it's a beast of a Java program with constant security patches and such). So we think we're going to use Github's Wiki service. It lets you edit online in the browser, or offline. Only thing it doesn't have is easy image attachments, so I'm still looking around.

[Logicwrath]

I think your first point is great.  The more people contributing the better.  It would also be nice if people could earn these credits for other things besides specifically contributing code.  I want to impact the community, however, I may not be qualified to write code for Kazoo.  At the same time I may be able to provide helpful posts, documentation, and/or code snippets (think pivot) that overall improve the community.  Perhaps these non-code related contributions might be worth some support credit or bug fixes in the future if you think that makes sense.  In any case I think you are on the right track.

[Darren Schreiber]

Oh you are so right, and I am so sorry! Yes, that is exactly our plan. In fact, the only reason we bought THIS CURRENT system that you're on was for the forums + credit/karma point system they had. That was our original goal, was to use this system to track participation points. Unfortunately it doesn't let you "spend" them and I can't manually modify them or whatever.

But yeah our thoughts were:
- High point values for Erlang code contributions.
- Medium point values for Bug Fixes, Scripts (like Bash helpers, etc.), Tutorial Contributions, Documentation Contributions
- Low point values for correcting typos, helping us organize meet-ups/events/etc, correctly answering people's questions in forums, etc.

We kind of want to model this off ExpertsExchange or StackOverflow as a concept.

[Logicwrath]

This sounds great.