Improve JanusGraph main page

[Alexandr Porunov]

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

[Misha Brukman]

Hi Alexandr,

Excellent points!

On Thu, Sep 20, 2018 at 5:04 AM, Alexandr Porunov <alexandr...@gmail.com> wrote:

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.

Agreed (I've also gotten this feedback separately); I have a draft in-progress here: https://mbrukman.github.io/janusgraph.org/ and this is being tracked via https://github.com/JanusGraph/janusgraph.org/issues/52

 

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.

Agreed as well on this point, but ince The Linux Foundation manages the domains and owns the DNS configuration for janusgraph.org, they need to update a certain part of config to enable GitHub to get us an SSL certificate via Let's Encrypt. I've reached out to my contact at The Linux Foundation to make this change but am still waiting to hear back. I'll follow-up on that.

Best,

Misha 

[Alexandr Porunov]

Hi Misha,

Awesome! Thanks for your work on these issues. I will add some comments on github.

Best regards,

Alexandr Porunov

[Jan Jansen]

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

[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?

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

Best regards,

Oleksandr

[Jan Jansen]

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.

[Chris Hupman]

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.

[Jan Jansen]

Hi Chris,

The traefik docs has multiple version in their documentation, see here https://docs.traefik.io/. They uses the same system.

I would try to remove the most of doc generation from our current build system.

• The current build system need to used to generate the config ref file and javadoc.
  
• current tinkerpop version need to be extract from the pom.
• (If we want, we could add a small command to maven which calls mkdocs.
• I would like to have automatic checks of markdown
• For older release, i would prefer to use the old documentation, as it requires a lot of manual work.
• So, we can start with the janusgraph release 0.3.2 and 0.4.0.

This task would requires to rebase work on each changes of documentation.

I would prefer that following task should be done before merging:

• I will change page order to the current state
  
• Fix links
• Fix images
• Support a multiple versions (basic)
• linking old
• building into a defined folder for the branch version
  
• Integrate build system
• Automate config generation

Tasks can be done after merging in small PR:

• Add linter (markdown or spellchecker)
  
• Correct, all small issues in the current documentation
• Reorder and check documentation
• Check code examples and provide tinkerpop examples in different GLV, for example c# or python

--
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 janusgraph-de...@googlegroups.com.
To post to this group, send email to janusgr...@googlegroups.com.
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.

[Jan Jansen]

Traefik use tool written by them self called: https://github.com/containous/structor.

On 2/13/19 7:19 PM, Chris Hupman wrote:

--

[Jan Jansen]

I updated the docs and move it to a new location to test automate building.

https://farodin91.github.io/janusgraph/

Changes:

• old document structure
• fix some major rendering flaws
• fix multiple links
• fix all images

[Florian Hockmann]

I really like the design in this preview and the fact that it integrates the homepage with the docs (and the possible blog) in a single web site. The included search functionality is of course also a nice benefit.

However, before Jan puts in all the work to get everything right and production ready, I think that we need to decide in general whether we want to move in this direction. If we agree in general, that we want to move from our current AsciiDoc based stack to MkDocs based on Markdown, then we can still discuss about the specifics like a Markdown linter, integration in our build process and so on.

So, what do you guys think about this in general?

The advantages I see:

• A modern design without much work required (we just use a theme like Material).
• Markdown is easier to write than AsciiDoc. Most developers/users probably already know it.
  
• Docs and homepage integrated in a single page with the same design.
• Docs and homepage backed by the same repo, so they can be changed in a single commit (we sometimes have issues for janusgraph.org and the main repo to do the same change in both places right now).
• Search functionality included.
• It included edit links in the docs. This makes it easier for users to suggest changes.
  

Disadvantages I can think of:

• Markdown has less functionality than AsciiDoc, e.g., including source code from source files isn't supported afaik which would otherwise be a good option to ensure that code examples in the docs keep working (by compiling them and maybe including them in a test).
• We need to find solutions / workarounds for things like the TinkerPop version that is automatically included in all links to TinkerPop docs in the version JanusGraph uses for that version of the docs.
  

Chris, you asked:

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?

I think it only makes sense if we replace our current process completely by this. Maintaining two systems doesn't make much sense too me.

[Oleksandr Porunov]

I see more advantages in a new design than in the current, so I think that we should go for a new design.

 

• Markdown has less functionality than AsciiDoc, e.g., including source code from source files isn't supported afaik which would otherwise be a good option to ensure that code examples in the docs keep working (by compiling them and maybe including them in a test).

I didn't check, but do we use this AsciiDoc functionality? I think it is a good feature, but if we don't use it, then I think we don't lose this advantage. Also, even if we lose this advantage I don't think that it is a critical part right now.

• We need to find solutions / workarounds for things like the TinkerPop version that is automatically included in all links to TinkerPop docs in the version JanusGraph uses for that version of the docs.

Agree here. The first thing that come up to my mind is to use some text identifier (like ${TINKERPOP_VERSION}) instead of version and then use some script to replace that text in all files but I don't know if it is a good solution.

[Jan Jansen]

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.

[Jan Jansen]

I forgot to mention that code include doesn't not support includes with a selected line range.

[Jan Jansen]

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?

[Oleksandr Porunov]

I would propose creating a new temporary branch in JanusGraph main repo to work on documentation right now. In such case multiple members could work on moving to MkDocs.

What others think about it?

[Jan Jansen]

I would like to get help by directly editing markdown instead comment in the PR. Beside, we can test setup better using TravisCI and gh-pages.

[Florian Hockmann]

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

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 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.

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?

I didn't check, but do we use this AsciiDoc functionality?

No, we aren't using that right now to the best of my knowledge. I just think that it could be a good improvement in the future to ensure that our docs always work with their version of JanusGraph as it's easy to change something in the source code and then forget to update the docs accordingly. But I also wouldn't see this feature as a hard requirement. I just wanted to also list the disadvantages I can see so we can make an informed decision on this.

[Jan Jansen]

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

[Florian Hockmann]

OK, I just created an issue (#1420) and a feature branch based on the 0.2 branch:

https://github.com/JanusGraph/janusgraph/issues/1420

Jan, I suggest that you use that feature branch as the target branch for your PR. Tell me when you want it to be merged (just ping me directly in the PR). After that, everyone can contribute by submitting PRs to the feature branch which I will merge with only minimal review required as the formal review will only happen when we merge the feature branch to a release branch.

I suggest that we use issue #1420 to coordinate contributions on this from now on.

[Oleksandr Porunov]

Asking for the review of this PR: https://github.com/JanusGraph/janusgraph.org/pull/64