[Octave-bug-tracker] [bug #65412] Appendices: C updates and D could use an overhaul

[Nicholas Jankowski]

URL:
  <https://savannah.gnu.org/bugs/?65412>

                 Summary: Appendices: C updates and D could use an overhaul
                   Group: GNU Octave
               Submitter: nrjank
               Submitted: Mon 04 Mar 2024 12:47:40 PM EST
                Category: Documentation
                Severity: 2 - Minor
                Priority: 5 - Normal
              Item Group: Documentation
                  Status: None
             Assigned to: None
         Originator Name: 
        Originator Email: 
             Open/Closed: Open
                 Release: 9.0.90
         Discussion Lock: Any
        Operating System: Any
           Fixed Release: None
         Planned Release: None


    _______________________________________________________

Follow-up Comments:


-------------------------------------------------------
Date: Mon 04 Mar 2024 12:47:40 PM EST By: Nicholas Jankowski <nrjank>
Looking at the backmatter of the docs, we don't have any obsolete functions
listed after 5.1.0 (we deprecate for 2 major versions, so should there be any
v6 or v7 items added to appendix C? is that just a matter of parsing the NEWS
files?)  

Appendix D is Known Causes of Trouble has the sections:

"D.1 Actual Bugs we haven't fixed yet" - which just lists pager related issues
and a recommendation users look to the PROJECTS file for enhancement ideas. 
as we have (presently) 754 bug reports listed as Open&Confirmed, maybe we
should just point to the bug tracker?

"D.2 Reporting Bugs" which points people up a section to see if we already
know about it, then provides advice on determining if you actually found a
bug, telling you to go submit one on  bugs.octaev.org, but _don't_ email
reports to 'help-octave'  (which we don't use much anymore). Also a decent
section on how to make a useful bug report (probably could use a link to
explaining making a MWE.), finally a section on sending patches that might not
be entirely accurate anymore, including pointing to the no-longer-used
ChangeLog files.

"D.3 How to Get Help with Octave" which mainly points to the mailing lists

"D.4 How to distinguish between Octave and Matlab" - which contains a
functions script that can be run to _programmatically_ tell if you're running
Octave.   I think this should maybe be moved elsewhere.


I had never read through this Appendix before. We aren't the best at keeping
our docs up to date, I'm wondering if this whole section, or most of it,
should be streamlined, linked out, etc.











    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?65412>

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/