Details

    • Type: Task Task
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Component/s: None
    • Labels:
      None

      Activity

      Hide
      Emmanuel Lecharny added a comment -

      All teh pages have been migrated to teh Apache CMS system

      Show
      Emmanuel Lecharny added a comment - All teh pages have been migrated to teh Apache CMS system
      Hide
      Felix Knecht added a comment -

      Hi Pierre-Arnaud

      It should be as much easy as possible especially for the main document writers to find the document they want to edit. The only problem I see this way is that one has to rename all files above if one wants to insert a chapter/section in between. But as I'm not THE document writer I leave it up to them to decide what they want.

      I agree, that your suggestions will make it easier to get an overview of the structure. Doing this way it might be even possible to have the book.txt file generated by a maven task on the fly
      When switching to you suggestion I'd even use 2 digits as prefix like 01_?, 02_? to be on the save side for at least 99 documents per folder which are correctly listed, otherwise following might become a problem:

      – 0_book.txt
      – 1_introduction/
      – 1_introduction.confluence
      – 11_some.confluence
      – 2_administrative_points.confluence
      – 3_operations_on_administrativepoints.confluence
      – 4_some.confluence
      – 5_some.confluence
      – 6_some.confluence
      – 7_some.confluence
      – 8_some.confluence
      – 9_some.confluence
      Show
      Felix Knecht added a comment - Hi Pierre-Arnaud It should be as much easy as possible especially for the main document writers to find the document they want to edit. The only problem I see this way is that one has to rename all files above if one wants to insert a chapter/section in between. But as I'm not THE document writer I leave it up to them to decide what they want. I agree, that your suggestions will make it easier to get an overview of the structure. Doing this way it might be even possible to have the book.txt file generated by a maven task on the fly When switching to you suggestion I'd even use 2 digits as prefix like 01_? , 02_ ? to be on the save side for at least 99 documents per folder which are correctly listed, otherwise following might become a problem: – 0_book.txt – 1_introduction/ – 1_introduction.confluence – 11_some.confluence – 2_administrative_points.confluence – 3_operations_on_administrativepoints.confluence – 4_some.confluence – 5_some.confluence – 6_some.confluence – 7_some.confluence – 8_some.confluence – 9_some.confluence
      Hide
      Pierre-Arnaud Marcelot added a comment -

      Hi Felix,

      I personally like better the prefixed version with chapter numeration.

      It has a great advantage to me, it allows to view the entire book hierarchy (like a table of contents) right from the book folder itself, in a command line environment (using ls -l), or in a graphical file manager (the Finder on OS X, Windows Explorer on Windows, Nautilus on Gnome).
      This makes it really easy to find the file you're looking for and to see which files come before and after.

      The big caveat of this solution is when you need to insert a new file between existing files. Then, you need to update the names of all the files coming after the one you're inserting. That can cause a lot of 'svn mv' commands and edits in the book file which links all other files.
      I experienced it a few (rare) times on Studio's documentation system.

      That said, what you've done is interesting, and moving files into subfolders depending on the subject (and chapter or section) they're dealing with, already looks like a kind of good organization.

      The only thing I'm really missing a lot in your files organization is order between the various files.

      How about combining the two methodologies?
      We could regroup related files (per chapter, per section, per sub-section) into folder and, inside and relative to that folder, have an internal ordering of file with number prefix.

      It would give us the following scheme:
      [Documentation root]

      – 0_book.txt
      – 1_introduction/
      – 1_introduction.confluence
      – 2_administrative_points.confluence
      – 3_operations_on_administrativepoints.confluence
      – 2_authentication_and_authorization/
      – 1_authentication_and_authorization.confluence
      – 2_autorization/
      – 1_autorization.confluence
      – 2_introduction.confluence
      – 3_definitions.confluence
      [...]

      This would avoid us to have long prefix like '2-5-6-3' which would require a complete rewrite for the sub-hierarchy in the case of an insertion (the problem exposed above)".

      WDYT?

      Show
      Pierre-Arnaud Marcelot added a comment - Hi Felix, I personally like better the prefixed version with chapter numeration. It has a great advantage to me, it allows to view the entire book hierarchy (like a table of contents) right from the book folder itself, in a command line environment (using ls -l), or in a graphical file manager (the Finder on OS X, Windows Explorer on Windows, Nautilus on Gnome). This makes it really easy to find the file you're looking for and to see which files come before and after. The big caveat of this solution is when you need to insert a new file between existing files. Then, you need to update the names of all the files coming after the one you're inserting. That can cause a lot of 'svn mv' commands and edits in the book file which links all other files. I experienced it a few (rare) times on Studio's documentation system. That said, what you've done is interesting, and moving files into subfolders depending on the subject (and chapter or section) they're dealing with, already looks like a kind of good organization. The only thing I'm really missing a lot in your files organization is order between the various files. How about combining the two methodologies? We could regroup related files (per chapter, per section, per sub-section) into folder and, inside and relative to that folder, have an internal ordering of file with number prefix. It would give us the following scheme: [Documentation root] – 0_book.txt – 1_introduction/ – 1_introduction.confluence – 2_administrative_points.confluence – 3_operations_on_administrativepoints.confluence – 2_authentication_and_authorization/ – 1_authentication_and_authorization.confluence – 2_autorization/ – 1_autorization.confluence – 2_introduction.confluence – 3_definitions.confluence [...] This would avoid us to have long prefix like '2-5-6-3' which would require a complete rewrite for the sub-hierarchy in the case of an insertion (the problem exposed above)". WDYT?
      Hide
      Emmanuel Lecharny added a comment -

      First, I agree that having chapter numbers in file name is painfull. We probably can get rid of it.

      About the "

      {toc:type=list|minLevel=2|maxLevel=2}

      " , it's just used to add a menu into a page, I'm not sure it's really useful, as soon as we have a content page. No book has such a feature, no need to add it IMO. Also the need of such a menu was created because we had too many information in the page. May be having smaller pages would be better.

      One more thing : when generating the pdf, we have an issue with the links (a link is seen twice, instead of once). The problem is not existing for the generated HTML pages. I have no idea how to fix that.

      Show
      Emmanuel Lecharny added a comment - First, I agree that having chapter numbers in file name is painfull. We probably can get rid of it. About the " {toc:type=list|minLevel=2|maxLevel=2} " , it's just used to add a menu into a page, I'm not sure it's really useful, as soon as we have a content page. No book has such a feature, no need to add it IMO. Also the need of such a menu was created because we had too many information in the page. May be having smaller pages would be better. One more thing : when generating the pdf, we have an issue with the links (a link is seen twice, instead of once). The problem is not existing for the generated HTML pages. I have no idea how to fix that.
      Hide
      Felix Knecht added a comment -

      Todo:

      • Fix the internal links and references
      • What shall we do with the " {toc:type=list|minLevel=2|maxLevel=2}

        "

      The structure/naming of the source files in "Basic User's Guide confluence" (no chapter numeration in the file name) looks to me better than using a chapter numeration in the file name (like in "Advanced User's Guide confluence"). It'll make it easier to move files from one into another chapter if ever needed. WDOT?

      Show
      Felix Knecht added a comment - Todo: Fix the internal links and references What shall we do with the " {toc:type=list|minLevel=2|maxLevel=2} " The structure/naming of the source files in "Basic User's Guide confluence" (no chapter numeration in the file name) looks to me better than using a chapter numeration in the file name (like in "Advanced User's Guide confluence"). It'll make it easier to move files from one into another chapter if ever needed. WDOT?
      Hide
      Felix Knecht added a comment -

      Done for Basic User's Guide

      Show
      Felix Knecht added a comment - Done for Basic User's Guide
      Hide
      Felix Knecht added a comment -

      Done for Advanced User's Guide

      Show
      Felix Knecht added a comment - Done for Advanced User's Guide

        People

        • Assignee:
          Felix Knecht
          Reporter:
          Felix Knecht
        • Votes:
          0 Vote for this issue
          Watchers:
          1 Start watching this issue

          Dates

          • Created:
            Updated:
            Resolved:

            Development