Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Samuli Seppänen]

>
> It should be possible to write a little script which parses the wiki
> (page content) source text and makes man/html pages and example files
> based on this.  This could be done before each release.
>
> The drawback is that the wiki markup might be too flexible (too many
> features) and the parsing script might get complicated.
I'm pretty sure we can get the Wiki contents out in HTML format. And
there should be plenty of "HTML -> something" converters out there.

-- 
Samuli Seppänen
Community Manager
OpenVPN Technologies, Inc

irc freenode net: mattock

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[David Sommerseth]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 12/01/11 21:48, Jan Just Keijser wrote:
> Hi David,
> 
> David Sommerseth wrote:
>> -BEGIN PGP SIGNED MESSAGE-
>> Hash: SHA1
>>
>>
>> Hi folks!
>>
>> This is a little cry for help from us playing with the OpenVPN code.
>>
>> We have a quite good man page today with a lot of information.  But
>> maintaining it and to make sure it is up-to-date with all the features
>> OpenVPN supports is often not high up on the priority list.  In
>> addition, the current format (one single file, in pure man page format)
>> is getting harder and harder to maintain as well.
>>
>> So, we're hoping some people with some English skills is interested to
>> help out improving this situation.  What we immediately would like to
>> see is something along these lines:
>>
>> * Move the man page to a better format than the pure man page format.
>>   Are there some good tools/formats like ascii2man or DocBookXML which
>>   could help easing the maintenance of our documentation?
>>
>> * Split up the documentation into more focused sections, like
>>   - main openvpn page (kind of like openvpn.8 today)
>>   Gives an executive overview over OpenVPN, features and references
>>   to the other documentation pages.  A bonus would be if it easily
>>   can produce other formats in addition, like HTML, PS/PDF, ePub.
>>
>>   - openvpn common options
>>   Gives information about the common options openvpn has, which is
>>   useful on both server and client instances.  F.ex. --keepalive,
>>   --tls-auth, --cert, --key, --ca, etc
>>
>>   - openvpn server options
>>   Describes only the options which are relevant for openvpn servers
>>
>>   - openvpn client options
>>   Describes only options useful for openvpn clients
>>
>>   - openvpn plug-ins
>>   Describes the different script plug-in hooks and environment
>>   variables available to scripts and plug-ins written in C
>>
>> * Review the contents of all the documentation, check their accuracy
>>   - Make sure no options are not available in OpenVPN 2.2 or later
>>   - Make sure no options are missing in the documentation, which is
>> available in the source code  (options.c is a good reference)
>>
>> * Review and check if all external references
>>   - Make sure all references to external sources, like web-sites, are
>> still available, valid and relevant in the document context
>>   - Find other external resources which are worth including.
>>
>> (These points are not carved into stone, but is more like a guideline of
>> what needs to be considered)
>>
>> This task should hopefully not require too much in-depth development
>> knowledge.  It should be user-focused, so that we avoid using terms and
>> details which is not so easy to understand.  What I'm saying is that
>> this documentation can be more useful and readable if users are involved
>> in this process.
>>
>> If someone are willing to step up and take a lead, that would be great!
>>  Further, discussions and reviews of the document changes should
>> probably happen on the openvpn-users mailing list.  That way, it might
>> be easier for users to review the documentation and provide feedback.
>>
>> We don't want this to just be a solo-project from someone in our OpenVPN
>> community, so we hope more people can help out and contribute, also if
>> you don't consider yourself a developer.
>>   
> I'd be willing to contribute but I don't see myself leading this effort
> right now (due to other obligations).

That's just fine!  And I presume you're not the only one loaded with
other tasks.  I believe if every one contributes a little bit according
to available time, big efforts will be achieved in the end.  Just
reading suggestions and giving comments are also much appreciated!

> As for the document format: if we want users to contribute then we
> should not opt for a too-difficult format that users would have to learn
> before being able to contribute. Docbook and/or texinfo are nice for
> Linux users but you'd scare away most Windows/Mac users.
> What about plain simple OpenDoc (odf) ?

