Re: [libreplanet-discuss] RFC: GNU Developer Network on libreplanet.org

[Rudolf]

The idea isn't to duplicate the documentation but to give a space for adding to the existing documentation in the form of tutorials, tips, snippets, notes on errors in the manual, etc.

Take a look at the MSDN: http://msdn.microsoft.com/en-gb/windows/

That page describes how to developer for Windows and how to develop desktop software. There are UX guidelines, a compatibility cookbook, and some parts function like the FSF directory.

The idea is to free that information and make it easier, faster to access and to update the resource.

The GNU coding standards that you point are themselves part of the problem. When were they last updated? Why aren't people using it as a guide anymore (unless they're forced when they're working on GNU project code)? It's because they aren't updated to meet the everyday needs of developers. I can't use the GNU coding standards at work as any sort of guide or model because it doesn't contain a section that applies to Python.

Developers are picking up their habits through reading certain tutorials and working with others. They look at the MDN as a guide, they look to the MSDN and distro-specific wikis as a guide. They read tutorials on blogs and learn to emulate that style.

When I look at github and all the projects there, including command-line projects or desktop-based projects, I am disappointed. There's no uniform way of writing a ChangeLog (all sorts of spellings, all sorts of formats), there's no roadmap for releases even for projects that are used by hundreds of developers! I don't want to dictate style to other developers; I want them to be engaged in a conversation and that's what a wiki will help with. There's no reason why we should let Microsoft or Mozilla dictate their own development style to the rest of the world. A wiki makes it easy to update and to add new pages to the GNU Coding Standards.

-Rudolf O.

On 8 July 2013 21:24, Bruno Félix Rezende Ribeiro <oitofelix@riseup.net> wrote:

David Gumberg <davidnoizgumberg@gmail.com> writes:

> My original intention when coming up with this idea, was something
> similar to Mozilla's Developer's Network. Mozilla does have pages with
> tutorials like: https://developer.mozilla.org/
> en-US/docs/Web/Guide/HTML/Introduction, but the biggest part of it is
> reference. Say you type in the search bar an html tag such as,
> "<a>". It will take you to this page that acts as like a much more
> friendly specification, telling you what the tag does, properties you
> can use with it, code samples, output examples, browser support,
> etc. I envision a GDN where you type in a function in the GNU C
> Library like say, printf, and it will tell you what the function does,
> what kind of values you can pass to it, code samples, and output
> examples, and how the function has changed in the various C
> standards. (ANSI, C99, C11, etc.) But, obviously we would have a
> friendlier homepage linking you to tutorials
> like https://developer.mozilla.org/en-US/.

I don't know if the analogy of a potential "GNU Developer Network" with
the existing "Mozilla's Developer's Network" is really fair.  Mozilla's
software is intrinsically related to the web.  So they use remote
documentation that is fetched by a browser, that is intended to be a
Mozilla derivative, and your work of development almost get done there.
In fact that documentation describes APIs, languages and standards that
will be processed by the same browser that reads the documentation.  It
is natural to expect that the MDN would be structured that way to
accomplish an integrated, web oriented, platform of documentation and
development.

The GNU project's software collection is far broader than that and often
has directly nothing to do with web technologies.  Consider the
following reasoning:

As a norm every GNU package should have a very good documentation in the
Texinfo format.  That is the case for the particular package you just
cited: The GNU C Library.  If you open its info manual in Emacs and type
"i printf" it will tell you what the function does, what kind of values
you can pass to it, will give you code samples and output examples, and
will tell how the function has changed in the various C standards.  If
it won't that info should be there before anywhere else, anyway.  What
is the point in duplicating the standard documentation when it already
exists or contributing it to a non-standard place when it doesn't
exists?  Why should developers rely on inherently remote documentation
for programs running and being developed locally, often with no remote
scope, that supposedly have already been shipped with the ultimate,
official, high quality documentation?  Why not to contribute to the
already existing standard documentation base?

Here I quote chapter 6 of The GNU Coding Standards, entitled
"Documenting Programs":

"A GNU program should ideally come with full free documentation,
adequate for both reference and tutorial purposes.  If the package can
be programmed or extended, the documentation should cover programming or
extending it, as well as just using it."

If you want to bring life to a web entity called "GNU Developer Network"
which purpose is to help developers of the GNU Operating System to
accomplish their development tasks, certainly to mimic "Mozilla's
Developer's Network" is not the way to do it.

I'm afraid of using precious human resources in the wrong place or in
the right place for the wrong task.

--
 ,= ,-_-. =.  Bruno Félix Rezende Ribeiro (oitofelix) [0x28D618AF]
((_/)o o(\_)) There is no system but GNU;
 `-'(. .)`-'  Linux-libre is just one of its kernels;
     \_/      All software should be free as in freedom;

Kosovo 22nd SAS industrial espionage AK-47 Clinton assassinate analyzer
eavesdropping underground CIDA IDEA Sears Tower Treasury Leuken-Baden
AFSPC