[pve-devel] [PATCH docs] Add a new top level chapter on how to improve the reference documentation

[Fabian Grünbichler]

This seems to duplicate almost the complete "Getting help" subsection,
although with more detail. Maybe it makes sense to merge both and move
the result to the first section ("Introduction")?

IMHO that is a better fit for such information, and it would also be
closer to the beginning of the documentation - and harder to miss ;)

For the actual "improve the documentation" part, it might make sense to
reference the README.(adoc|html) files.

Minor nitpick for that part: simply adding to or fixing parts of the
documentation does not require a dev or PVE setup at all - only updating
the files which are automatically generated from our API schema does.

On Wed, Sep 21, 2016 at 02:24:27PM +0200, Emmanuel Kasper wrote:
> ---
>  Makefile             |  1 +
>  index.adoc           |  1 +
>  pve-admin-guide.adoc |  2 ++
>  pve-improve.adoc     | 37 +++++++++++++++++++++++++++++++++++++
>  4 files changed, 41 insertions(+)
>  create mode 100644 pve-improve.adoc
> 
> diff --git a/Makefile b/Makefile
> index 0acaedf..a8205b0 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -29,6 +29,7 @@ CHAPTER_LIST=		\
>  	ha-manager	\
>  	vzdump		\
>  	pve-faq		\
> +	pve-improve     \
>  	pve-bibliography
>  
>  STORAGE_TYPES=		\
> diff --git a/index.adoc b/index.adoc
> index 95c67ab..05d77cf 100644
> --- a/index.adoc
> +++ b/index.adoc
> @@ -32,6 +32,7 @@ Individual Chapters
>  |High Availability                    |link:chapter-ha-manager.html[]
>  |Backup and Restore                   |link:chapter-vzdump.html[]
>  |Frequently Asked Questions           |link:chapter-pve-faq.html[]
> +|Improving the {pve} documentation    |link:chapter-pve-improve.html[]
>  |Bibliography                         |link:chapter-pve-bibliography.html[]
>  |===========================================================
>  
> diff --git a/pve-admin-guide.adoc b/pve-admin-guide.adoc
> index 1f98eed..ac68406 100644
> --- a/pve-admin-guide.adoc
> +++ b/pve-admin-guide.adoc
> @@ -63,6 +63,8 @@ include::pvesubscription.adoc[]
>  
>  include::pve-faq.adoc[]
>  
> +include::pve-improve.adoc[]
> +
>  include::pve-bibliography.adoc[]
>  
>  :leveloffset: 0
> diff --git a/pve-improve.adoc b/pve-improve.adoc
> new file mode 100644
> index 0000000..8977d2a
> --- /dev/null
> +++ b/pve-improve.adoc
> @@ -0,0 +1,37 @@
> +How to report errors and improve the {pve} documentation
> +========================================================
> +include::attributes.txt[]
> +
> +Depending on which issue you want to improve, you can use a variety of
> +communication mediums to reach the developers.
> +
> +First if you're not sure about something explained in this documentation,
> +create an account on https://forum.proxmox.com/[Proxmox Forums] or use the
> +http://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-user[pve-users mailing
> +list]. Enterprise customers can use their dedicated support portal where they
> +have a guaranteed response time.
> +
> +If you notice an error in the current documentation, use the 
> +http://bugzilla.proxmox.com[Proxmox bug tracker] and propose an 
> +alternate text/wording.
> +
> +If you want to propose new content, it depends on what you want to
> +document:
> +
> +* if the content is specific to your setup, a wiki article is the best
> +option. For instance if you want to document specific options for guest
> +systems, like which combination of Qemu drivers work best with the NetBSD OS,
> +this is a perfect fit for a wiki article.
> +
> +* if you think the content is generic enough to be of interest for all users,
> +then you should try to get it in the reference documentation. The reference
> +documentation is written in the easy to use asciidoc text document format, ,
> +from which HTML pages, man pages and mediawiki articles are generated. Editing
> +the official documentation requires a
> +https://pve.proxmox.com/wiki/Developer_Documentation[developer setup] and to
> +checkout the documentation from the pve-docs.git repository at
> +git://git.proxmox.com/git/pve-docs.git.
> +
> +Improving the documentation is just as easy as editing a Wikipedia
> +article and is an interesting foray in the development of a large
> +opensource project.
> -- 
> 2.1.4
> 
> 
> _______________________________________________
> pve-devel mailing list
> pve-devel at pve.proxmox.com
> http://pve.proxmox.com/cgi-bin/mailman/listinfo/pve-devel