Bug 441809 - Kate: The Development version is behind the released version
Summary: Kate: The Development version is behind the released version
Status: RESOLVED INTENTIONAL
Alias: None
Product: docs.kde.org
Classification: Websites
Component: docs.kde.org (show other bugs)
Version: unspecified
Platform: openSUSE Linux
: NOR normal
Target Milestone: ---
Assignee: Documentation Editorial Team
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2021-08-31 11:27 UTC by Christopher Yeleighton
Modified: 2021-09-02 13:43 UTC (History)
2 users (show)

See Also:
Latest Commit:
Version Fixed In:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Christopher Yeleighton 2021-08-31 11:27:53 UTC
SUMMARY
The Kate Handbook [1] is supposed to be in the Development version --- but it reports version 21.04, which is behind the released version 21.08.

STEPS TO REPRODUCE
1. Read the Kate Handbook [1]!

OBSERVED RESULT
Revision Applications 21.04 (2021-03-06)

EXPECTED RESULT
Revision Applications 21.12 (TBD)

SOFTWARE/OS VERSIONS
Windows: 
macOS: 
Linux/KDE Plasma: openSUSE Tumbleweed 20210829
(available in About System)
KDE Plasma Version: 5.22.4
KDE Frameworks Version: 5.85.0
Qt Version: 5.15.2

ADDITIONAL INFORMATION
[1] <URL: https://docs.kde.org/trunk5/en/kate/kate/index.html >
Comment 1 groot 2021-08-31 12:12:14 UTC
The document was revised in the timeframe of 21.04; the document itself says that it documents Kate version 18.12, which -- judging from some of the test -- is the time when most of that handbook was written. 

