Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: move docs from www/documentation/head #744

Merged
merged 2 commits into from Feb 7, 2017
Merged

Conversation

@jorsol
Copy link
Member

@jorsol jorsol commented Feb 3, 2017

Move documentation from www/documentation/head/ to pgjdbc/docs/

This makes easy to update the documentation when a change is made to the driver, so this will allow to evolve the documentation along with the driver.

There will be a manual procedure to copy contents from docs, back to the hosting in documentation/head/ but I think the advantage outweighs the disadvantage.

[skip ci]

Move documentation from www/documentation/head/ to pgjdbc/docs/

This makes easy to update the documentation when a change is
made to the driver.

[skip ci]
@davecramer davecramer merged commit 70e23c4 into pgjdbc:master Feb 7, 2017
2 checks passed
Loading
@vlsi
Copy link
Member

@vlsi vlsi commented Feb 12, 2017

@jorsol , what was that?
Why is this just a subset of pgjdbc/www?

I thought the idea was to move full contents of pgjdbc/www to pgjdbc/pgjdbc/docs

@davecramer , should other contents from pgjdbc/www be moved to the main repository?

Loading

@jorsol
Copy link
Member Author

@jorsol jorsol commented Feb 12, 2017

@vlsi , this is just head documentation, is a subset because the idea is to update documentation when a change is made to the driver in a single shot, there is no point in having whole (historic) documentation here, the documentation should evolve with the driver, and the history/old documentation should remain in pgjdbc/www.

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 12, 2017

How do you think website should be built?
How do you tell if documentation/changelog.md belongs to head or not?

The beauty of having all the docs in one place is:

  1. simplified site build
  2. simplified cross-references

Loading

@davecramer
Copy link
Member

@davecramer davecramer commented Feb 12, 2017

I'm starting to have second thoughts about this idea, perhaps it is not such a good idea. I doubt there is any way to build it,

Loading

@jorsol
Copy link
Member Author

@jorsol jorsol commented Feb 12, 2017

  1. Yes, there is a two-step site build using this aproach, but the reasoning behind this is to have simplified documentations updates in the same PR of modifications to the driver (without a separate PR to www), so basically it's simplify the update of documentation, or simplify the build process. IMO the advantage of update the documentation overcome the site build, and BTW the current documentation is a little outdated with references to Ant, JDK1.4/1.5, etc. and it doesn't help to have it in a separate location.

  2. And what are those cross-references? the documentation is pretty much standalone, and there is no references to older parts, as it's essentially a copy of the older one.

How do you tell if documentation/changelog.md belongs to head or not?

documentation/changelog.md never belongs to head as there is no reference to head on it, just to released versions, which by definition are not head. If for instance for every change made to the driver the changelog.md is updated, then yes, it contains head. but it's not the case.

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 12, 2017

@davecramer , Do you intend to build site from both pgjdbc/www and pgjdbc/pgjdbc/docs sources?

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 12, 2017

  1. And what are those cross-references?

For instance:

  • Ability to navigate between versions of the same page
  • Reference specific pages in the changelog page

Loading

@jorsol
Copy link
Member Author

@jorsol jorsol commented Feb 12, 2017

The build process is:
pgjdbc/www/: jekyll build
pgjdbc/pgjdbc/docs/: jekyll build
copy pgjdbc/docs/_site/ to pgjdbc/www/_site/documentation/head/

That's all... and yes there should be a build from both.

There is no such navigation between versions of the same page, and since the pgjdbc follows a linear development (there will be no further maintainace to the 9.4 branch) there is no point in having that.

And I haven't seen any references to documentation in changelog page, and even if there is a reference, it should be the same as having the documentation in www.

But if you think that having the documentation outside where nobody looks at, then it's ok, I can send a PR moving it again to www.

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 12, 2017

There is no such navigation between versions of the same page

Do you think lack of that navigation is good? I don't think so.

moving it again to www

I think of moving all the documentation to pgjdbc/pgjdbc.

@davecramer , any thoughts?

Loading

@davecramer
Copy link
Member

@davecramer davecramer commented Feb 12, 2017

Loading

@jorsol
Copy link
Member Author

@jorsol jorsol commented Feb 12, 2017

@vlsi , to be clear, you prefer to have all documentation directory in pgjdbc/docs? This will include the faq.md and changelog.md.

The only problem I see is that those are part of the website (they follow the same style), and to move all that to pgjdbc/docs/ whould require some more refactoring. In fact the full website and documentation require a refresh.

Loading

@jorsol
Copy link
Member Author

@jorsol jorsol commented Feb 12, 2017

I think moving it back would be easier.

As I said, it would be easier to build but harder to update, so it's up to you Dave since you have the keys to upload the content to jdbc.postgresql.org.

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 12, 2017

In the mean time I don't think we could proceed with 42.0.0 release with documentation in a half-split state.

At least, we have two copies of documentation/head (in pgjdbc/www, and in pgjdbc/pgjdbc/docs)

As I said, I would prefer having documentation (as well as things like changelog) and code in a single repository for the following reasons:

  1. Less hassle to update code, since the documentation can be updated in the same commit
  2. Simplified regression analysis (e.g. commit that adds a specific property in the doc can be tracked to the code change)
  3. Simplified validation of the contributions: having doc&code in the same repository makes it easier to validate if a change is covered with a relevant doc change
  4. "Notable changes" changelog entry could be added side-by-side with the relevant code change.
  5. Cool things like "run doc examples during build process" (that is automatic validation of documentation code samples against current codebase) will be possible.
  6. I don't think site build process depends on the repository that stores the site be it pgjdbc/www or pgjdbc/pgjdbc.

I don't see much downsides of moving all the www contents to pgjdbc/pgjdbc repository:

  1. Repository size would increase a bit. That would be negligible

I might miss something, so I'm open to hear opinions why having separate pgjdbc/www repository is preferable.

Loading

@davecramer
Copy link
Member

@davecramer davecramer commented Feb 13, 2017

Loading

@jorsol
Copy link
Member Author

@jorsol jorsol commented Feb 13, 2017

Does move all means the complete website?

Loading

@jorsol jorsol deleted the move-docs branch Feb 13, 2017
@vlsi
Copy link
Member

@vlsi vlsi commented Feb 13, 2017

Does move all means the complete website?

I'm sure it does.

Loading

@davecramer
Copy link
Member

@davecramer davecramer commented Feb 13, 2017

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 13, 2017

yes, it doesn't include the downloads so it is just documentation.

I'm puzzled.
Does it really make sense to split the website into several repositories?

Loading

@davecramer
Copy link
Member

@davecramer davecramer commented Feb 13, 2017

Loading

@vlsi
Copy link
Member

@vlsi vlsi commented Feb 13, 2017

I meant the actual artefacts. The download section will be there, but not
the actual files.

Agreed. jar/tar, etc should not be placed to pgjdbc/pgjdbc repository.
On the other hand, all the "source" *.md files to be moved from www to pgjdbc.

Loading

davecramer added a commit to davecramer/pgjdbc that referenced this issue Sep 19, 2017
* docs: move docs from www/documentation/head

Move documentation from www/documentation/head/ to pgjdbc/docs/

This makes easy to update the documentation when a change is
made to the driver.

[skip ci]

* update intro
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants