Documentation

[Maria Arias de Reyna Dominguez]

Hi!

I'm checking our current docs and want to add all the dispersed docs
on github to our https://syndesis.io/docs/

Are we in favor of having everything on the syndesis.io/docs website
or is there any reason to keep it separated on the source code? Maybe
on github it gets easier to maintain?

To me it makes sense to have at least a link from the website, better
if everything is rendered on the website. Less experienced developers,
the ones who need it most, will not know where to find the docs if it
is not consistent.

We have the user docs: https://github.com/syndesisio/syndesis/tree/master/doc
Which should be added once this PR (or another similar) gets merged:
https://github.com/syndesisio/syndesis.io/pull/158
Zoran, any comments here? (I'm having problems building this PR
because node-saas versions not being compatible with my linux
whatever, checking about it now)

We have the UI docs:
https://github.com/syndesisio/syndesis/tree/master/app/ui-react
Is the UI team planning to merge it at some point to the website too?
Maybe on a similar approach as what we will do with the user docs?

We have the server docs:
https://github.com/syndesisio/syndesis/tree/master/app/server/docs
This is confusing to me. Are they imported on some other docs, maybe?
Are they rendered somewhere?

We also have the connector docs:
https://github.com/syndesisio/syndesis/tree/master/app/connector
If I'm not mistaken these are part of the user docs too, right? So
once we merge the user docs, this gets solved?

We have the testing docs:
https://github.com/syndesisio/syndesis/tree/master/app/test
This would be nice to have it added to the website. They are basic
markdown, so I guess we can maybe import them too on a gulp task and
adapt them to render it properly.

And finally we have the Camel-k docs:
https://github.com/syndesisio/syndesis/tree/master/app/integration/runtime-camelk
Which I would do as the testing docs.

Am I missing any other piece of documentation we should add to the website?

Have a nice day!
María Arias de Reyna Domínguez

--
Senior Software Engineer

She / Her / Hers
ariasd...@redhat.com

[Maria Arias de Reyna Dominguez]

On Mon, May 4, 2020 at 2:34 PM Zoran Regvart <zo...@regvart.com> wrote:
>
> Hi Maria,

>
> On Mon, May 4, 2020 at 11:40 AM Maria Arias de Reyna Dominguez
> <mari...@redhat.com> wrote:
> > Are we in favor of having everything on the syndesis.io/docs website
> > or is there any reason to keep it separated on the source code? Maybe
> > on github it gets easier to maintain?
>

> Not sure what you mean exactly, I took it to mean that there's docs in
> the syndesisio/syndesis.io and syndesisio/syndesis GitHub projects,
> and you're asking if they should be in the same GitHub project?
>
> If so, the reason why there are two sources for the documentation is
> that the documentation in syndesisio/syndesis gets versioned whereas
> the documentation in syndesisio/syndesis.io is not versioned.

Ah no, I meant to publish everything on the https://syndesis.io/docs website.

>
> > To me it makes sense to have at least a link from the website, better
> > if everything is rendered on the website. Less experienced developers,
> > the ones who need it most, will not know where to find the docs if it
> > is not consistent.
>

> The goal is to publish all the documentation (contributing guide,
> connector reference and the user guide) on the website, out of which
> that I'm aware only the user guide is not published, hence:

>
> > We have the user docs: https://github.com/syndesisio/syndesis/tree/master/doc
> > Which should be added once this PR (or another similar) gets merged:
> > https://github.com/syndesisio/syndesis.io/pull/158
> > Zoran, any comments here? (I'm having problems building this PR
> > because node-saas versions not being compatible with my linux
> > whatever, checking about it now)
>

> I need to finish that work. You most likely need to switch to Node v10
> to get node-sass working.

>
> > We have the server docs:
> > https://github.com/syndesisio/syndesis/tree/master/app/server/docs
> > This is confusing to me. Are they imported on some other docs, maybe?
> > Are they rendered somewhere?
>

> I think that was an attempt to add architecture related documentation
> along with code. I think that's pretty defunct and out of date at the
> moment, not sure if it helps anyone.

Then maybe we should remove it.

>
> > We also have the connector docs:
> > https://github.com/syndesisio/syndesis/tree/master/app/connector
> > If I'm not mistaken these are part of the user docs too, right? So
> > once we merge the user docs, this gets solved?
>

> Not sure what docs you found here, I can't seem to find any.

I meant all the *.adoc files on each connector, but I found they are
part of the manuals.

>
> I snipped the rest of the mail, I think this applies to those bits as
> well. I don't think we need to publish every document to the website,
> there needs to be some code-level documentation at the place where
> someone can discover it. So placing README.md files is to me the same
> as adding documentation to the code, and not really material that
> should be pushed to the website. This helps in making it current and
> discoverable.

I find it a bit random where those README.md files are placed. If all
of them were on the root folder or linked from the root folder, maybe.
But for example, the documentation on how to use Camel-k feels hidden
to me. You can't find it unless you are a developer that knows there
is this specific maven project inside app/integration/runtime-camelk.
Otherwise you don't even have to know Camel-k is a possibility. And if
I add the same information to the website, that means having to
maintain both texts.

Same with AtlasMap integration.
https://github.com/syndesisio/syndesis/blob/master/app/server/docs/design/datamapper.md
(the page that made me start yak shaving this :) ).

[Pasquale Congiusti]

In my opinion we should leverage existing documentation that is still valuable and rewrite targeting syndesis.io. As far as I can see, most of that documentation is old and used to drive further refinement on the technical development, so not always 100% accurate. However it's still a good point to start and build added value on top of it. Also from SEO perspective, we should avoid to clone what we have on github, as the latter is already indexed and may be perceived by search engine as a cloned content.

A possible strategy is to spot those good documents and log an issue in github and then having volunteer to write about each topic.

Cheers,

Pasquale.