Обсуждение: New member - where to begin

While at PgConf West 2009 JD mentioned there is a need to review and
possibly update the Pg documentation.

I'm here and wondering where to start.  :-)

A few questions that come to mind:

* Is there an area that needs the most attention?

* Is flavor-rite topics alright or what most do?

* What format? DocBook was mentioned.
   I prefer vim so what are your preferences for plugins-wise?

* Any Vim+DocBook or DocBook howtos/tutorials that you would recommend?


\\||/
Rod
--

On Fri, 23 Oct 2009, Roderick A. Anderson wrote:

> * What format? DocBook was mentioned.

http://developer.postgresql.org/pgdocs/postgres/docguide.html is the main
intro to this area and the latest docs available.  You'll need to check
out the current release from CVS or git to generate patches; see
http://wiki.postgresql.org/wiki/Development_information for guides to both
of those.

>  I prefer vim so what are your preferences for plugins-wise?
> * Any Vim+DocBook or DocBook howtos/tutorials that you would recommend?

For the most part simple changes are easy enough to make; just mimic the
style of similar markup and confirm the docs still build after your
change.  I'd recommend using a version control system where you can track
your diffs easier and commit in stages, particularly when getting started.
That makes it easier to figure out what broke after a bad change and you
can incrementally save successful changes until you get more comfortable.

If you have the full vim set (vim-enhanced on Fedora/RHEL, vim-full on
Debian/Ubuntu), there is some assistance the editor can provide.  There's
a quick intro to helpful features to toggle at
http://docs.fedoraproject.org/documentation-guide/en_US/ch-vim.html and a
much longer discussion of macros at
http://www.linuxjournal.com/article/7737 ; you really don't need anything
beyond simple customizations in most cases though, simple tool assistance
and cut/paste example copying is plenty if you're not authoring a serious
docbook work from scratch.

One helpful thing you might do right off the bat is update section I.4
"Documentation Authoring" with a section covering vim, to match the one
already there for emacs, to include whatever you find works here.
Getting documentation updates from patch authors is always hard to do, and
some better information to help them accomplish that would be valuable.

--
* Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD

Greg Smith wrote:
> On Fri, 23 Oct 2009, Roderick A. Anderson wrote:
>
>> * What format? DocBook was mentioned.
>
> http://developer.postgresql.org/pgdocs/postgres/docguide.html is the
> main intro to this area and the latest docs available.  You'll need to
> check out the current release from CVS or git to generate patches; see
> http://wiki.postgresql.org/wiki/Development_information for guides to
> both of those.

Thanks Greg.

>
>>  I prefer vim so what are your preferences for plugins-wise?
>> * Any Vim+DocBook or DocBook howtos/tutorials that you would recommend?
>
> For the most part simple changes are easy enough to make; just mimic the
> style of similar markup and confirm the docs still build after your
> change.  I'd recommend using a version control system where you can
> track your diffs easier and commit in stages, particularly when getting
> started. That makes it easier to figure out what broke after a bad
> change and you can incrementally save successful changes until you get
> more comfortable.

Sounds good.

> If you have the full vim set (vim-enhanced on Fedora/RHEL, vim-full on
> Debian/Ubuntu), there is some assistance the editor can provide.
> There's a quick intro to helpful features to toggle at
> http://docs.fedoraproject.org/documentation-guide/en_US/ch-vim.html and
> a much longer discussion of macros at
> http://www.linuxjournal.com/article/7737 ; you really don't need
> anything beyond simple customizations in most cases though, simple tool
> assistance and cut/paste example copying is plenty if you're not
> authoring a serious docbook work from scratch.

I found both of these so will do a more in depth reading.

> One helpful thing you might do right off the bat is update section I.4
> "Documentation Authoring" with a section covering vim, to match the one
> already there for emacs, to include whatever you find works here.
> Getting documentation updates from patch authors is always hard to do,
> and some better information to help them accomplish that would be valuable.

This will be the first thing I work on.


\\||/
Rod
--
> --
> * Greg Smith gsmith@gregsmith.com http://www.gregsmith.com Baltimore, MD
>