directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Pierre-Arnaud Marcelot (Commented) (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DIRSERVER-1678) Move wiki pages to svn
Date Fri, 09 Dec 2011 11:12:40 GMT

    [ https://issues.apache.org/jira/browse/DIRSERVER-1678?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13166074#comment-13166074
] 

Pierre-Arnaud Marcelot commented on DIRSERVER-1678:
---------------------------------------------------

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?
                
> Move wiki pages to svn
> ----------------------
>
>                 Key: DIRSERVER-1678
>                 URL: https://issues.apache.org/jira/browse/DIRSERVER-1678
>             Project: Directory ApacheDS
>          Issue Type: Task
>    Affects Versions: 2.0.0-M4
>            Reporter: Felix Knecht
>            Assignee: Felix Knecht
>             Fix For: 2.0.0-M4
>
>
> See http://mail-archives.apache.org/mod_mbox/directory-dev/201109.mbox/%3CCAPz8h_UBRfTsk%2Bpy%2BKtxdh8zH1XW7x_t3gc0KcDiAfoMy8kwAA%40mail.gmail.com%3E

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

Mime
View raw message