I've been thinking about that we need to lower the level for
contributing documentation.  ODF isn't such a bad suggestion, after all
it is XML based and with strict style usage it should be possible to do
some script magic on these files.  However, why not lower the bar even
more?  (And I do see Karl O. Pinc's comment as well, people would need
to install ODF compliant software)

Krzee on IRC simply asked, why not use wiki for this purpose?  I
personally think that is a very good idea!  For the reasons:

* Simple formatting but still some structured way of organising the
  contents
* Many users are familiar with wikis, and the learning curve is usually
  low.
* No special software required, all you need is a browser
* No git knowledge needed
* Revision control is built into the wiki (and on community wiki, login
  is required - so we can trace who did what)

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Karl O. Pinc]

On 01/12/2011 02:48:29 PM, Jan Just Keijser wrote:

> As for the document format: if we want users to contribute then we 
> should not opt for a too-difficult format that users would have to
> learn 
> before being able to contribute. Docbook and/or texinfo are nice for 
> Linux users but you'd scare away most Windows/Mac users.
> What about plain simple OpenDoc (odf) ?

If you say so.  (It's not as if they haven't seen html,
which is superficially similar to docbook/xml,
or haven't they?)  But they could install and use lyx
and get a full-gui experience.  They'll have to install
something anyway if they want to use odf.



Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Jan Just Keijser]

Hi David,

David Sommerseth wrote:

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1


Hi folks!

This is a little cry for help from us playing with the OpenVPN code.

We have a quite good man page today with a lot of information.  But
maintaining it and to make sure it is up-to-date with all the features
OpenVPN supports is often not high up on the priority list.  In
addition, the current format (one single file, in pure man page format)
is getting harder and harder to maintain as well.

So, we're hoping some people with some English skills is interested to
help out improving this situation.  What we immediately would like to
see is something along these lines:

* Move the man page to a better format than the pure man page format.
  Are there some good tools/formats like ascii2man or DocBookXML which
  could help easing the maintenance of our documentation?

* Split up the documentation into more focused sections, like
  - main openvpn page (kind of like openvpn.8 today)
  Gives an executive overview over OpenVPN, features and references
  to the other documentation pages.  A bonus would be if it easily
  can produce other formats in addition, like HTML, PS/PDF, ePub.

  - openvpn common options
  Gives information about the common options openvpn has, which is
  useful on both server and client instances.  F.ex. --keepalive,
  --tls-auth, --cert, --key, --ca, etc

  - openvpn server options
  Describes only the options which are relevant for openvpn servers

  - openvpn client options
  Describes only options useful for openvpn clients

  - openvpn plug-ins
  Describes the different script plug-in hooks and environment
  variables available to scripts and plug-ins written in C

* Review the contents of all the documentation, check their accuracy
  - Make sure no options are not available in OpenVPN 2.2 or later
  - Make sure no options are missing in the documentation, which is
available in the source code  (options.c is a good reference)

* Review and check if all external references
  - Make sure all references to external sources, like web-sites, are
still available, valid and relevant in the document context
  - Find other external resources which are worth including.

(These points are not carved into stone, but is more like a guideline of
what needs to be considered)

This task should hopefully not require too much in-depth development
knowledge.  It should be user-focused, so that we avoid using terms and
details which is not so easy to understand.  What I'm saying is that
this documentation can be more useful and readable if users are involved
in this process.

If someone are willing to step up and take a lead, that would be great!
 Further, discussions and reviews of the document changes should
probably happen on the openvpn-users mailing list.  That way, it might
be easier for users to review the documentation and provide feedback.

We don't want this to just be a solo-project from someone in our OpenVPN
community, so we hope more people can help out and contribute, also if
you don't consider yourself a developer.
  
I'd be willing to contribute but I don't see myself leading this effort 
right now (due to other obligations).
As for the document format: if we want users to contribute then we 
should not opt for a too-difficult format that users would have to learn 
before being able to contribute. Docbook and/or texinfo are nice for 
Linux users but you'd scare away most Windows/Mac users.

