Re: [pve-devel] applied-series: [PATCH v4 docs 0/7] Documenation overhaul chapt. 1.12 to 3.2

[Aaron Lauterer]

On 2/11/20 5:42 PM, Thomas Lamprecht wrote:

applied series, but not really happy how you just ignored Stefan's and
my comment about why you change title capitalization in just a single
patch (sys requirements one) to something nowhere else used in the docs..


I'm sorry I forgot to answer that. Our current technical writing style 
guide states that first and second level headlines should use title 
capitalization and starting with third level headlines sentence style 
should be used.


We can of course think about changing that, but changing the style guide 
too often will be problematic.



Fixed that up and made a few general followup patches, renaming the "USB
flash drive" to "Prepare Installation Media" and re-ordering it before
"Using the Proxmox VE Installer" which makes quite more sense.

IMO, a series and months-of-work effort called "overhauling the
documentation" should also care for such details, i.e., do a step backward
and see if the general order, flow, .. is all right and somewhat sound.
As else I'd rather just have "grammar + typo fixes" getting in in continuous
small patches and see bigger effort on expanding the documentation with new
content.


This patch series started a long time ago when I was anxious to not 
break anything (e.g. deep links). Therefore restructuring was saved for 
later.


___
pve-devel mailing list
pve-devel@pve.proxmox.com
https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel

[pve-devel] applied-series: [PATCH v4 docs 0/7] Documenation overhaul chapt. 1.12 to 3.2

[Thomas Lamprecht]

On 2/11/20 9:55 AM, Aaron Lauterer wrote:
> This is the first patch series aimed to overhaul our documentation. The
> main goal is to make it easier to understand and more consistent.
> Therefore the phrasing is changed in a lot of places, sometimes the
> ordering of content as well. I tried to align the source to the 80
> characters per line wherever possible.
> 
> The reason why this first patch series doesn't start at the very
> beginning is because we are not yet happy with few things there.
> 

applied series, but not really happy how you just ignored Stefan's and
my comment about why you change title capitalization in just a single
patch (sys requirements one) to something nowhere else used in the docs..
Fixed that up and made a few general followup patches, renaming the "USB
flash drive" to "Prepare Installation Media" and re-ordering it before
"Using the Proxmox VE Installer" which makes quite more sense.

IMO, a series and months-of-work effort called "overhauling the
documentation" should also care for such details, i.e., do a step backward
and see if the general order, flow, .. is all right and somewhat sound.
As else I'd rather just have "grammar + typo fixes" getting in in continuous
small patches and see bigger effort on expanding the documentation with new
content.

Thanks!

> v3 -> v4:
> fixed some phrasings and minor issues reported on v3
> 
> v2 -> v3:
> rebased on current master
> 
> v1[0] -> v2:
> 
> * incorporating suggestions received
> * moved line length and white space fixes to separate patch
> 
> [0] https://pve.proxmox.com/pipermail/pve-devel/2019-September/038938.html
> 
> Aaron Lauterer (7):
>   Overhaul Translation
>   Overhaul System Requirements
>   Overhaul Install from USB flash drive
>   Overhaul Sysadmin
>   Overhaul Package Repositories
>   OVerhaul System Software Updates
>   Fix whitespace and line length
> 
>  getting-help.adoc|   9 +-
>  howto-improve-pve-docs.adoc  |   4 +-
>  pve-installation.adoc|  14 ++--
>  pve-package-repos.adoc   | 154 ++-
>  pve-system-requirements.adoc |  75 +
>  pve-usbstick.adoc| 109 -
>  sysadmin.adoc|  40 -
>  system-software-updates.adoc |  25 +++---
>  translation.adoc |  37 +
>  9 files changed, 229 insertions(+), 238 deletions(-)
> 


___
pve-devel mailing list
pve-devel@pve.proxmox.com
https://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel