[nanomsg] Re: Separating the library from the docs
- From: Martin Sustrik <sustrik@xxxxxxxxxx>
- To: <nanomsg@xxxxxxxxxxxxx>
- Date: Tue, 13 Aug 2013 15:02:01 +0200
On 2013-08-13 11:41, Paul Colomiets wrote:
The only reason to put documentation in the same git repository, is to
update docs simultaneously with the code, and to accept patches for
code and docs in one go. But this is fairly good reason to do so.
Frankly speaking, the more I am thinking about the whole documentation
stuff, the more confused I am. There's too much intersecting domains
there: global-scope (online docs), release-scope (the source package),
repo-scope (what you get when you do git clone) and local-scope
(generated by make). Then there are things that maintainers should do,
things that other developers should do, things that users of source
package should do and things that users of distro packages should do.
Then there are many instances of the docs to keep in sync: distros,
source packages, website, git repos, the library itself etc.
All in all, it's a mess.
However, separating the library from the docs at least clearly
separates the mess from the rest of the system. You simply commit the
generated man pages into the library repo. That's a pretty simple and
easy-to-follow process. It also solves the problem of delivering the man
pages to everyone, including people building from git and without the
appropriate tools installed.
Generating the docs may still be messy, but at least it's in a separate
repo and thus it confuses much smaller community :)
Anyway, I don't feel very confident about the whole stuff, so feel free
to disagree.
Martin
Btw, here's the visulisation of content distribution channels:
nanomsg-doc ---+----> nanomsg github repo ---> source packages --->
distro packages
| | |
|
| +-> /usr/share/man +-> /usr/share/man
+-> /usr/share/man
|
+----> gh-pages github repo ---> website
|
+----> IETF RFC editor
|
+----> ...
Other related posts:
