[Starlingx-discuss] StarlingX Documentation Initial Template

[Dean Troyer]

On Thu, Aug 9, 2018 at 4:33 PM, Arce Moreno, Abraham
<abraham.arce.moreno at intel.com> wrote:
> How to decide where to land the documentation? 2 options:
>
>   - docs.openstack.com

We will not be publishing things under openstack.org

>   - docs.starlingx.io

This or something else under starlingx.io

> [ OpenStack Documentation ]
> For each project we create source code directories to enable specific
> functionality:
>
> <stx-project>/docs/                  General Documentation

/doc

> <stx-project>/api-ref/              API Reference
> <stx-project>/api-guide/         API Guide
> <stx-project>/releasenotes/  Release Notes

yes

> [ docs.starlingx.io ]
>
> This option will allows us to take advantage of the infrastructure not only
> to create but also to land our documentation as follows, depending on
> what is the functionality available from the project:
>
> <stx-project>/docs/                 -> docs.openstack.org/<stx-project>
> <stx-project>/api-ref/             -> developer.openstack.org/api-ref/<stx-project>
> <stx-project>/api-guide/        -> developer.openstack.org/api-guide/<stx-project>
> <stx-project>/releasenotes/ -> docs.openstack.org/releasenotes/<stx-project>

FWIW OpenStack did some of the separation here due to the different
teams responsible for the content.  We may not have that need and want
to stick to a simpler format with everything under a single site.

> [ docs.starlingx.io ]
>
> Source code directory structure can be kept however, what could be the landing
> process since it will be out of OpenStack infrastructure?

We need to get the server set up for this (via OpenStack Infra team)
and set up the publishing jobs to populate it

> How about the layout?
>
> Option 1
> <stx-project>/docs/                 -> docs.starlingx.io/<stx-project>
> <stx-project>/api-ref/             -> docs.starlingx.io/api-ref/<stx-project>
> <stx-project>/api-guide/        -> docs.starlingx.io/api-guide/<stx-project>
> <stx-project>/releasenotes/ -> docs.starlingx.io/releasenotes/<stx-project>

I prefer this or something similar...

dt

-- 

Dean Troyer
dtroyer at gmail.com