As for me the main page of any product is important to make a good first impression. When I open the main page of JanusGraph it looks like the site was constructed in the 90s (sorry for criticism). I understand that the style was taken from TitanDB (http://titan.thinkaurelius.com) but I think it should be changed.

Another concern is that the main page uses http protocol still. I do understand that there is nothing to secure on the main page but I believe that https protocol will make a better impression. Notice that docs.janusgraph.org is using https protocol (Letsencrypt certificate). I believe it isn't hard to add an additional SSL certificate for the main page. Also, Letsencrypt supports wildcard certificates, it is possible to make a certificate for the entire *.janusgraph.org domain to cover all subdomains and use the same certificate on the main page and in the docs.

Best regards,

Alexandr Porunov

Hi

I used the mkdocs-material theme to create a modern looking page overall.

The main approach was to merge everything together into one repo. This also reduces the managing tasks.

Hosted version of my approach code: https://farodin91.github.io/farodin91/site/

Code: https://github.com/farodin91/janusgraph/tree/mkdocs

What does everyone think of this design?

Best,

Jan

Hi

Will try to open an pull request in the next days.

The most broken things are broken due the conversion from adoc to md. All files need to be checked manually. Therefore, I want to get a response first of current state, before checking all files.

Best,

Jan

Am Mittwoch, 13. Februar 2019 15:40:40 UTC+1 schrieb Oleksandr Porunov:

Hello Jan,

Wow. It is an impressive work. I really like this design! Hope it will be merged soon. 

The one issue which I've noticed is that there is only one (I assume latest) version of the documentation. Right now in JanusGraph there are seven documentations for different versions of janusgraph and we can easily switch between them. Is there a possibility to make such an approach with your solution?

The traefik docs has multiple version in their documentation, see here https://docs.traefik.io/.

There are also other issues, but I think they are temporary and easy to resolve. I will place them here not to lose:  

- Some links are shown as `???`.

- Some links doesn't work.

- Some images are not loaded.

- Some links are wrong named (For example, in the bottom of the `Introduction` section there is a next link which is also called `Introduction` but should be called `Configuration`)

- `Edit this page` buttons are referring to the wrong location

Some pages need to be named correctly.

Best regards,

Oleksandr

On Wednesday, February 13, 2019 at 2:36:49 PM UTC+2, Jan Jansen wrote:

Hi

I used the mkdocs-material theme to create a modern looking page overall.

The main approach was to merge everything together into one repo. This also reduces the managing tasks.

Hosted version of my approach code: https://farodin91.github.io/farodin91/site/

Code: https://github.com/farodin91/janusgraph/tree/mkdocs

What does everyone think of this design?

Best,

Jan

There are definitely some items I would add nits on in a PR, but I like it. As Oleksandr's mentioned we should probably have a way to have multiple doc versions and I definitely have some opinions on this.

Some of my thoughts on a docs overhaul: 

• We should add pdf of the docs to the releases page for the docs that are shipped with each release. This hopefully satisfies the requirement that users can access the same version of docs that come with their release zip.
  
• We should only host the current, actively updated, docs of each release branch. 0.1.x0.2.x, 0.3.x, 
• Are we fully replacing the current doc generation for the release docs? Or are we going to have two separate systems to manage going forward?
• Add doc only checks instead of [skip ci] to travis and can auto-merge updates to gh-pages on changes. There were some enhancements to travis last year that make this possible.
• link checker for markdown files, if it covers relative links this covers broken images as well. (I've worked on this for other projects and could take this one)
• javadoc validation. (Already in maven)
• possibly spellcheck with a custom dictionary.

On Wednesday, February 13, 2019 at 7:26:35 AM UTC-8, Jan Jansen wrote:

Hi

Will try to open an pull request in the next days.

The most broken things are broken due the conversion from adoc to md. All files need to be checked manually. Therefore, I want to get a response first of current state, before checking all files.

Best,

Jan

Am Mittwoch, 13. Februar 2019 15:40:40 UTC+1 schrieb Oleksandr Porunov:

Hello Jan,

Wow. It is an impressive work. I really like this design! Hope it will be merged soon. 

The one issue which I've noticed is that there is only one (I assume latest) version of the documentation. Right now in JanusGraph there are seven documentations for different versions of janusgraph and we can easily switch between them. Is there a possibility to make such an approach with your solution?

The traefik docs has multiple version in their documentation, see here https://docs.traefik.io/.

There are also other issues, but I think they are temporary and easy to resolve. I will place them here not to lose:  

- Some links are shown as `???`.

- Some links doesn't work.

- Some images are not loaded.

- Some links are wrong named (For example, in the bottom of the `Introduction` section there is a next link which is also called `Introduction` but should be called `Configuration`)

- `Edit this page` buttons are referring to the wrong location

Some pages need to be named correctly.

Best regards,

Oleksandr

On Wednesday, February 13, 2019 at 2:36:49 PM UTC+2, Jan Jansen wrote:

Hi

I used the mkdocs-material theme to create a modern looking page overall.

The main approach was to merge everything together into one repo. This also reduces the managing tasks.

Hosted version of my approach code: https://farodin91.github.io/farodin91/site/

Code: https://github.com/farodin91/janusgraph/tree/mkdocs

What does everyone think of this design?

Best,

Jan

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/b09f96d9-0886-4e04-abba-eccf0d78195f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

There are definitely some items I would add nits on in a PR, but I like it. As Oleksandr's mentioned we should probably have a way to have multiple doc versions and I definitely have some opinions on this.

Some of my thoughts on a docs overhaul: 

• We should add pdf of the docs to the releases page for the docs that are shipped with each release. This hopefully satisfies the requirement that users can access the same version of docs that come with their release zip.
  
• We should only host the current, actively updated, docs of each release branch. 0.1.x0.2.x, 0.3.x, 
• Are we fully replacing the current doc generation for the release docs? Or are we going to have two separate systems to manage going forward?
• Add doc only checks instead of [skip ci] to travis and can auto-merge updates to gh-pages on changes. There were some enhancements to travis last year that make this possible.
• link checker for markdown files, if it covers relative links this covers broken images as well. (I've worked on this for other projects and could take this one)
• javadoc validation. (Already in maven)
• possibly spellcheck with a custom dictionary.

On Wednesday, February 13, 2019 at 7:26:35 AM UTC-8, Jan Jansen wrote:

Hi

Will try to open an pull request in the next days.

The most broken things are broken due the conversion from adoc to md. All files need to be checked manually. Therefore, I want to get a response first of current state, before checking all files.

Best,

Jan

Am Mittwoch, 13. Februar 2019 15:40:40 UTC+1 schrieb Oleksandr Porunov:

Hello Jan,

Wow. It is an impressive work. I really like this design! Hope it will be merged soon. 

The one issue which I've noticed is that there is only one (I assume latest) version of the documentation. Right now in JanusGraph there are seven documentations for different versions of janusgraph and we can easily switch between them. Is there a possibility to make such an approach with your solution?

The traefik docs has multiple version in their documentation, see here https://docs.traefik.io/.

There are also other issues, but I think they are temporary and easy to resolve. I will place them here not to lose:  

- Some links are shown as `???`.

- Some links doesn't work.

- Some images are not loaded.

- Some links are wrong named (For example, in the bottom of the `Introduction` section there is a next link which is also called `Introduction` but should be called `Configuration`)

- `Edit this page` buttons are referring to the wrong location

Some pages need to be named correctly.

Best regards,

Oleksandr

On Wednesday, February 13, 2019 at 2:36:49 PM UTC+2, Jan Jansen wrote:

Hi

I used the mkdocs-material theme to create a modern looking page overall.

The main approach was to merge everything together into one repo. This also reduces the managing tasks.

Hosted version of my approach code: https://farodin91.github.io/farodin91/site/

Code: https://github.com/farodin91/janusgraph/tree/mkdocs

What does everyone think of this design?

Best,

Jan

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/b09f96d9-0886-4e04-abba-eccf0d78195f%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Replacing of variable is already possible using variables in mkdocs config and in the markdown file a jinja variable.

Code include is already possible using a plugin which is default included.

Things can't be done by me:

* Rename release branches starting with v... for example v0.3, v0.2. This is required for the version tool detect version branches.

* Check that TravisCI can write into the branch gh-pages in the janusgraph repo.

Any member can you check/do both things? If it is okay.

For the topic: Version control

I think we should be able to update documentation for old versions. Therefore, I would like to have rolling updates in the documentation for each major release for example 0.3, 0.4, or 0.5.

For the patch level version, I prefer to only integrate the current version document into release binary.

In the future, we could starting adding notes in to the documentation in which version this feature was added.

Anyone okay with this schema of releasing new documentation?

Not sure if I understood you correctly, Jan: Are you agreeing with Oleksandr that a feature branch makes sense?

Yes

In that case, I can create one, but that would mean of course that you would need to do all changes from then on through PRs. Although we can then just merge these PRs through to the feature branch as the formal review will happen later when we merge the feature branch into a release branch.

We should not change any text in the doc with this PR.

We should just create an issue first for that, but that makes sense in general I guess as we can keep track of the progress and what's still left to do in that issue.

Yes  

Another thing I'm not sure about yet is which release branch should be target for this. We will release a 0.2.3 version. Should that still use our current version of the docs or already the new one?

This would be possible only 4/5 commits difference between branch 0.2 and master