Kirki: Documentation format or structure should be better.

[ghost]

Issue description:

Version used:

Using theme_mods or options?

Code to reproduce the issue (config + field(s))

[aristath]

If you have any suggestions I'm all ears!
The docs are a complete rewrite and everything you see has been written in the past week, so yeah, it's not perfect.

But criticising something without offering any solutions or advice on how to improve a situation is not that helpful.

What would you like to see? What do you think would be helpful in the docs and how would you structure them if you were the developer?

[rahulv3a]

@himelkazi Kirki is an open source plugin. People put a lot hard work, time, and effort and then share it with everyone for free.They are not earning anything from this. In my opinion, one should think twice before criticize it. As @aristath pointed out, criticizing something without offering any solutions or advice on how to improve a situation is not that helpful.

@aristath I'm working on a project. It would take around 2 months to finalize. If everything goes well, once it's finished, I will be able to help you with Kirki. I'm willing to contribute, but my programming skills are not as good as yours. Now I think maybe I can help you with the documentation and possibly GitHub issues :+1:

[dameer]

There's absolutely nothing wrong with the documentation, Kirki is far more better documented than many other commercial plugins. It's not about "bad user experience" mr. himelkazi, it's about bad user attitude.

[enkota]

The documentation has improved a lot in the past week, I agree with @dameer, there's nothing wrong with it. @aristath has put in many many hours into this project :+1:

[ghost]

