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