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
Docs: User Guide Layout Style
  • I want to get an idea of what people prefer for the user guide layout style.

    I am NOT referring to css styling, but to the structure of a user guide page.

    There are already three ways of doing this in the user guide. Below are three good examples, they each present similar info in different ways.

    Which one do we want?

    1. ORM example Lists methods by method name , No method enumeration, method code example usage.
    2. Validation example Lists methods by method description. No method enumeration, method code example usage.
    3. Cache example Lists methods by method description. Full method enumeration, method code example usage.

    Remember we have API documentation, see for example cache API

    If you have a firm opinion, please just vote +1 or +2 or +3

  • +2 but with close ties to the API, there's no need to duplicate it

    I have an idea for a new structure for the docs (organisation of pages, not what's on each page like this) that ties the user guide and API together, i'll make a new thread when i've got a working example.
  • +2

    (As mentioned by Pugfish, if nicely integrated with the API. I also like 3, but it's a massive amount of duplication, for something already produced automatically)

  • +2 like PugFish said, close ties to the API. Linking to it in a structured way or something. API could be moved to api.kohanaphp.com and Kodoc could implement the new website design.

    Must be said that the '2' format mostly applies to libraries. Helpers, by nature, have a more API like documentation whereas library documentation should be more explanatory of the entire library instead of focussing on single methods.

    I would also be in favour of changing the structure under the general heading. Now it acts like a reference and not so much as a guide. It could be used as a more of a step by step introduction to various Kohana aspects, i.e. you start by reading the topmost article and then downwards and when you reach the end you know all there is to know about Kohana in general.
  • @dlib : agree about structure, reference versus guide.

    I should wait to see what Pugfish has in mind, but I was thinking perhaps a navigation block should be placed in each page.

    Say you are reading general: routing page, then something like this, to make finding your way around a bit easier.

    Previous [URLs] Top [toc] Next[Loading]
    
  • +3 yep
  • Posted By: dlib

    Must be said that the '2' format mostly applies to libraries. Helpers, by nature, have a more API like documentation whereas library documentation should be more explanatory of the entire library instead of focussing on single methods.

    I would also be in favour of changing the structure under the general heading. Now it acts like a reference and not so much as a guide. It could be used as a more of a step by step introduction to various Kohana aspects, i.e. you start by reading the topmost article and then downwards and when you reach the end you know all there is to know about Kohana in general.



    +2

    I think structuring the user guide into some form of top-down approach would be great. The current format is difficult for new users to follow, if you are unfamiliar with the framework. CodeIgniter gets around this with their Getting Started page. Maybe the top half of the user guide page can be converted to top-down style and keep the reference section as is.

    For helpers, the API style definitely appears appropriate, but maybe a short introduction on when and how to use the helper. Along with some practical examples of actual helper usage.
  • I'm a fan of +3
  • I like #2 but also like to see the method enumeration to be on the same page. If captions of the API corresponding to the right topic of the documentation could be integrated in a way that is collapsible/expandable on the same page, then for me that would be the perfect solution. Then again, perhaps just a link to the corresponding API section would suffice. Either way a clever integration between the two would make some wonderful documentation.
  • +2

    There are links to php functions. Why not similar links to Kohana methods?

  • +2 but both 1 and 3 have their advantages.(clarity and depth respectively)

  • I like 3 and 2, i think 3 is a better choice for beginners though as it shows abit more of the flow for what you need to do.
  • +2

    I am still new to Kohana (and Php in General) so i have been using the documentation extensively.

    I like having a 'Getting Started' Section at the top directly after the Introduction, 9 times out of ten that will answer 90% of what i need to know :)

    IMHO the Getting started should not assume anything, so if there are pre-requisites then they should be clearly listed and linked in.


    Helpers by there nature are a different kettle of fish, there does need to be a section for each method, however there is no need to just repeat what is in the generated API....after all thats what the api is for.....

    I would expect that experienced users would refer to the API while newbies like me refer to the guide.
  • +3 with additional information like in 2

    Additional information: Article Tutorial Tutorial with Captcha and the links sprinkled throughout the document.

    The more links the faster you can get your head around a new concept or refresh your memory about something previously learned.

  • +3

    It's good to be able to quickly peak and find a function name you forgot.. Even though there is the reference for that, I'd rather not have two documents open..

    I understand the concern of repetition, but why not have it mirror the ref dynamically?
  • +1

    with a long code example, as at bottom of 2, that puts usage into a definite context. although both 1 and 2 have a getting started section which is very useful.

    what would be really helpful when first getting to grips with it all would be a complete Kohana application that you could download and examine, one that had MVC and ORM well done (with a simple non-ORM db access alternative), although I know you are working on this so all good.

  • +3 looks good. Helpful to new users way to increase the users as well and grow the community.

  • +3 and +2

    Why not:

    • generate a style 3 reference (with phpdoc or similar) at api.kohanaphp.com
    • use style 2 for the docs at docs.kohanaphp.com and tie it in to the API reference.
  • +1

    This style clearly defines all the methods and allows for a quick look up, but provides code samples at the bottom. Style 2 reads too much like a tutorial and Style 3 I'm undecided on.
  • My thoughts?: I think it's also very important to ship a copy of the html-version Docs with each release. At the same time, keeping the online version of the docs as updated as possible (maybe even trunk ready). I agree with +1 being quick and detailed. it also seems quick to update. I feel +3 is to wordy for both beginners and veterans and it might be harder to keep updated.
  • I think from a UX perspective Kohana's documentation should emulate the layout of the PHP documentation. I'm sure every Kohana developer is familiar with the PHP documentation, ease of use, ease of lookup but also the community element with examples and tips added to the bottom of each page. Therefore, I'd like to see an overview page with each method and property given its own sub-page and the version number clearly marked so we know what's deprecated and what's relevant.

    I'm a newbie and have already been caught out wasting time trying to get old functions to work. It took me a while to find out that v2.1 or v2.2 methods documented on the 'official' Kohana site were no longer in the v2.3.4 release. I believe that good documentation is one reason Kohana hasn't become more popular as it steepens the learning curve and makes the framework look unprofessional at first glance, which is a shame. It would be nice to see v3 being released with a new documentation site.

Howdy, Stranger!

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

In this Discussion