|
From: | James |
Subject: | Re: who needs script `update-patch-version`? |
Date: | Mon, 1 Feb 2021 16:22:01 +0000 |
User-agent: | Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.7.0 |
On 01/02/2021 15:06, Werner LEMBERG wrote:
Unfortunately, this is next to impossible since there are so many changes. I will provide a PDF that holds the changed pages so that you and others can simply read what's written there, comparing it with the current version of the Contributor guide if necessary.It was this condition (to provide small incremental changes) that made me abandon editing the docs many years ago. At the time I was part-way through a major reorganisation of 2.1 Vocal Music which I had to abandon as it was simply impossible to do it incrementally. Since then the docs have virtually stagnated. Hope you're able to work this out better than I was able to do, Werner.Well, I revise the stuff, I don't rewrite it, so it's definitely easier, I guess. The main thing is that these extra steps take a significant amount of time, which I think are not really justified for documentation changes (in contrast to code changes) and could be invested into more useful things.
Well if you are planning lots of these,I understand how frustrating it can be, as I've done a fair amount of re-writing sections myself (maybe not quite on the scale of Trevor's work but I have done a lot of 're-org' type checkins). However that all said, one man's 'significant amount of time' is another man's 'time well spent'. Why not just see/illustrate/prove how painful it really is (if it actually is after all with our new CI/Gitlab interface) and then afterwards we can all see how we could perhaps improve or bypass some/all countdown steps.
The main concern is that things get deleted (either deliberately or accidentally) which was always Graham P's concerns when I did large doc edits. So staging them as section moves and then rewrites is just safe even if it takes a bit longer.
Where it becomes tedious is the (IMHO) bike shedding or digressions about things that were not supposed to be the focus of said doc edit like grammar and spelling/punctuation for things not specifically listed in our style guide.
When everyone is a doc editor, no one is a doc editor right? James
[Prev in Thread] | Current Thread | [Next in Thread] |