What about plain simple OpenDoc (odf) ?

cheers,

JJK

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Karl O. Pinc]

On 01/12/2011 02:40:00 AM, Matthias Andree wrote:
> Am 11.01.2011 12:20, schrieb David Sommerseth:
> > 
> > Hi folks!
> > 
> > This is a little cry for help from us playing with the OpenVPN 
> code.
> > 
> > We have a quite good man page today with a lot of information.  But
> > maintaining it and to make sure it is up-to-date with all the
> features
> > OpenVPN supports is often not high up on the priority list. 

Don't accept a patch unless the documentation is also patched?

 In
> > addition, the current format (one single file, in pure man page
> format)
> > is getting harder and harder to maintain as well.
> > 
> > So, we're hoping some people with some English skills is interested
> to
> > help out improving this situation.  What we immediately would like
> to
> > see is something along these lines:
> > 
> > * Move the man page to a better format than the pure man page
> format.
> >   Are there some good tools/formats like ascii2man or DocBookXML
> which
> >   could help easing the maintenance of our documentation?
> 
> Docbook XML for sure is a lot more verbose than asciidoc or roff.  I
> would tend
> to avoid Docbook, the toolchains are lacking a bit -- still :-(
> although xmlto +
> fop can yield reasonable PDF results.

This is a matter of taste.  I'd turn that on it's head and say
that Docbook is a lot more clear than roff.  How hard is stuff
like:

Overview
...

With an editor like emacs or lyx it's not even much more typing 
and you get built-in validation, etc.

I'm not sure I understand the tool criticism.  There's pdf and
html and all the other basic outputs.  You can use the
xinclude mechanism  to produce different documents from 
components broken into files.  So there can be a man page,
a reference book, a "pocket reference" with just a table
of arguments, etc, some content of which is shared and
some of which is unique to each document.  If you 
like you've all of xml and xslt
and so forth to manipulate the documents dynamically allowing
you to, say, suck an example configuration straight out of
the documentation into a text file to be distributed in
an examples directory to be installed with openvpn.
This way you don't maintain the same example in two places.

> 
> However, we should make sure that there still is something that works
> with "man".

Docbook should do man.  I've never actually done it but
here's a whole series of tags that 
support all the man-like formatting at the top of the man page
what with marking each argument etc.
Frankly, that's where you'll see the ugly verbosity.  Plain old
paragraphs and so forth are plainless.  But once the top of the
man page is done once you pretty much don't have to make changes
or if you do then you've an example to work from.




Karl 
Free Software:  "You don't pay back, you pay forward."
 -- Robert A. Heinlein

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Stefan Monnier]

>> * Move the man page to a better format than the pure man page format.
>> Are there some good tools/formats like ascii2man or DocBookXML which
>> could help easing the maintenance of our documentation?

> Docbook XML for sure is a lot more verbose than asciidoc or roff.
> I would tend to avoid Docbook, the toolchains are lacking a bit --
> still :-( although xmlto + fop can yield reasonable PDF results.

I'd recommend Texinfo: its man output is not too bad (especially if you
write the Texinfo with "man" in your mind), it can be turned into
many other formats (including Docbook) and it's not verbose.


Stefan

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Matthias Andree]

Am 12.01.2011 11:18, schrieb David Sommerseth:

> But if we could manage to produce, say chm files (or whatever is the
> standard nowadays) for windows, that would be a big improvement as well.
>  Otherwise, a HTML file (like now, I believe) is better than nothing.

I don't personally care much for the Windows Help fad of the day.

You can use doclifter or manserver or an up-to-date groff to convert the roff
man format to HTML, and htmldoc to further convert this to PDF.  No need to
change anything.

> In the -users mailing list and on the #openvpn IRC channel, it is
> obviously that many struggle to find/understand the available
> documentation.  OpenVPN is very extensive and flexible, but with that
> comes complexity, especially when describing it all at once (like the
> man page does).  So this is an area where we should improve.

Well, roff-based manual pages support sectioning through .SH and .SS for what
you'd call H1 and H2 in HTML.

