TIP: Use Markdown or, <pre> for multi line code blocks / <code> for inline code.
These forums are read-only and for archival purposes only!
Please join our new forums at discourse.kohanaframework.org
Documentation revamp
  • I talked to Zeelot a couple of weeks ago to contribute to the docs., revamping the content, reorganizing the pages, etc.

    Here's a gist file with the TOC https://gist.github.com/feketegy/6365298

    You're welcome to comment and contribute to it.

  • Need add section "modules" and move there items 3.6, 3.8 and add part about creation modules. Also nothing about coding style http://kohanaframework.org/3.3/guide/kohana/conventions . Theory before practice: install and config after "Cascading Filesystem"(without files parts) and "Conventions and Style"

  • @WinterSilence in 3.6 and 3.8 we should talk about how to load those modules in and how it all works in KO, not about the detailed Database and Minion modules itself.

    Coding style will be in 1.3. Contributing section (coding guidelines). If a developer just wants to use the framework and not pushing back anything to the main trunk, then he is free to use whatever coding style he wants.

    About modules creation, yes, you're right, we need to add a section for it. Maybe under 5. Advanced Usage. [EDIT] Added under 5.4.

  • 3.6 \ 3.8 not in core now, therefore i move their in another section. Сhange section order, as example: Database\Request Handling\ is more often used than Logging \ Error Handling. Move up 3.3. Autoloader because its theory part.

  • Awesome stuff @feketegy! Keep up the good work!

    You probably need to add a section about Unit testing.

  • I see you have added unit testing under contributing. I was referring about how to unit test your application stuff. It probably needs a main section alone.

    Also, a section about the user guide, since it is an official module, probably under Creating Modules. Mainly, because you need to document your module.

  • @enov I think how unit testing your application is out of the scope of Kohana's documentation... if somebody want's to contribute to the project, then he should be informed that unit testing is required and how to unit test specifically for Kohana.

    As for creating modules, it is added under 5. Advanced Usage

  • Unit testing in general is surely out of scope for kohana's documentation. If anything, a small page on how to bootstrap it would suffice.

  • Good job @feketegy ... are you planning to make this go into the /guide ?

  • Samsoir's articles should definitely be referenced if they aren't already.

  • @Jack Ellis can you add the links here?

  • I'm wondering about those too, I found a slideshare that was very interesting (albeit a little old, 2011, mentioning KO 3.1). I'm happy to see someone wanting to focus on the userguide, shouldn't Localisation be included in the guide (even mentioning how Validation messages are found, because I had to find out from reading code a clear guide could really help beginners).

    If there's any help needed to write a guide I'd like to give a helping hand.

  • I'm going to be a little reluctant to include links to third party sites going forward… we've had those in the past and when they go down or are moved, we get a bunch of complaints about our documentation linking to dead sites. One of my next goals is to start working on an official blog where people can submit articles as pull requests.

  • Yeah, not third party links pls.

  • Cool, we could remove it, but as I mentioned in the gist, the tutorials would be curated. I thought that we put the content into the guide and also add a link to the original source URL.

    But, the blog with pull requests is much cooler imho.

  • http://www.yiiframework.com/wiki/ we could do something like that, if article data not actual members sets
    minus rating and admins fast find old\bad articles. Also maybe take wiki engine for this?
    Need add translations of user guide and subsequently api guide.

  • We can worry about other languages after we have decent enough documentation in english :) one thing at a time.

  • @Zeelot3k of course, but need to create a plan of action. maybe add individual tracker for guide? now it is difficult to understand which sections need to be improved.

  • Source code is written in english, documentation will be for now. As @Zeelot3k said, when we have a decent documentation than we should worry about translating it.

    As for a "plan of action" we just modify the route (e.g. /3.3/guide/en/ or something like that) when that time will come :)

  • +1 for adding translations in the user guide.

    @Zeelot3k, @feketegy

    one thing at a time

    A doc revamp can take months if not years, in case it ever gets done! It's an ongoing process. It's good to start translations when there's a finalized TOC ready.

    Officially translated docs can attract devs, with little English knowledge, from all around the world. And that's our main goal. After all, the docs are not meant for those who write them. Appointing overseers over each language could help the process. Maybe @biakaveron can oversee the Russian?

    @WinterSilence How can we have translations in API guide? Multiple translations in source code comments ?!!?

  • @enov @biakaveron already started translate documentation (somewhere came across a link), also ru community have http://kohana3.ru/ and http://kohanaframework.su/. Current guide support multi language, but i think use wiki engine is fastest and most convenient way, see link on yii wiki.

  • I think everything that's not under kohanaframework.org domain should be considered "unofficial" and shouldn't be supported by the dev. team. This way we can improve consistency. If you wrote a translation you should consider making a pull request (if that's will be available) or talk to someone from the dev. team to merge it in so it will be available on kohanaframework.org

  • @feketegy I just suggest to combine materials from these resources and official guide. If there is no free development on the basis of this site, users will create their own resources, or even go into the other project due to lack of information. Several people who are responsible for the kernel can not physically keep track of all.

  • There's nothing wrong that users will create docs / tutorials in other languages, but to keep the consistency between translations we need first to have a decent enough documentation in english, than think about translating that content into other languages.

    We should cross that bridge when we get there.

  • @feketegy everyone understands that the omelette without eggs don't, why are you repeating it over and over again?

  • @enov @WinterSilence Are you talking about http://101.brotkin.ru? Its not a translation, just my own articles :) But I would be happy to include them to official (russian) userguide.

    +1 for @feketegy, we need stable english guide before creating other translations.

  • Fair enough @biakaveron. @feketegy hope you succeed in healing the Achilles' heel of Kohana.

    @WinterSilence is that a yummy russian omelette you're referring to?

  • @enov I think @WinterSilence is referring to the old saying "you can't make an omelette without breaking eggs" that translates to "it is hard to achieve something important without causing unpleasant effects"

    In case you were being sarcastic, pardon me.

  • lol, @vev, sarcastic is probably not the exact word, I was trying to add some humor. If that sounded sarcastic, then let @WinterSilence pardon me!

  • @vev @enov confused it's true, but i just meant that there is no need to explain the obvious things.

  • How is this coming along?

Howdy, Stranger!

It looks like you're new here. If you want to get involved, click one of these buttons!

In this Discussion