We are updating documentation for Toolset releases

   Konstantinos

Announcements

June 6, 2016
11

A major update for all Toolset plugins is coming later this week and this also includes updates in our documentation pages. Today, we are starting updating our live content, so it will be ready for the releases.

The next few days, during this documentation update, some pages may include information or screenshots for both the current and the upcoming releases. We apologize for this inconvenience and we hope that the transition will be smooth.

If you want to preview and test the upcoming versions of Views 2.1 or Types 2.1, you can find them in the Downloads page of your Toolset account, by selecting “Beta” in the plugins dropdown.

 

Comments 11 Responses

    • The new release was just published this week! It was delayed for few days because of some important final testing.

  2. Good news – documentation is the foundation of success when it comes to software, and your documentation needs work.

    However, from your above post it seems you are trying to modify the mess you have instead of going at it with a new approach. If I may suggest, instead of revamping the old stuff, just create a new layer.

    Let’s say we have primary documentation areas as follow:

    • License
    • Terminology
    • Introduction (including linear overview)
    • Quick-start Guide
    • Full Documentation (including a section with examples)
    • Advanced Implementations (including a section with examples)
    • API Reference (including a section with examples)
    • Known Bugs

    (Of course, each area would have sections and subsections, but hopefully you get the idea.)

    So instead of something like this:

    https://toolset.com/documentation/user-guides/content-filter-settings/

    you might have something like this:

    https://toolset.com/docs/2.1/full/CRED/content-filter-settings/

    And instead of something like this:

    https://toolset.com/documentation/customizing-sites-using-php/functions/

    You would have something like this:

    https://toolset.com/docs/2.1/api/types/fields/content-filter-settings/

    Then, on your next release you copy the entire “2.1” directory, rename the copy to “2.2”, place it under the docs directory, and start your editing. You could delete old version directories so that you only had three versions available at any given time, but with disk space being so cheap, not sure why you’d bother. In any event, you wouldn’t have the problem you are discussing above, and at some point I would hope you could actually overhaul the documentation instead of just updating the same confusing set you have.

    Here’s a real life example in action:

    http://httpd.apache.org/docs/2.4/configuring.html
    http://httpd.apache.org/docs/2.2/configuring.html
    http://httpd.apache.org/docs/2.0/configuring.html

    • Thank you for a very nice suggestion! The documentation system you suggest is very nice but we don’t feel it would present a good choice for are own case. We are aware of the things you mention about improving the documentation and we are already underway on this huge task. Hopefully, you will soon come to see the results of it in our documentation.

    • Please elaborate on how a situation where “some pages may include information or screenshots for both the current and the upcoming releases” is better than what I suggest. Also please explain what users are to do for documentation is they want to delay upgrading and you are modifying the docs out from under them.

      Thanks

      • Hello! I would just like to add that while we will not pursue the proposed version-based system, we are actively looking into adding a way for you to find needed documentation more easily. Please believe me when I tell you that for us, documentation is anything but an after-thought. 🙂

        Thank you for all your comments and suggestions!

        Dario,
        Documentation Leader

  3. I have to agree with a.s.N-2 here, I find is a very clunky system to use. Konstantinos your reply is very narrow and reads: We don’t have the time to invest in sorting out the most important part of our software. You hit the nail on the head here: ” The documentation system you suggest is very nice but we don’t feel it would present a good choice for are own case. ”

    The documentation is not for you, it is for your users.!

    You really do need to update your docs to read more friendly & more videos please. There are two ways of learning, visual is a big one!

    • Hi Alex, Dario here, documentation leader!

      I read your comment and wanted to ask you about the video documentation you suggested. Can you please share what topics would you most like to see us adding video guides for? More basic or more advanced things?

      Thank you!

      • Hi there,

        Thank you for your reply 🙂

        I would love to see more videos to the layouts and theme integrations!

        Regards
        Alex

  4. I have to agree with a.s.N-2 as well. Finding my way around to see the actual topic I am looking for is hard.
    Also, the samples should always use the same concept – trying to wrap my head around a page that concentrates on Services, then suddenly we jump to Light Sabers.

    I can easily follow a sample site that uses Book listings to see how the examples can be converted to my requirements. Books can be changed to Products, Properties, Services or whatever.
    I can ‘think’ .. okay, books would be my product. Author would be my brand and so on. Please consider in future tutorials to stick to one, simple to understand example page 🙂

    Let me take this opportunity to congratulate you on a GREAT plugin. As a non-programmer I am struggling a bit to make this very complex site, but it is doable!

    • Thanks for your feedback. I completely agree that we should pick fewer objects and use them consistently for our documentation. This comes in good timing, as we’re always updating documentation.