It's a shortcoming in man(1) if that's not supported properly; and it's a
shortcoming of the documentation as a whole (not necessarily the manual page) if
there's nothing that takes a new user by the hand to show him how to get 
started.

Adding more documentation, or duplicating information, however, makes it more
difficult to maintain -- and see below for a fully-fledged overview.  You'll
probably want to assemble a full manpage with all the options rather sooner than
later if you split.

Plus, the manual page is mostly a reference, and should be kept as such.  I have
no objections to adding howto or intro or overview manpages, or mode-specific
takeouts, if they are generated automatically (probably a few lines of awk or
perl suffice if you agree on comment mark-up in the manpage).  Don't duplicate
information!

> I believe one of the issues is that a lot of this comprehensive
> information is compressed into to few separate files, which can make it
> daunting and intimidating really reading the documentation.  Further,

The issue isn't reading the manual page (virtually nobody reads it all through
from a to z), but finding the right pieces for the desired application at hand.

> the usage of specific terms might make it more difficult to understand
> the document they are reading.  Parts of the documentation do take it
> for granted that the reader knows a lot to start with, which often is
> not the reality.

Target group check please.  The reference must not paraphrase or describe but
needs to be concise, precise, and use the proper terms, to avoid ambiguities.
Explanations of the specific technical terms belong into a glossary and possibly
an introductory document.

> Second, maintaining the current man document is a hassle and can be
> intimidating for people not having written man pages before.  In
> addition, the size of the current man page makes it even more difficult
> to make sure it is up-to-date.  Which is also a reason I would like to
> split it up into more pieces and a different format than a raw man page
> file.

As though that would make things more concise for the editor and thus
maintenance easier.  If you think it does, let me know how I should structure my
workflow for that to become true.

> I've taken some of the ideas for categorisation splits from the git man
> pages.  It is quite easy to know where to look when you don't know where
> to look, and where to look when you know what you are looking for.
> That's kind of my main idea.  Further, take out the more advanced things
> (like plug-ins) and put the gory details in a separate place, which must
> be referenced in the server/client man pages.  This way users will not
> be distracted too much with options which are not necessarily related to
> what they need or are looking for.

And I've seen users complain that Postfix (the Mail Transfer Agent,
) didn't have one single manual page to collect *all*
options; now there is one. :-)

> The reason for splitting client and server options is also to avoid
> confusion about which options can be used in which mode.  It grouped
> correctly in the man page today, but when you scroll up and down in the
> man page it is easy to loose overview of which "mode" you are reading about.

An issue of the man(1) tool that doesn't show a breadcrumb trail or a sidebar
with bookmarks like many PDF viewers can do, and easily rectified by converting
the roff manpage into a proper PDF document.

> If the "entry" man page also would cover a little bit generic VPN and
> networking with VPN basics, referencing other man pages to tools like
> ip, ifconfig, route, brctl, etc, it might help new users to understand a
> little bit more as well.

And needs to be system-specific in that very instant because the tools are.

> Another thing, just as a side note, easy-rsa could really use a man page
> as well.