That's not really surprising, since the documentation is a story about the software, and even if it is generated from the development branch of the repository, the story about the software remains whatever was most recently written.
Comment 2 Luigi Toscano 2021-08-31 12:12:30 UTC
The date is by policy the last revision of the documentation, to ensure the document is checked. It is not the last version of the application.
Comment 3 Christopher Yeleighton 2021-09-02 05:03:06 UTC
(In reply to Luigi Toscano from comment #2)
> The date is by policy the last revision of the documentation, to ensure the
> document is checked. It is not the last version of the application.

How often is documentation revised?
Comment 4 Yuri Chornoivan 2021-09-02 05:31:21 UTC
(In reply to Christopher Yeleighton from comment #3)
> (In reply to Luigi Toscano from comment #2)
> > The date is by policy the last revision of the documentation, to ensure the
> > document is checked. It is not the last version of the application.
> 
> How often is documentation revised?

When somebody spots interface changes, when there is a typo found somewhere, when developers want to add something, when it is needed for some other reason.
Comment 5 Christopher Yeleighton 2021-09-02 06:41:38 UTC
(In reply to Yuri Chornoivan from comment #4)
> (In reply to Christopher Yeleighton from comment #3)
> > (In reply to Luigi Toscano from comment #2)
> > > The date is by policy the last revision of the documentation, to ensure the
> > > document is checked. It is not the last version of the application.
> > 
> > How often is documentation revised?
> 
> When somebody spots interface changes, when there is a typo found somewhere,
> when developers want to add something, when it is needed for some other
> reason.

That looks like yesterday.  I am confused.
Comment 6 Yuri Chornoivan 2021-09-02 06:45:42 UTC
(In reply to Christopher Yeleighton from comment #5)
> (In reply to Yuri Chornoivan from comment #4)
> > (In reply to Christopher Yeleighton from comment #3)
> > > (In reply to Luigi Toscano from comment #2)
> > > > The date is by policy the last revision of the documentation, to ensure the
> > > > document is checked. It is not the last version of the application.
> > > 
> > > How often is documentation revised?
> > 
> > When somebody spots interface changes, when there is a typo found somewhere,
> > when developers want to add something, when it is needed for some other
> > reason.
> 
> That looks like yesterday.  I am confused.

This is not a question, it is a statement.
Comment 7 Christopher Yeleighton 2021-09-02 06:51:06 UTC
(In reply to Yuri Chornoivan from comment #6)
> This is not a question, it is a statement.

Under the assumption that the trunk documentation gets revised when updated, and given that it has recently been updated, why hasn’t it been revised?
Comment 8 Yuri Chornoivan 2021-09-02 06:52:31 UTC
(In reply to Christopher Yeleighton from comment #7)
> (In reply to Yuri Chornoivan from comment #6)
> > This is not a question, it is a statement.
> 
> Under the assumption that the trunk documentation gets revised when updated,
> and given that it has recently been updated, why hasn’t it been revised?

Because authors do not want to do so.
Comment 9 Christopher Yeleighton 2021-09-02 06:54:04 UTC
(In reply to Yuri Chornoivan from comment #8)
> Because authors do not want to do so.

I am an author now and I certainly want it to be revised.
Comment 10 Yuri Chornoivan 2021-09-02 06:54:50 UTC
(In reply to Christopher Yeleighton from comment #9)
> (In reply to Yuri Chornoivan from comment #8)
> > Because authors do not want to do so.
> 
> I am an author now and I certainly want it to be revised.

Ok. Do it.
Comment 11 Christopher Yeleighton 2021-09-02 06:56:42 UTC
(In reply to Yuri Chornoivan from comment #10)
> Ok. Do it.

If that is the case, may I reopen?
Comment 12 Yuri Chornoivan 2021-09-02 06:59:49 UTC
(In reply to Christopher Yeleighton from comment #11)
> (In reply to Yuri Chornoivan from comment #10)
> > Ok. Do it.
> 
> If that is the case, may I reopen?

How can I prohibit this? You have been said that nobody will implement this bikeshedding bug report now but you are free to reopen it.
Comment 13 Christopher Yeleighton 2021-09-02 07:01:35 UTC
(In reply to Yuri Chornoivan from comment #12)
> (In reply to Christopher Yeleighton from comment #11)
> > (In reply to Yuri Chornoivan from comment #10)
> > > Ok. Do it.
> > 
> > If that is the case, may I reopen?
> 
> How can I prohibit this? You have been said that nobody will implement this
> bikeshedding bug report now but you are free to reopen it.

What do you mean by nobody?  I am somebody for sure.
Comment 14 Luigi Toscano 2021-09-02 07:50:19 UTC
This bug is not a bug and shall stay closed.
Comment 15 Christopher Yeleighton 2021-09-02 10:45:02 UTC
(In reply to Luigi Toscano from comment #14)
> This bug is not a bug and shall stay closed.

Which part of the information provided by Yuri is incorrect?
Comment 16 Luigi Toscano 2021-09-02 10:49:16 UTC
(In reply to Christopher Yeleighton from comment #15)
> (In reply to Luigi Toscano from comment #14)
> > This bug is not a bug and shall stay closed.
> 
> Which part of the information provided by Yuri is incorrect?

Please see my initial answer. Don't report further "the documentation is outdated" bugs.
Comment 17 Christopher Yeleighton 2021-09-02 11:58:31 UTC
(In reply to Luigi Toscano from comment #16)
> Please see my initial answer. Don't report further "the documentation is
> outdated" bugs.

How often is documentation revised?
Comment 18 Jack 2021-09-02 13:43:25 UTC
Documentation is updated when someone updates it.  There is no automatic updating just because the program it documents gets updated.  There is no regular schedule for updating documentation.  The issue is that the developers who updated the code do not usually update the documentation, so that task simply waits until someone willing to update the documentation does so.  A very few application have dedicated folks who maintain their docs, but most depend on a core crew of doc writers.  

A bug is not necessary to update documentation - an email to the doc team's mailing list is likely to work as well.  The documentation files include the version of the program for which the docs were last updated, and the date those updates were done.  For the reasons above, these often do lag behind the current version of the program.  That is not a bug, but an unfortunate reality.