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 improvement.
  • Hey guys, we want to start improving the Kohana 3.x documentation, so we want to ask your opinion on some things.

    1. What are some things that you can't find at all in the documentation?
    2. What are some areas of the docs that should be improved?
    3. What parts of the unofficial wiki should be included in the docs, and where should it be put?


    Using your feedback, we will make a list of changes to be done, then people can volunteer to contribute and get those changes done!
  • To start of the discussion:

    Missing/Improvement: The docs could include a very thorough example of ORM including using Auth. It could show all relationship types and how to add and remove relationships, how to use rules and filters effectively, etc.

    Improvement: Messages could be improved to explain that message files can be in subdirectories, and that you can use nested arrays using dot separated values. Example:

    <?php echo Kohana::message('folder/file','foo.bar.baz'); ?>

    From the wiki: The Pagination module guide could be included as a tutorial.

  • ORM documentation should provided in the ORM module itself, most documentation should move this direction (eg: Database, Pagination).
  • I'll be sure to coordinate that all the changes happen in the modules they apply to.
  • What are some things that you can't find at all in the documentation?

    Common mistakes, things to avoid and other helpful tips.

    What parts of the unofficial wiki should be included in the docs, and where should it be put?

    None, because of possible licensing issues. Be careful about taking content that isn't yours.

    1. Menu section should stay expanded for the section you're on.
    2. I feel like the API documentation is a waste of space.
    3. Cookie and Database pages under security are blank

    I can't put my finger on it, but the guide doesn't inspire me to read on. Compare it to the Rails documentation and it's just depressing. Woody, is this part of the website re-design?

    I would be happy to work on any of the points I've made.

    I agree with what Woody said too.
  • All of the valid tutorials should be moved over, especially the sections on Routing.

    A deployment section, similar to the one that I put together for 2.3 (http://docs.kohanaphp.com/installation/deployment) would be useful.

    Are there are plans for an "official" wiki for community contributed tutorials?
  • None, because of possible licensing issues. Be careful about taking content that isn't yours.
    I should have been more clear that it wouldn't be copy/paste, but rather like a general idea. Like, the wiki has a good guide on Pagination. The official docs should as well, and we can probably use some of the ideas from the wiki, just not copy/paste it.

  • > Woody, is this part of the website re-design?

    No, the user guide is not included in the redesign. Stylesheet patches welcome! I know bluehawk has a different color scheme for the user guide...
  • i think documentation should give some basic usage sample
    just like unofficial wiki

    maybe i can do some help for KO3 :)
  • What is the intention of the annotations via Disqus? It seems to get various kinds of posts, some of which would be more likely to be seen in the forum. A standardised use of this facility - e.g. code examples only - would make sense.
    While trying to use Ko3, I found I was usually able to get the necessary information but only after looking in two or three different places. I think it would help everyone if the devs - probably Bluehawk - spelled out a clear intention for some scheme for consolidating and standardising the docs. Everyone will have their own ideas, but democracy only works within an overall framework.
  • I agree with Martin, I think some kind of document outline for the userguide would be really useful. That way anyone who wants to help could see what topics need adding or expanding.

    It would also be helpful to know which topics are already being worked on by others, to avoid a duplication of effort, and to have some kind of style guide (even if this is just an existing entry which can be held up as an example) to show what standard of documentation we're aiming for.
  • I completely disagree Zicon. Nobody is asking to write a fancy text or "articles". Create a weblog if you want to do that. As long as the function is there style can come later. People are not exactly complaining that the documentation isn't fancy enough.

    If you really want some sort of "how-to-write-text" guide you can check the one on wikipedia and just follow the Kohana conventions for any code snippet.

    I hate to be mean, but if you want to do it, then do it! don't just talk the talk. We could debate on how to best write a 3 word sentence for months, and it won't help anybody. If you want to make it as perfect as possible, write a draft and post it here as a thread for feedback. You can't just "guess" all your problems.

    Right now I'm reading your posts as: "I want to help write some of the documentation, please write a 100-page documentation on how to write documentation."
  • @Akki: I'm sorry if my comments came across that way, but that's not what I intended. I'm just suggesting that an existing article could be mentioned as an example of what standard of documentation (in terms of level of detail, not writing style - that's not what I meant) is being aimed for (the validation section, for example?). Every project out there does their documentation differently - Colonel-Rosa mentioned the Ruby documentation, for example - is that the kind of docs Kohana should aspire to? I don't know, but surely it's a question worth asking?

    I'm not looking for anyone to hold my hand, and I'm sorry if it came over that way - it's just the first time I've tried contributing to an open-source project and so I've no experience of how these things are done.
  • @Akki: I think you are misreading LordZicon's posts. He and I are asking for leadership, discipline and co-ordination to avoid wasted time and effort. The "if you want to do it, then do it" approach will always mean wasted time and effort, either at this end or by increasing the devs' burden of sifting and collating the results.
    You are saying "We want you to do something, but we're not telling you what it is".
    For example:
    Has anyone asked kerkness about incorporating some of his unofficial wiki in the User Guide? Or do you think a couple of dozen different people should ask him? Leadership, discipline, co-ordination. It has to come from one or more senior devs.

    @bluehawk: I'm absolutely not sniping at you; your original post raises specific points and it's good to know someone is taking this on. But inviting general feedback on what can be a very detailed and nit-picky topic will give you more grief than strictly necessary.
    Can you tell us the following:
    A. Will the User Guide by expanded in its present form, by filling in - even on a "draft" basis - the existing gaps?
    B. Kerkness unofficial wiki - see above.
    C. What is the status of the disqus.com annotations?
    The answers would give me a clearer picture of where you are and where you're headed. Above all, thanks for the work you and the others do. You should know that it's appreciated.
  • Every project out there does their documentation differently
    But documentation is still documentation. Really, you can just write stubs with only all the necessary information and no pretty wording attached, and that would be immensity helpful to the community.

    Every project out there does their documentation differently - Colonel-Rosa mentioned the Ruby documentation, for example - is that the kind of docs Kohana should aspire to?

    The rails documentation looks a little different then what the current documentation looks like, so from my perspective this is a weird question you're asking. Do you want to write documentation, or do you want to re-write documentation (meaning the current one as well) into something else?

    Its fine if you want to re-write it - but just make it clear which is it, since I'm really bad at guessing. :)

    I'm just suggesting that an existing article could be mentioned as an example of what standard of documentation (in terms of level of detail [...]
    I don't see a reason why anyone would want it "less detail". :) Just use common sense when writing it. Reader is assumed to be totally new to the topic and you progressively fill him in (using whatever means avaiable: images, code snippets, etc.), that's all there is to it. As for examples: http://dev.kohanaframework.org/projects/userguide3/repository/revisions/master/show/guide

    He and I are asking for leadership, discipline and co-ordination to avoid wasted time and effort.
    Its not that I'm against planning (actually quite the opposite), but I feel you have a really inefficient plan that is too "idealistic". Making a plan more complicated does not make it better.

    What you're currently doing is:
    * ask for "how-to-do-it" (time: whatever the turn-around-time on the forum is)
    * debate on how to do it perfectly (time: forever)
    * write it perfectly (supposedly)

    When, what I think you should be doing:
    * write a drafts using the current articles and common sense as a guide
    * ask for proofread/feedback/corrections/suggestions here
    * submit it
    * update it based on user comments, etc. (should they come)

    Maybe it's not the most efficient way, but it should be the fastest way to get it to those who need it! Isn't that the important part?

    You are saying "We want you to do something, but we're not telling you what it is".
    Well, if you want to do it, I'm assuming you actually know what it is you want to be doing, and have some faith in your own skills. If you don't know what you're doing, don't do it. ;)
  • > The rails documentation

    He said ruby, not rails.
  • Colonel-Rosa linked to this one: http://guides.rubyonrails.org/action_mailer_basics.html which is the rails documentation, so I assume that's a typo.
  • Well, someone is confusing things either way ;)
  • @zombor: typo on my part
  • Edit:
    Was gonna say something else, but changed my mind.. the time would be better spent writing docs ;)
  • What you're currently doing is:
    ask for "how-to-do-it" (time: whatever the turn-around-time on the forum is)
    debate on how to do it perfectly (time: forever)
    write it perfectly (supposedly)


    That bears absolutely no resemblance to what I actually said.
  • LordZicon wrote:
    I agree with Martin, I think some kind of document outline for the userguide would be really useful. That way anyone who wants to help could see what topics need adding or expanding.

    We are working on a new Table of Contents for the userguide, mostly just refining the current Table of Contents, adding things that are missing, etc.

    LordZicon continued:
    It would also be helpful to know which topics are already being worked on by others, to avoid a duplication of effort, and to have some kind of style guide (even if this is just an existing entry which can be held up as an example) to show what standard of documentation we're aiming for.

    We will probably be using Kohana's redmine to track what pages still need work (each page could have its own issue/ticket, to help stay organized), and people can link to a commit in their own fork of the docs. If someone posts a commit that we don't feel are up to the standard, we can give them constructive criticism and help them improve it.

    As for standard of documentation, we will try to aim for having lots of sample code, pictures (if it will help), and clear concise descriptions and explanations. It should be easy for someone who is new to Kohana or MVC frameworks to understand the docs, although we can assume they have a solid understanding of PHP.

    Martin Hall wrote:
    [LordZicon] and I are asking for leadership, discipline and co-ordination to avoid wasted time and effort.

    This is the plan. :)

    But inviting general feedback on what can be a very detailed and nit-picky topic will give you more grief than strictly necessary.

    The question I wanted answered in this forum post was "what areas of the userguide are lacking? what areas do you think could benefit from the wiki? etc." but unfortunately it seems to have derailed into a meta discussion about writing docs :/

    Can you tell us the following:
    A. Will the User Guide by expanded in its present form, by filling in - even on a "draft" basis - the existing gaps?

    At this moment the plan is to finish the new Table of Contents and then work on moving the docs from the wiki and the old userguide into the new one, making improvements where necessary.

    B. Kerkness unofficial wiki - see above.

    I will contact Kerkness. We absolutely won't be copy/pasting anything from the wiki, but it is a good place to look to answer "what kind of things should be covered in the docs or on this specific page?" The wiki seems to be a place where users could say "Man, I wish there was a better description of how XYZ worked, so I'll go write it." We don't have to copy and paste, just be sure to cover those topics well in the official docs.

    C. What is the status of the disqus.com annotations?

    Good question. I would prefer similar content to what is found on the php docs, where people post useful functions or tips. Perhaps a message right above the disqus edit box that says "Don't use this to point out errors/typos/suggestions for the docs, please file a bug (link to redmine). This should be used to provide additional commentary or code samples pertaining to the topics on this page." It would become annoying to have most of the comments be "this should be fixed" followed by "okay we fixed it".
  • Very many thanks, Bluehawk. I'll come back when I've digested all this.
  • @Bluehawk:
    1. I agree with you on the disqus.com annotations. Presumably not all of the existing notes will be retained, in which case I would volunteer to look through them and submit recommendations as to which ones might be dropped.

    2. I should have mentioned this earlier: is there a definite commitment to .md files for the User Guide, and if so is there a basic commented template anywhere?

    3. Point 2 leads directly to my own limitations: Kohana's "contributions" facilities are too varied and too difficult for me. Clearly not everyone has this problem, but the simpler something can be made then the more likely it is that people of all abilities will use it.
    I see github, redmine, user guide not html, forum bug thread (where the response is usually "raise a ticket"), and I tend to give up. As I say, my own limitations are not (thankfully!) universal; but there must be others who would be more help if the process could be simplified and standardised.

    4. I have looked at revising the database tutorial, as I think that the format is hindering understanding. (The same thing applies elsewhere, I'm just using the db tut as an example.)

    For example, surely this (paraphrasing):

    Databases

    Making Queries

    Prepared Statements

    Query Building

    would be better like this:

    Databases

    n. Making Queries
    1.Prepared Statements
    2. Query Building

    etc. etc.

    Again - if such a thing exists - a standard template recommendation for user guide .md files would be useful here.

    I hope at least some of this is helpful.
  • @Martin Hall

    1. Concerning the discus comments, putting a warning similar to the one on the jquery docs is what I had in mind, and then deleting existing or new comments that fall in that category. Your help in cleaning those up will be appreciated, when the time comes.

    2. Yes, I think we are pretty set on markdown. It is much easier and quicker to write/format things in markdown. What do you mean by a basic commented template? If it helps, here is a markdown guide I wrote.

    3. I agree that it can be difficult sometimes, but in order to stay organized we have to use some kind of version control and/or issue/bug report/feature request system. If, for example people just posted things they wanted changed into a forum thread or something, someone would have the job of going through each post and applying the changes, which wouldn't be fun. If you don't know/like git, you could post as an feature request on redmine. Learning git (or any version control) and redmine (or any project management) are good things to know anyways, so it's not to much to ask I think.

    4. The database guide will be many pages that go in much more detail, rather than a single confusing page.
  • @bluehawk that markdown guide is simple and effective.

    On long pages such as http://kohanaframework.org/guide/tutorials.orm I think it would be helpful to have an index at the top so we can jump down to a specific section. The 2.3.4 docs did this.
  • @slacker

    Pages like the database and orm tutorial were added because there was a lack of docs for that, but they are in the wrong place, under the wrong name. They aren't a tutorial, they try to be comprehensive docs including examples, all on one page. Soon, each of those modules will include their own docs, with multiple pages, etc.

    An index is a good idea though.
  • @Bluehawk:
    Thanks for the markdown guide. (I didn't actually know .md meant markdown - my ignorance blossoms by the hour lately.)

    If, for example people just posted things they wanted changed into a forum thread or something, someone would have the job of going through each post and applying the changes, which wouldn't be fun.

    I agree, and I suggest that the "Bugs and Errors" thread is scrapped from the "new" site although I have lost track of whose jurisdiction that would fall under.

    Thanks again for your help.
  • I think the YUI API documentation is also a good example. (See: http://developer.yahoo.com/yui/3/api/)

    What I like, for Kohana to have:

    1. Autocomplete + searchbox combined on the API (like the YUI documentation has)
    Also look at the seperation of the namespace and method name in the autocomplete box.
    I suggest some format like this: Module.Class method (var, var, &var, [var], [optional var])
    and let the search query be highlighted in the autocomplete box
    put that box on the place where the language selection is now, and make that one smaller or something

    2. Seperate API browser and tutorials more, but on some parts integrate them more
    For example I want in the normal userguide direct access to the API via the searchbox. But also it's nice to have a direct navigation to the API, like YUI docs has. Which makes it a lot faster and easier for me to find things.

    I also want more cross referencing between API browser and tutorials and back. Like for example, clicking in example code on functions will bring you to the API browser, and maybe even mouseover will give you a tooltip, compared to modern IDE's about the function. But also backwards, in the API browser have some links, via phpdoc @link or @site to some tutorials about that class/method you're watching.

    3. The "Class Contents" in the API browser is currently by default, hidden, and you're able to slide it out. But if I want to search quick on the page I want it by default visible, so I can click through to the part of the page I want to be.

    4. The API function description could be a lot compactor shown on the screen, so you don't have to scroll much to view the functions. The font size is to much. Also the return values are places as if PHP allows multiple return values, but PHP only allows a single return value.

    5. In the API browser be able and do that by default to disable the view in deprecated methods and only if you check that checkbox you will be able to view those. This discourage users to use those functions as well as makes the interface a bit cleaner. See for example also the YUI docs.

    6. Clear examples codes of specific parts. For example, when beginning with ORM on how to use many-to-many relations. And how to use through and stuff like that and what is the difference.

    7. On every userguide page or API page, you should be able with one click to go to the API browser and other important pages.

    8. Give me enough example code which is self explainable. Most programmers just want to see example code to see how they can how to use something or just the thoughts behind a function/class.
    For example I wanted to know how to use ORM_MPTT I searched for documentation about it how to use it. I expected to be working something like this.
    $object = ORM::factory('mpptobject');
    $object->parent_id = 2;
    $object->save();
    But it worked like:
    $object = ORM::factory('mpptobject');
    $object->insert_as_last_child(2);

    By searching in some forum about it, I found it. But if this kind of documentation is in the documentation of Kohana/that module for me looking at that code says enough. So I was searching more for such example than browsing through the API, because then I could better read the code myself.

    9. Please create a direct link from the documentation page, to post a bug report about it, with the link to the specific page already in it, so users will post it more on where it should be done, instead of in the comments.


    By the way I'm working here with examples. some parts you don't have to take literally. I do understand ORM_MPTT is not for Kohana, but it's just an example. Just get what I mean, instead of what I literally say. Sorry for this disclaimer, but sometimes I get misunderstood if I don't post this.
  • @ict4schools

    Excellent feedback, thank you very much!

    1. Autocomplete + searchbox combined on the API (like the YUI documentation has)

    I really like that! I'm not sure how hard that would be to implement, but I'll look into it.

    2. Seperate API browser and tutorials more, but on some parts integrate them more.

    The new docs will have 2 tabs at the top of the page, "User Guide" and "API Browser". I have no idea why the API browser was originally buried like it is.

    I also want more cross referencing between API browser and tutorials and back. Like for example, clicking in example code on functions will bring you to the API browser, and maybe even mouseover will give you a tooltip, compared to modern IDE's about the function. But also backwards, in the API browser have some links, via phpdoc @link or @site to some tutorials about that class/method you're watching.

    I believe that you can type Class::method and it will link. Tooltips would be tricky, I'm not convinced they would be worth the effort. Links in the api are a good idea as well.

    3. The "Class Contents" in the API browser is currently by default, hidden, and you're able to slide it out. But if I want to search quick on the page I want it by default visible, so I can click through to the part of the page I want to be.

    I think it was hidden because it takes up so much space on a large class with lots of methods, but thats actually when you would want it the most.

    4. The API function description could be a lot compactor shown on the screen, so you don't have to scroll much to view the functions. The font size is to much.

    Not sure what you mean, can you clarify?

    Also the return values are places as if PHP allows multiple return values, but PHP only allows a single return value.

    It's because a function can return different things depending on the input. For example, Kohana::find_file() can return an array, or a single file path (or FALSE actually, that should probably be added) depending on the params and whether the file was found.

    5. In the API browser be able and do that by default to disable the view in deprecated methods

    Not sure if this is necessary, there aren't that many deprecated functions.

    6. Clear examples codes of specific parts.

    Definitely.

    7. On every userguide page or API page, you should be able with one click to go to the API browser and other important pages.

    Yep.

    8. Give me enough example code which is self explainable.

    Definitely. Although ORM_MPTT isn't an official module, so you can't get mad at us for the lack of documentation :P Edit: nevermind, just read the disclaimer at the end of your post :)

    9. Please create a direct link from the documentation page, to post a bug report about it, with the link to the specific page already in it, so users will post it more on where it should be done, instead of in the comments.

    Great idea.
  • 1. How can I set language without setting cookie? May be something like $_GET['lang'] param?
    2. It will be great if we can separate Disqus comments for different languages. Is it possible?
  • API Browser:

    1. I assume it's generally known that it doesn't work on Windows. Is there a quick fix?
    2. Would be easier to use if each class (< h2 >) heading had its relevant < ul > as an optional dropdown.
  • @Martin Hall, not sure what problem you have on Windows but I have the API browser working fine "out of the box" on installations under Apache (module) on XP, server 2003 and Vista.
  • @biakaveron:

    1. No, I don't want to do that. A URI param could work, but it would require a different interface.
    2. Not unless we use a URI param, Disqus uses the URI to determine the comments page to load.
  • not sure what problem you have on Windows but I have the API browser working fine "out of the box" on installations under Apache (module) on XP, server 2003 and Vista.

    Hmmm. I've seen a API Browser/Windows problem reported elsewhere in here, and assumed it's a general problem.
    I get this:

    ErrorException [ Parse Error ]: parse error, expecting `'{''

    MODPATH\userguide\classes\kohana\kodoc\missing.php(33) : eval()'d code [ 1 ]

    1. {PHP internal call} » Kohana_Core::shutdown_handler()

    I'm on XAMPP and Vista, but I can't see how server and Windows versions would be significant here, when it's basically just PHP and a bunch of text files. The development version of my main app works fine.
  • @Martin Hall

    Do you ming doing some debugging and telling us what the name of that missing class was?
  • Sorry Bluehawk, should have thought of that.
    It's my own class called "Google" which lives in a "services" module (enabled in bootstrap).
    /modules/services/classes/Google.php. It's a library.
    I also have a Controller_Google : /modules/services/classes/controller/google.php. Might this be a name conflict? I have this naming pattern* in several places, and my own app works fine.


    * /modules/services/classes/Thing.php class Thing
    /modules/services/classes/controller/thing.php class Controller_Thing
    /modules/services/classes/model/thing.php class Model_Thing
  • @Martin Hall

    Everything there looks fine, not sure why that's happening.
  • My only thought is that ISTR that xampp on windows uses case-sensitive filenames, no? So your Google class should be in classes/google.php. although saying that, your app would fail in the same way as userguide if that was the case. Might be worth a try though to see if it solves your missing problem (and worth doing anyway in case you deploy to linux in future).

    On the parse error though, is the exact string being evaled in Kohana__Kodoc_Missing
    class Google extends Kodoc_Missing {}

    Hard to see how the parser could expect a { anywhere in there on any platform. There definitely aren't any special characters or anything somehow creeping into the $class parameter?
  • I already tried the possible permutations of case with no change.
    I'm going to try moving my own files out of "modules" and replacing them one by one.
    Don't hold your breath....
  • The problem has to do with my own files and/or bootstrap settings. My vanilla copy of 3.0.7 has a working API Browser.
    Do my own files require *strict* PhpDoc commenting for the API Browser to work properly?
    By the way, Bluehawk, apologies for the thread hijack - unless you think this is as good a place as any to discuss API problems.
  • Perhaps the autoload process could be fine-tuned. It seems that .bak files will be included, along with any other non-.php junk which might be lying around.
    Also, would it be possible to make including app files a configurable option?
  • I read about 1/2 to 2/3rds of this thread and got a little tired of what seemes to be more of an arguement of points previously made rehashed 4-6 times each in a row and decided to skip the rest and just come to the bottom and add my "Documentation Improvement Suggestion" that was originally asked for and I apologize in advance if what I am suggesting was suggested in the last half that I skipped but here are my suggestions:

    1. I would like to see more "Modules" Information added to the documentaion.

    2. I would like to see more Tutorials aimed at several levels of compency or experience and have them categorized as so. ie: Begginer Intermediate Expert sort of thing.

    3. I think it might be useful and cool to have a "Related" like set of links in a CSS box or something to each section that perhaps links to community mods or packages etc that use or enhance or demonstrate Kohanas Capabilities in some way. For instance linking somehow to the snippet forum where a particular snippet was made to use or extend a Module or Helper or Class etc. So when someone is reading and learning about the "Auth" module perhaps there is a link to a download or discussion elsewhere that offers some views or controllers etc to add to it that are being distrubeted.

    4. I do like the commenting linked via disqus thing and perhaps there could use a more unified way of accomplishing this wherby you can add comments via disqus or via directly if you wished? Dunno if that's a good or bad idea and not really important on the list to me?

    I like the current layout of the guide and am not too conerned about appearance improvement. Looks fairly fine to me save for ways to incorporate some of the suggestions I made.

    As a noobie to Kohanna I would also like to state that Site Navigation in general can be very confusing sometimes and it just seems like lots of areas have been develeoped seperately and aren't very cohesive. This can sometimes extend into the documentation and perhaps if one was considering documentation appearance improvement than one important improvement would be to make it look like you are still on kohanaframework.org while reading its documentation and not some other site. And finding your way back (or onward) to other areas is easy and intuitive.


    Thanks for your time
  • I've been struggling to learn Kohana now for the last 7 days and it bothers me that I haven't even been able to get a simple user login interface to work with all the documentation, tutorials in several languages and everything else I found through the forum and google.

    Two things that would help me a great lot would be:

    a. In-depth module-independant documentation of each of the following features: Authentication interfaces, Templates, Search, etc.

    b. Three thoroughly documented very basic skeleton apps flung together by three different kohana experts, available for download, including a database sql file with minimally populated tables included if it uses a database at all. Ideally one of them would use ORM, whereas another would use Sprig, just so you can get a good idea of various different best-practices out there.


    Especially the latter would be immensly helpful!

    I downloaded w.ings from Shadowhand's github, but it's not a complete example of simplicity. If I had a skeleton app to study I would probably be able to learn much more from looking at the source of w.ings ...

    Anyway, that's just my two cents :-)
  • > If I had a skeleton app to study

    http://github.com/zombor/Vendo
  • @thinkaround - Oh I totally agree and love your suggestions. Would help a lot.

    @zombor sounds like it would make a good skeleton example. I intend to look at it thanks!
  • I definitely agree that the documentation needs a style overhaul.

    Here are some examples of some nicely styled documentation:
    http://simplegeo.com/docs/clients-code-libraries/php
    http://guides.rubyonrails.org/security.html
  • What I am missing is demonstration applications. My idea is that there are a dedicated page called "Demonstration applications". On this page there would be a list where every items look like this:

    Name: Blog
    Description: How to make a blog in 30 minutes using Sprig
    Tags: Frontend, Backend, Sprig, 404 page, auth, template
    Rating 4 of 5 stars (maybe visually)

    Every application would then be hosted on git hub. The install/usage/requirements instructions would then be on git hub.

    Also it would be nice if there could be a recommended way of doing somthing e.g. how to do authentication/authorization. That would then be a complete demonstration application.

    I have been working on some demonstration applications but do not know where I should post it. Right now my best guess is kerkness unofficial wiki.
  • @boxyman
    Github is an excellent place for your demos ;)

Howdy, Stranger!

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

In this Discussion