True enough, but better placed in a separate thread on the lists, and I suppose
you'll collect volunteers much more easily for this much smaller 

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[David Sommerseth]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 12/01/11 09:40, Matthias Andree wrote:
> Am 11.01.2011 12:20, schrieb David Sommerseth:
>>
>> Hi folks!
>>
>> This is a little cry for help from us playing with the OpenVPN code.
>>
>> We have a quite good man page today with a lot of information.  But
>> maintaining it and to make sure it is up-to-date with all the features
>> OpenVPN supports is often not high up on the priority list.  In
>> addition, the current format (one single file, in pure man page format)
>> is getting harder and harder to maintain as well.
>>
>> So, we're hoping some people with some English skills is interested to
>> help out improving this situation.  What we immediately would like to
>> see is something along these lines:
>>
>> * Move the man page to a better format than the pure man page format.
>>   Are there some good tools/formats like ascii2man or DocBookXML which
>>   could help easing the maintenance of our documentation?
> 
> Docbook XML for sure is a lot more verbose than asciidoc or roff.  I would 
> tend
> to avoid Docbook, the toolchains are lacking a bit -- still :-( although 
> xmlto +
> fop can yield reasonable PDF results.
> 
> However, we should make sure that there still is something that works with 
> "man".

Agreed!  man pages should not go away, that is the main place to find
documentation on the *nix platform.  In fact, in most Linux
distributions it is a requirement to provide man pages to packages there.

But if we could manage to produce, say chm files (or whatever is the
standard nowadays) for windows, that would be a big improvement as well.
 Otherwise, a HTML file (like now, I believe) is better than nothing.

>> * Split up the documentation into more focused sections, like
>>   - main openvpn page (kind of like openvpn.8 today)
>>   Gives an executive overview over OpenVPN, features and references
>>   to the other documentation pages.  A bonus would be if it easily
>>   can produce other formats in addition, like HTML, PS/PDF, ePub.
>>
>>   - openvpn common options
>>   Gives information about the common options openvpn has, which is
>>   useful on both server and client instances.  F.ex. --keepalive,
>>   --tls-auth, --cert, --key, --ca, etc
> 
> Should be part of the main page.
> 
>>   - openvpn server options
>>   Describes only the options which are relevant for openvpn servers
>>
>>   - openvpn client options
>>   Describes only options useful for openvpn clients
> 
> Not sure if that's useful and actually reduces confusion this way.
> 
> Basically what you want is more (a) a concise HOWTO (more or less in place on
> the website), and (b) an exhaustive reference, no?

In the -users mailing list and on the #openvpn IRC channel, it is
obviously that many struggle to find/understand the available
documentation.  OpenVPN is very extensive and flexible, but with that
comes complexity, especially when describing it all at once (like the
man page does).  So this is an area where we should improve.

I believe one of the issues is that a lot of this comprehensive
information is compressed into to few separate files, which can make it
daunting and intimidating really reading the documentation.  Further,
the usage of specific terms might make it more difficult to understand
the document they are reading.  Parts of the documentation do take it
for granted that the reader knows a lot to start with, which often is
not the reality.

Second, maintaining the current man document is a hassle and can be
intimidating for people not having written man pages before.  In
addition, the size of the current man page makes it even more difficult
to make sure it is up-to-date.  Which is also a reason I would like to
split it up into more pieces and a different format than a raw man page
file.

I've taken some of the ideas for categorisation splits from the git man
pages.  It is quite easy to know where to look when you don't know where
to look, and where to look when you know what you are looking for.
That's kind of my main idea.  Further, take out the more advanced things
(like plug-ins) and put the gory details in a separate place, which must
be referenced in the server/client man pages.  This way users will not
be distracted too much with options which are not necessarily related to
what they need or are looking for.

The reason for splitting client and server options is also to avoid
confusion about which options can be used in which mode.  It grouped
correctly in the man page today, but when you scroll up and down in the
man page it is easy to loose overview of which "mode" you are reading about.

I did a quick page count in a 80x25 terminal window for the 2.1.1 man
page.  I lost count when I passed 150 pages.  This is exhaustive, but
easy to loose track of where you are - and might be quite intimidating
for new users.  Therefore I believe splitting it up into more focused
section will be easier for users to understand.

If the 

Re: [Openvpn-devel] OpenVPN documentation (man page) review

[Matthias Andree]

Am 11.01.2011 12:20, schrieb David Sommerseth:
> 
> Hi folks!
> 
> This is a little cry for help from us playing with the OpenVPN code.
> 
> We have a quite good man page today with a lot of information.  But
> maintaining it and to make sure it is up-to-date with all the features
> OpenVPN supports is often not high up on the priority list.  In
> addition, the current format (one single file, in pure man page format)
> is getting harder and harder to maintain as well.
> 
> So, we're hoping some people with some English skills is interested to
> help out improving this situation.  What we immediately would like to
> see is something along these lines:
> 
> * Move the man page to a better format than the pure man page format.
>   Are there some good tools/formats like ascii2man or DocBookXML which
>   could help easing the maintenance of our documentation?

Docbook XML for sure is a lot more verbose than asciidoc or roff.  I would tend
to avoid Docbook, the toolchains are lacking a bit -- still :-( although xmlto +
fop can yield reasonable PDF results.

However, we should make sure that there still is something that works with 
"man".

> * Split up the documentation into more focused sections, like
>   - main openvpn page (kind of like openvpn.8 today)
>   Gives an executive overview over OpenVPN, features and references
>   to the other documentation pages.  A bonus would be if it easily
>   can produce other formats in addition, like HTML, PS/PDF, ePub.
> 
>   - openvpn common options
>   Gives information about the common options openvpn has, which is
>   useful on both server and client instances.  F.ex. --keepalive,
>   --tls-auth, --cert, --key, --ca, etc

Should be part of the main page.

>   - openvpn server options
>   Describes only the options which are relevant for openvpn servers
> 
>   - openvpn client options
>   Describes only options useful for openvpn clients

Not sure if that's useful and actually reduces confusion this way.

Basically what you want is more (a) a concise HOWTO (more or less in place on
the website), and (b) an exhaustive reference, no?

-- 
Matthias Andree

[Openvpn-devel] OpenVPN documentation (man page) review

[David Sommerseth]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1


Hi folks!

This is a little cry for help from us playing with the OpenVPN code.

We have a quite good man page today with a lot of information.  But
maintaining it and to make sure it is up-to-date with all the features
OpenVPN supports is often not high up on the priority list.  In
addition, the current format (one single file, in pure man page format)
is getting harder and harder to maintain as well.

So, we're hoping some people with some English skills is interested to
help out improving this situation.  What we immediately would like to
see is something along these lines:

* Move the man page to a better format than the pure man page format.
  Are there some good tools/formats like ascii2man or DocBookXML which
  could help easing the maintenance of our documentation?

* Split up the documentation into more focused sections, like
  - main openvpn page (kind of like openvpn.8 today)
  Gives an executive overview over OpenVPN, features and references
  to the other documentation pages.  A bonus would be if it easily
  can produce other formats in addition, like HTML, PS/PDF, ePub.

  - openvpn common options
  Gives information about the common options openvpn has, which is
  useful on both server and client instances.  F.ex. --keepalive,
  --tls-auth, --cert, --key, --ca, etc

  - openvpn server options
  Describes only the options which are relevant for openvpn servers

  - openvpn client options
  Describes only options useful for openvpn clients

  - openvpn plug-ins
  Describes the different script plug-in hooks and environment
  variables available to scripts and plug-ins written in C

* Review the contents of all the documentation, check their accuracy
  - Make sure no options are not available in OpenVPN 2.2 or later
  - Make sure no options are missing in the documentation, which is
available in the source code  (options.c is a good reference)

* Review and check if all external references
  - Make sure all references to external sources, like web-sites, are
still available, valid and relevant in the document context
  - Find other external resources which are worth including.

(These points are not carved into stone, but is more like a guideline of
what needs to be considered)

This task should hopefully not require too much in-depth development
knowledge.  It should be user-focused, so that we avoid using terms and
details which is not so easy to understand.  What I'm saying is that
this documentation can be more useful and readable if users are involved
in this process.

If someone are willing to step up and take a lead, that would be great!
 Further, discussions and reviews of the document changes should
probably happen on the openvpn-users mailing list.  That way, it might
be easier for users to review the documentation and provide feedback.

We don't want this to just be a solo-project from someone in our OpenVPN
community, so we hope more people can help out and contribute, also if
you don't consider yourself a developer.


kind regards,

David Sommerseth

-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/

iEYEARECAAYFAk0sPQcACgkQDC186MBRfrrX2gCgnymM0Rx8yMronRPhfXatFts9
S24An13g48fdlKXnb9O1Zud8z/elaLRM
=qXo0
-END PGP SIGNATURE-