Loading...
 
Skip to main content

Documentation

Forum List Topic List

Forums » Documentation » Questions about the state of doc.t.o
 
Thread actions
Print this page
  • Print all pages

    • Questions about the state of doc.t.o

    Posted by pianoliv posts: 97

    Hi

    I have recently been translating documentation pages into french and started to realize how messy things are.
    There used to be a unique documentation structure:
    http://doc.tiki.org/Documentation+TOC
    Things seems to have started to evolve for the best with the creation of several different structures supposed to contain the same stuff:
    http://doc.tiki.org/Tiki+Installation+Guide
    http://doc.tiki.org/Tiki+Reference+Guide
    http://doc.tiki.org/Tiki+User+Guide

    Now we are stuck with two paralel systems which is confusing to say the least. So my main question today is:
    Is the old "documentation toc" structure ready to disappear? If not, what still needs to be done?

    In the spirit of splitting the guide for admins and users, I think splitting this page would be a good idea: http://doc.tiki.org/Wiki-Syntax+Links
    In fact, it seems it has already been done somehow with http://doc.tiki.org/Wiki+Linking
    The idea is to have a user centric page on how to create simple links, mostly via editing icons in the user guide structure, and keep the gory details for the admins in the "tiki reference guide" structure

    Also, while translating I found out a few odd things, like different places for translated content in a structure.
    For example, why is this not in this page ?
    why is the content of this included here in the french version but not the english one? which is right?

    At last, an OT note: I support the minor alternative layout modification proposed here:
    http://doc.tiki.org/Tiki+Manual+of+Style&no_bl=y#Page_Titles
    The first paragraph of a page should not be the page title. The page title should be displayed above the page or the description made bigger.

    oliv'

    Reads: 6447
    Posted by Xavier de Pedro posts: 1817 Catalan Countries

    hi pops:

    "Is the old "documentation toc" structure ready to disappear? If not, what still needs to be done?"

    Sorry, why should it dissapear? It is useful for me (at least, and as well others) to find (almost) everything related to the documentation in Tiki, as if it was some sort of "Site map".

    I guess that this structure can coexist with other structures, such as the ones you mention.


    Posted by Rick Sapir / Tiki for Smarties posts: 3665 United States

    Welcome! And a hearty "thanks" for taking on the docs...

    pops wrote:

    Now we are stuck with two paralel systems which is confusing to say the least. So my main question today is:
    Is the old "documentation toc" structure ready to disappear? If not, what still needs to be done?

    Not yet (as there's still no completed "User Guide" for the doc). Ideally, we could have all the structures remain, but we really need a way to have a default structure (there's an open Enhancement Request for this), because when a page opens that belongs to two (or more) structures, end-users get no notification at all. 😑

    pops wrote:
    The idea is to have a user centric page on how to create simple links, mostly via editing icons in the user guide structure, and keep the gory details for the admins in the "tiki reference guide" structure

    This was/is the goal of the initial doc revamp (many moons ago). The "User Guide" is meant for end-users of Tiki-powered sites; the "Reference Guide" is meant for Tiki admins.

    pops wrote:

    At last, an OT note: I support the minor alternative layout modification proposed here:
    http://doc.tiki.org/Tiki+Manual+of+Style&no_bl=y#Page_Titles(external link)
    The first paragraph of a page should not be the page title. The page title should be displayed above the page or the description made bigger.

    I don't think I understand your item... The page name may be different than the page's title. On doc.t.o, page names are not displayed by default — on the typed-in page name.

    HTH,

    - Rick | My Tiki Blog | My Tiki UserPage

    Why be a dummy? Get smarty! TikiForSmarties.com
    Tiki for Smarties, your source for the best (and only) Tiki books, guides, and tutorials.

    Posted by pianoliv posts: 97

    Thank you both for theses quick answers, as always 😉

    @Xavier de Pedro:
    Imho the main documentation structure should disappear because:
    It is confusing to have 2 differents structures for the sames pages. Once you got to know your way in one, you'll have a hard time figuring out how to navigate from a page displaying another structure.
    As rick noted, a page with 2 structures will not even display one if accessed via a link like this one. I really wish that users of my website I send to thoses kind of pages "stay" in the user structure. I know I could add the structure as an URL variable, but I have the feeling it would make sense in a broader way.
    Although you are right that power-users like to have all-in-one-page, this would still be possible either via grouping the guides in one mega-structure or by displaying all tocs in one page.
    Of course, a default structure option would be just as awsome, I second this feature request (and then I could also go on adding more structures to my own website).

    @rick: If I understand this page correctly, the main aim is to spread all pages of the documentation structure into 3 differents structures, is this right?
    How many pages didn't go through the process, and which?
    And what is the difference between "Reference Guide" and "Administrators Guide"?

    I had a second thought about splitting the page Wiki-Syntax Links. I still want to split it, but no inclusion in the admin or reference guides. This page is mostly for users, just too much in deep. We could imitate this two pages by having 2 "links syntax" pages in the user guide: basic and advanced.
    Can someone here add this page to the user guide structure so I can start the work?

    The thing with using the first !header to display a page name is that it forces us to never use other first level headers in the page, and the result in the maketoc module is not really sensible. Why should the page title not be its name? Or the page description can be used for a slightly more evolved title, why the need for a third title system?

    About my other questions related to the french translation I'll go directly ask the people who did it. An alternative set of french pages aimed to be a user guide was writen before the new structures appeared, it has no reason to be so anymore.

    oliv'

    Posted by larryg posts: 69

    No, please do not eliminate the current TOC and MAKETOC document structure features. I maintain a 1000 page document that is constantly edited by multiple authors and we use the following divisions:
    1 TOC structure - each chapter/section being a wiki page:
    4 chapters with about 100 sections beneath them (100 wiki pages)

    MAKETOC subsections: on each wiki page (chapter and section) there are many subsections and sub-subsections (many hundreds).

    We use Chapter, section and subsection numbering with TOC and MAKETOC, and print an outlined PDF using a modified version of TW's to print the book., then from Firefox to an HTML file, then import on Microsoft Word, and from Word to a PDF.

    That might sound like an awful process, but it produces an outlined, TOC-supported, numbered, reference document.

    the customized Print Current Documentation is an edited version of the file /lib/parser/parserlib.php file with 2 modified sections adding 20 lines of code. it is free to whomever wants it

    Posted by Xavier de Pedro posts: 1817 Catalan Countries

    Hi Larryg:

    the customized Print Current Documentation is an edited version of the file /lib/parser/parserlib.php file with 2 modified sections adding 20 lines of code. it is free to whomever wants it


    Can you please add your patch at least to tracker5 in dev.t.o?
    https://dev.tiki.org/Make+a+wish

    Or why not adding a new optional feature in tiki's main codebase, in case you consider that your patch is not a fix but an optional enhancement?
    And if it's a bug fixed, don't hesitate to add it to "trunk", at least. See:
    https://dev.tiki.org/Commit

    Thanks for improving Tiki! 😊

    Posted by larryg posts: 69

    Xavi,

    I have contributed my code, with insertion point details, on the Make-a-Wish page. I hope that was the right place to put it. Please let me know if further explanation is necessary.

    -larryg

    Posted by Xavier de Pedro posts: 1817 Catalan Countries

    Hi Oliv'

    The thing with using the first !header to display a page name is that it forces us to never use other first level headers in the page, and the result in the maketoc module is not really sensible. Why should the page title not be its name? Or the page description can be used for a slightly more evolved title, why the need for a third title system?


    In some sites, page names are not shown as page titles. And only in pages where you want to have some page title, you add the "! Foo" tag to get the h1 tag display the title.
    For maketoc, you can indicate to display links for levels from 2 to 3, for instance, and therefore, level 1 is not shown there, nor levels from 4 to downwards. See this example:

    Copy to clipboard
    {maketoc levels="2,3"}


    HTH