You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-dev@jackrabbit.apache.org by Davide Giannella <da...@apache.org> on 2016/01/19 12:38:00 UTC

Restructure docs

Hello team,

as part of https://issues.apache.org/jira/browse/OAK-3894 I was planning
a restructure of our documentation site. In particular I was thinking
about an easier way to add/update documentation about oak specific features.

Currently we have a section in the left-hand menu: Features and plugins.
This mean that if we add a feature over there we have to update the
whole doc site as the menu is eventually static in all pages.

My suggestion is to move such section into a specific page features.hml
under the section: Using Oak. Then to move content around under a
subdirectory `features`. We'll eventually have something like:

/oak/docs/features.html (lists all the features)
/oak/docs/features/nodestore/overview.html
/oak/docs/features/plugins/blobstore.html
/oak/docs/features/nodestore/documentmk.html
/oak/docs/features/nodestore/segment/overview.html
/oak/docs/features/query/query.html
/oak/docs/features/security/overview.html
/oak/docs/features/clustering.html
/oak/docs/features/nodestore/persistent-cache.html

This will allow us later on to update and add features by simply
committing the features.html plus all the changed pages.

Thoughts?

Davide

Re: Restructure docs

Posted by Chetan Mehrotra <ch...@gmail.com>.
On Wed, Jan 20, 2016 at 2:46 PM, Davide Giannella <da...@apache.org> wrote:
> When you change/add/remove an item from the left-hand menu, you'll have
> to redeploy the whole site as it will be hardcoded within the html of
> each page. Deploying the whole website is a long process. Therefore
> limiting the changes over there make things faster.

I mostly do partial commit i.e. only the modified page and it ha
worked well. Changing of left side menu is not a very frequent task
and for that I think doing full deploy of site is fine for now

Chetan Mehrotra

Re: Restructure docs

Posted by Thomas Mueller <mu...@adobe.com>.
Hi,

I also always deploy the whole site with maven.

Regards,
Thomas

On 20/01/16 10:16, "Davide Giannella" <da...@apache.org> wrote:

>On 20/01/2016 08:14, Thomas Mueller wrote:
>> ...
>>> This mean that if we add a feature over there we have to update the
>>> whole doc site as the menu is eventually static in all pages.
>> I'm sorry I don't understand. The left-hand menu is in site.xml (in one
>> place). I don't think we will add all that many "features" to Oak in the
>> future.
>>
>
>When you change/add/remove an item from the left-hand menu, you'll have
>to redeploy the whole site as it will be hardcoded within the html of
>each page. Deploying the whole website is a long process. Therefore
>limiting the changes over there make things faster.
>
>With regards to the fact that we won't add that many features in the
>section I hope it won't be true. I see it as a section where we document
>how to use or how it works a particular feature. So I'm really hoping
>we'll add more and more.
>
>Davide
>
>


Re: Restructure docs

Posted by Michael Dürig <md...@apache.org>.

On 20.1.16 10:41 , Marcel Reutegger wrote:
> On 20/01/16 10:16, "Davide Giannella" wrote:
>> When you change/add/remove an item from the left-hand menu, you'll have
>> to redeploy the whole site as it will be hardcoded within the html of
>> each page. Deploying the whole website is a long process. Therefore
>> limiting the changes over there make things faster.
>
> I always deploy the whole site with maven. It does take a bit of time
> but it is automated and worked pretty well for me in the past.
>
> For me this isn't really a pain point at the moment.

+1

Michael
>
> Regards
>   Marcel
>

Re: Restructure docs

Posted by Marcel Reutegger <mr...@adobe.com>.
On 20/01/16 10:16, "Davide Giannella" wrote:
>When you change/add/remove an item from the left-hand menu, you'll have
>to redeploy the whole site as it will be hardcoded within the html of
>each page. Deploying the whole website is a long process. Therefore
>limiting the changes over there make things faster.

I always deploy the whole site with maven. It does take a bit of time
but it is automated and worked pretty well for me in the past.

For me this isn't really a pain point at the moment.

Regards
 Marcel


Re: Restructure docs

Posted by Davide Giannella <da...@apache.org>.
On 20/01/2016 08:14, Thomas Mueller wrote:
> ...
>> This mean that if we add a feature over there we have to update the
>> whole doc site as the menu is eventually static in all pages.
> I'm sorry I don't understand. The left-hand menu is in site.xml (in one
> place). I don't think we will add all that many "features" to Oak in the
> future.
>

When you change/add/remove an item from the left-hand menu, you'll have
to redeploy the whole site as it will be hardcoded within the html of
each page. Deploying the whole website is a long process. Therefore
limiting the changes over there make things faster.

With regards to the fact that we won't add that many features in the
section I hope it won't be true. I see it as a section where we document
how to use or how it works a particular feature. So I'm really hoping
we'll add more and more.

Davide



Re: Restructure docs

Posted by Thomas Mueller <mu...@adobe.com>.
Hi,

I'm not in favour of this, as it breaks links, and I don't see a clear
improvement. I'm more in favour of incremental, small changes.

> an easier way to add/update documentation about oak specific features.

Sorry I don't understand, what is the problem with the current approach?
Is the menu too large? Sure, we could add some structure, but I wouldn't
just add "features".

>
>Currently we have a section in the left-hand menu: Features and plugins.

I think "plugins" is an arbitrary name, it might as well just be
"features".


>This mean that if we add a feature over there we have to update the
>whole doc site as the menu is eventually static in all pages.

I'm sorry I don't understand. The left-hand menu is in site.xml (in one
place). I don't think we will add all that many "features" to Oak in the
future.

Regards,
Thomas