First of all, I want to thank the developer's for this open source project. don't understand why all of your are being so furious :( here I am not for criticize your plugin or something like that. I am not much experienced with customizer, so as a new comer I find nothing here for me like how to getting started or how to use it as a library. The most annoying things ( for me ) is it document as a file and lots of split. Its totally awful to searching into documentation folder and back and search.... just wasting lots of the to do it. So that's the point. If you think it's easy to use and smart enough then I nothing have to say. If you want to know some well and user friendly documented plugin, CMB2 Advanced Custom Field are I like to say. Anyway I felt sorry for kirki Author if my word make him heart ( actually we are from different place to it's common to think ) . Honestly I don't criticize the plugin ( haven't quality to do that ). Today I can't use it just for the doc but I know currently it is the best wp_customzier plugin of the planet. Hope I can use it future and I am going to delete the issue soon. Thank You

[aristath]

The most annoying things ( for me ) is it document as a file and lots of split. Its totally awful to searching into documentation folder and back and search.... just wasting lots of the to do it. So that's the point.

I agree, the way the docs are presented is wrong.
But this is just the beginning... Right now I'm writing the docs that will be included in the plugin, and the most efficient way to do that is by writing simple .md files so that users can browse them on github.
As soon as this version is released I'm planning to include the docs in the site in an easy to navigate manner.
So the navigation/browsing the docs will be fixed in a few days.
However, what I would like to know is about the docs themselves.
Did you find something missing from them? Besides the presentation/browsing issue, do you think for example that the documentation for the checkbox field is adequate? https://github.com/aristath/kirki/blob/develop/docs/controls/checkbox.md

What would you like to see added in the content of the docs?

Anyway I felt sorry for kirki Author if my word make him heart

Don't worry about it buddy, I just wanted to know what it is exactly that you thought was bad about the docs. And I agree with your point, that's why we'll fix that in a few days. :+1:

Thank you for your feedback, I really appreciate it!! :smile:

[Thomas-A-Reinert]

Hey aristath, you may want to take a look at https://github.com/tripit/slate . That´s probably the best documentation format for code I´ve ever seen. Thanks for your effort!

[enkota]

@Thomas-A-Reinert That is a very nice doc format, thanks for sharing!

[aristath]

@Thomas-A-Reinert yeah, I've used Slate in the past to build the docs for some of my themes too...
I'm still thinking how to format the docs to be honest. The thing I don't like that much on Slate is the fact that it's basically a single page and URLs are using hashes.
I'm also considering something similar to https://10up.github.io/Engineering-Best-Practices/markup/
In any case, it's gonna be built using Jekyll (both of them use Jekyll so they're fast, static sites built using .md files) which is why I started building all docs using MarkDown :+1:

If you find any other examples of documentation sites that look nice let me know!

[ghost]

Actually I think the original docs were slate Aris? If not it looks similar.
I didn't think the OP was too off, I think if anything it was just a
language barrier as I can clearly see English is not native tongue for
Himel. Sometimes things that non english people write seems and can be
misconstrued as offensive. Will be interesting to see what format you use
for the docs.

On Mon, Mar 14, 2016 at 10:24 PM, Aristeides Stathopoulos <
[email protected]> wrote:

@Thomas-A-Reinert https://github.com/Thomas-A-Reinert yeah, I've used
Slate in the past to build the docs for some of my themes too...
I'm still thinking how to format the docs to be honest. The thing I don't
like that much on Slate is the fact that it's basically a single page and
URLs are using hashes.
I'm also considering something similar to
https://10up.github.io/Engineering-Best-Practices/markup/
In any case, it's gonna be built using Jekyll (both of them use Jekyll so
they're fast, static sites built using .md files) which is why I started
building all docs using MarkDown [image: :+1:]

If you find any other examples of documentation sites that look nice let
me know!

—
Reply to this email directly or view it on GitHub
https://github.com/aristath/kirki/issues/730#issuecomment-196277250.

[ghost]

Actually, what happened to the original wiki and documentation Aris? It was simpler to find the instructions on what you had before. I see it is no longer on your main site. I see that you have been updating the md files here https://github.com/aristath/kirki/tree/develop/docs

Is that because you can use the md files in some other way later?

[aristath]

I didn't think the OP was too off, I think if anything it was just a
language barrier as I can clearly see English is not native tongue for
Himel.

Yup, I agree. English is not my native tongue either, so I completely understand.

Actually, what happened to the original wiki and documentation Aris? It was simpler to find the instructions on what you had before. I see it is no longer on your main site. I see that you have been updating the md files here https://github.com/aristath/kirki/tree/develop/docs

Is that because you can use the md files in some other way later?

Yeah, you guys just caught me in a transitional state.
The docs from the wiki were removed because a lot of things there were just wrong. The docs had not been updated in about a year and I wanted to start from a clean slate, get it right this time.

For the time being the docs are included in the repo so that people can examine them and help improve them, provide some feedback about what they want, what's missing and so on.
But they won't stay there...
I don't think that keeping the docs in the plugin is wise. Most people embed kirki in their own theme anyway (which I think is a bad idea but that's not the question here) so including them in the repo makes no sense.

Eventually the docs will be in their own branch (the gh-pages branch) and will be included in the main site. I just need a few days to find the right format and theme them properly. The kirki.org site is generated from the gh-pages branch and hosted here on github, so I just have to just build the new site and embed the docs there...

Actually I think the original docs were slate Aris? If not it looks similar.

Once again you're right. But Slate also requires its own repository, it's can't be in the same repo as Kirki because the docs are on the master branch and then automatically deployed to the gh-pages branch. Which is why at some point there was a separate kirki-docs repo (no longer exists).
It's brilliant, but in this case it won't do what I need.

Will be interesting to see what format you use for the docs.

I started working on a theme using foundation about an hour ago... we'll see how it goes. :+1:

[aristath]

OK guys, I just published a 1st draft of the docs: http://kirki.org/docs/controls/checkbox

But I'll need your help if I'm gonna get this right...
Since you're the ones using it for your projects, I need to know what you're looking for in the docs. What to focus on, what to get rid of and so on.

Any advise is welcomed.

[rahulv3a]

@aristath I think Example and Usage should be above Arguments. Other than that, it looks good to me :+1:

[aristath]

ok, fixed that too (along with lots of other things... :+1:

@himelkazi What do you think? The new docs are on https://kirki.org/
Let me know if you think I should improve or change something to make these better. :)

[aristath]

I think it's safe to assume that with the new docs this is no longer an issue. :+1: If any of you have not seen them yet, they're on https://kirki.org

If there are any issues with the new docs, feel free to submit a pull request (there are links all over the place to improve the docs), or just open a new ticket here.

[enkota]

Looks brilliant @aristath good work :+1:

Edit: Oh i forgot to say there is a small typo on the image page - https://kirki.org/docs/controls/image.html

Under 'usage' - get_theme_mod

<?php $image = get_theme_mo( 'my_setting', '' ); ?>

[aristath]

Edit: Oh i forgot to say there is a small typo on the image page - https://kirki.org/docs/controls/image.html

Thanks, fixed. :+1: