[jira] [Commented] (NIFI-3513) Publish versioned documentation

["Andy LoPresto (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/NIFI-3513?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16733818#comment-16733818 ] 

Andy LoPresto commented on NIFI-3513:
-------------------------------------

Matt Burgess and I had further conversation on this tonight and I wanted to capture it here. 

{quote}Andy LoPresto [19:36]
I’ll ask again in the morning, but once that PR ([PR 3242|https://github.com/apache/nifi/pull/3242] for [NIFI-5926|https://issues.apache.org/jira/browse/NIFI-5926]) is merged, I am considering updating the site with it even though it technically would be a 1.9.0 commit. It doesn’t change anything version specific in the docs, and it would be helpful to the community to have that additional information on the site earlier rather than wait for a release. However, the document structure has changed significantly in previous commits that have not yet been released, so it’s not a simple cherry-pick. 

Matthew Burgess [19:40]
I’m +1 on getting more doc out there early, but because of auto generation, I realize it can be a PITA.

Joe Witt [19:40]
if the bits are accessible such that the docs make sense- go for it

Andy LoPresto [19:53]
Ok. If Drew is available tomorrow I’ll discuss with him because he was the one who committed the reorganization changes. I think we can make it work.
If not, I’ll cherry pick those couple lines into our existing admin guide (generated HTML) and just update that directly, and when 1.9.0 is released, we’ll push all the new auto-generated stuff.
Thanks.

Matthew Burgess [20:00]
might be worth a look at a pattern, straight doc updates vs doc for added features, if y’all get something you’re comfortable with, let’s write it down :slightly_smiling_face:

Andy LoPresto [20:01]
Not sure I follow, Matt.
We have a collection of different document types:
• component docs
• guides
• APIs
The component docs are autogenerated and are release-specific.
Hence why we still host old versions on the website.
The guides _can_ have version-specific info, but they are not specifically tied to a version of the software.
Between 1.8.0 and 1.9.0, Drew re-organized the Admin Guide (and possibly others, I didn’t look exhaustively) into sub-guides to better streamline the resources.
I think this will be overall good for users.
The restructuring is independent of my change to add a couple lines; however, because of the restructuring, the location I _would_ add these lines is now the Toolkit Guide, rather than just in the giant Admin Guide.
So the least change solution for site users would be if I temporarily copied those lines into the Admin Guide and updated that directly.
And when 1.9.0 is released, the whole section(s) get restructured into the Toolkit Guide, as the code in master & PR is now, but this is not currently reflected on the site.
Done here: https://github.com/apache/nifi/pull/3155

Matthew Burgess [20:06]
I meant “missing doc” vs “new doc”, sorry I must have misunderstood the PR
when I add “missing doc” to a processor for example, it doesn’t show up until the next release, but it’s valid now (and possibly in the past)

Andy LoPresto [20:07]
And here’s the original that added the Toolkit Guide: https://github.com/apache/nifi/pull/3124
Ah, gotcha.

Matthew Burgess [20:07]
rgr, meant only to update docs to make things current (for the released version)

Andy LoPresto [20:08]
Yes, I personally feel that any time the “new” documentation is valid for the current release of the software, we should publish it as early as possible to help the community.
So if it refers to a feature/bug fix that won’t be available until 1.X+1.0, don’t publish it.
But if it enhances or further explains something that is currently true, publish.
I understand this could get complicated to track though.

Matthew Burgess [20:10]
Unless we’re shackled by Maven (https://issues.apache.org/jira/browse/NIFI-943 ?) I think it would be pretty helpful to populate upcoming doc (with the obvious caveat that it hasn’t happened yet)
maybe it’s not Maven but Apache servers
we don’t need to publish a whole snapshot release, but could we publish Javadoc, etc. for it?
not sure how cool Maven is (I’m a Groovy guy so Gradle lol) with maybe publishing to the Apache Wiki (as a Work In Progress)

Andy LoPresto [20:12]
There is a Jira to organize the docs better.
https://issues.apache.org/jira/browse/NIFI-3513
So once we do that, we could even have:
• 1.6.0
• 1.7.0
• 1.7.1
• 1.8.0
• _current_ (points to 1.8.0)
• _beta_ / _unreleased_ / _upcoming_ (frequently updated 1.9.0-SNAPSHOT)
This will help with Google indexing, long-term linking, etc.

Matthew Burgess [20:13]
YES that’s the one
on SO and HCC I recommend javadoc.io, which fetches them and tries to present them nicely

Andy LoPresto [20:14]
And that way we could script something that maybe runs nightly and pushes the 1.9.0-SNAPSHOT master docs to the site as _upcoming_.

Matthew Burgess [20:14]
after publish of course

Andy LoPresto [20:14]
So people running current master can still reference the site.
Ok. I think it would be good to copy this conversation to 3513 as well to document the upcoming part.{quote}

> Publish versioned documentation
> -------------------------------
>
>                 Key: NIFI-3513
>                 URL: https://issues.apache.org/jira/browse/NIFI-3513
>             Project: Apache NiFi
>          Issue Type: Improvement
>          Components: Documentation & Website
>            Reporter: Andy LoPresto
>            Priority: Minor
>              Labels: archive, documentation, versioning
>
> While NiFi is slightly different from most software projects in that every deployment contains a copy of the relevant documentation, it is still valuable to have versioned documentation available online:
> * archive canonical version of documentation
> * allow real-time comparison between versions
> * allow access to documentation without spinning up instance of NiFi locally
> I would propose a structure like the following but am open to other suggestions:
> * /docs/0.7.2/index.html
> * /docs/1.1.2/index.html
> * /docs/latest/index.html -> /docs/1.1.2/index.html
> * /docs.html -> /docs/latest/index.html
> The latter two redirects would be updated when a new release is published (only /latest/index.html would need to be manually updated). 
> The docs pages should also be updated to prominently display the version (I believe I have seen this in another browser, but in both Chrome and Firefox I do not see the version number in the HTML content anywhere). 



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)