How to improve the docs?

[Ralf Eggert]

Hi,

I am starting a new thread since the discussion in the thread "Starting
the 3.0 branch" is heavily leading in the wrong direction.

In the discussion I identified two contrary positions: On the one hand
people complain about the available documentation. On the other hand
other people tell them to improve the docs themself.

Lets get ready to rumble? I hope not!

I think both groups are both right and wrong.

Yes, the docs can be improved in many places. Some components are still
missing or the docs for a component is incomplete (if it comes to
explaining all options or how to use a component within the big picture
of a ZF2 application).

But, if you are missing anything and are not able to write the docs
yourself, at least you should create an issue and write down what is
missing. Create an issue for each component and state if examples are
missing or hard to understand, if options or features are missing, and
whatever you noticed. Create issues for missing tutorials how to do
stuff or explanations how to use a component within a ZF2 application.
Flood the issue tracker, please!

https://github.com/zendframework/zf2-documentation/issues

Yes, the Zend Framework is an open source project and everybody is asked
to help out to improve the docs. But the bad vibes in the "Starting the
3.0 branch" complaining about the complainers (at least that is my
personal impression) won't solve the problem. Be thankful for anyone who
is getting up to write their concerns about the docs to the list.
Because for each person writing here, dozens won't write and just leave
to find a framework with a documentation that fit their needs better.
Don't underestimate the need for a proper documentation!

So, everybody who finds something missing in the docs or has suggestions
for tutorials to explain the big picture of a ZF2 application, please
create issues. And then lets do the DocHunt weekends regularly to
improve the ZF2 docs.

Then it will much easier to provide good ZF3 docs from the beginning. If
ZF3 should be a success the docs should be a major milestone to be
reached for.

Jm2c

Ralf

[Spabby]

Let me set my stall out from the offset. I am a docs maintainer and contributor, and I contribute little or nothing to the main framework. I agree that the documentation is not all it can be, and I am trying hard to use my own free time to improve that situation. I have a vested interest in the documentation, and I am not impartial, so my opinion should be skewed in favour of the docs because I've spent so much of my own time trying to get them into a usable state.

You all now know where I stand, but for the sake of the jury, let me just again state that I am NOT impartial.

My main frustration comes to the amount of contributors we have on the documentation. We have several pull requests per week from the same faces who are trying hard to make improvements. I completely understand the opinion that "the component authors should provide docs" but this is a pipe dream. We should be grateful for any and all time anyone spends on a framework that we all use for fun and profit. The lion's share of the framework was written by the same familiar faces, and they only have finite time to give to a project completely for free and for no thanks. In an ideal world we would not merge components into master until the documentation that accompanies those components are up to scratch, but this is not an ideal world (which is why Justin Beiber is still popular).

This is where YOU come in (cue the picture of the Uncle Sam pointing  and saying "We Want You!"). YOU can make the documentation better. If you've wrestled to understand a component, and been victorious despite the documentation, then you can submit a pull request on the documents to change or improve what was wrong. If you aren't confident enough to submit directly to the documentation, then create an issue in the issue tracker with a pointer to what was wrong, and a sample of the code you ended up using. If you would be happy to commit but don't know how, then email me and I'll walk you through it, or even better come badger me in IRC (Spabby).

Let me state at this point that I feel like the docs are in a decent state at the moment. We've come a long way baby! Thanks in no part to the guys who setup the readthedocs.org site, and pulled all the half assed original documentation into some semblance of order (you know who you are), the docs are at least ordered, readable and findable. This is no small feat. 

I know lots of people will be dismayed that my stance on this is "if you have a problem, contribute to help solve it", but in all honesty this is an open source project. And open source means that the work will almost always be done by someone who is getting no financial reward for the efforts they are putting in. Efforts that YOU will benefit from. If everyone thinks that the documentation is an SEP - http://en.wikipedia.org/wiki/Somebody_Else's_Problem - then the documentation will never get better.

Sorry for the wall of text, you can see I really care about this, I look forward to the barrage of pull requests on the documentation in the near future!

Gary (Spabby)

On Thu, Jun 20, 2013 at 9:23 AM, Ralf Eggert <[hidden email]> wrote:

Hi,

I am starting a new thread since the discussion in the thread "Starting
the 3.0 branch" is heavily leading in the wrong direction.

In the discussion I identified two contrary positions: On the one hand
people complain about the available documentation. On the other hand
other people tell them to improve the docs themself.

Lets get ready to rumble? I hope not!

I think both groups are both right and wrong.

Yes, the docs can be improved in many places. Some components are still
missing or the docs for a component is incomplete (if it comes to
explaining all options or how to use a component within the big picture
of a ZF2 application).

But, if you are missing anything and are not able to write the docs
yourself, at least you should create an issue and write down what is
missing. Create an issue for each component and state if examples are
missing or hard to understand, if options or features are missing, and
whatever you noticed. Create issues for missing tutorials how to do
stuff or explanations how to use a component within a ZF2 application.
Flood the issue tracker, please!

https://github.com/zendframework/zf2-documentation/issues

Yes, the Zend Framework is an open source project and everybody is asked
to help out to improve the docs. But the bad vibes in the "Starting the
3.0 branch" complaining about the complainers (at least that is my
personal impression) won't solve the problem. Be thankful for anyone who
is getting up to write their concerns about the docs to the list.
Because for each person writing here, dozens won't write and just leave
to find a framework with a documentation that fit their needs better.
Don't underestimate the need for a proper documentation!

So, everybody who finds something missing in the docs or has suggestions
for tutorials to explain the big picture of a ZF2 application, please
create issues. And then lets do the DocHunt weekends regularly to
improve the ZF2 docs.

Then it will much easier to provide good ZF3 docs from the beginning. If
ZF3 should be a success the docs should be a major milestone to be
reached for.

Jm2c

Ralf

[bl4de]

CONTENTS DELETED

The author has deleted this message.

[EvanDotPro]

This was posted in the other thread but I'd like to continue the discussion here...

On Mon, Jun 24, 2013 at 8:47 AM, Justin Martin <[hidden email]> wrote:

On 13-06-24 07:17 AM, Evan Coury wrote:

I agree, this would be nice in a "perfect world" where all contributors are also great, English-speaking technical writers, but it's simply not the case.

As I mentioned earlier in this thread, this is largely (though not exclusively) already the case -- most of the component docs we have today, were indeed, written by the contributor(s)/author(s) for those components. However, I also believe that this practice is actually partially to blame for many of the complaints we end up getting about the current docs. They're not written with a beginner or larger context in mind because they're written by someone that's far too close to the code to write quality end-user documentation for it. I think there's definitely ways to solve the doc problems, but requiring docs along with contributions is, in my opinion, not the optimal solution -- it will result in improving the quantity of documentation, but not increase the quality, which as I see it, needs to be our priority.

Again, this thread is getting off topic from my intent of planning ZF3.0 development. "Better docs" has definitely been noted and agreed upon, but let's move the discussion on the specifics over to the "How to improve the docs" thread.

--

Evan Coury

Jumping into the shark pit, here. Not sure if it'd be better directed towards the other thread, but I have a few remarks to make on the issue of documentation.

It should be noted that the old refrain of "make the developers do it!" is completely and totally ineffective. Firstly, developers *suck* at writing their own documentation. The reasons for this are plentiful.
Even extremely talented programmers can be poor communicators. They are not always equipped with the skills to write effective and useful documentation.
The person writing the code often has *too much* context on what the code does, to be able to discern where confusion may arise. A "fresh perspective" is very important in writing effective documentation.
When you force developers to write their own documentation, they do it as an afterthought, and usually resentfully, instead of considering it a contribution unto itself.
Some developers simply will refuse. It's easy to say "We'll just reject their contributions" in that case, but the reality is that those developers are often excellent contributors to the codebase, and rather crappy documentation writers.

In my experience, the *best* documentation is that written by dedicated documentation editors. This is how the PHP manual is written. It does make it *much harder* to find documentation contributors, but I would argue that having *more* documentation people isn't necessarily so important as having *good* documentation people.

Is anyone against this idea of putting together a dedicated docs team? I think this is actually a good idea if we can find the right people. I've spoken to Justin on IRC, and I think within reason, he'd be more than happy to help organize such an effort. I think it would be a really positive step in the right direction.

 

I have a number of suggestions regarding specific ways we can improve the documentation, and would be more than willing to assist in the process. However, I'll leave those suggestions to another thread where the passion of this thread isn't present. :)

Let's hear them, Justin. :) 

--

Evan Coury

[Spabby]

+1000

I'm all for a docs team.

G

On Mon, Jun 24, 2013 at 7:49 PM, Evan Coury <[hidden email]> wrote:

This was posted in the other thread but I'd like to continue the discussion here...

On Mon, Jun 24, 2013 at 8:47 AM, Justin Martin <[hidden email]> wrote:

On 13-06-24 07:17 AM, Evan Coury wrote:

I agree, this would be nice in a "perfect world" where all contributors are also great, English-speaking technical writers, but it's simply not the case.

As I mentioned earlier in this thread, this is largely (though not exclusively) already the case -- most of the component docs we have today, were indeed, written by the contributor(s)/author(s) for those components. However, I also believe that this practice is actually partially to blame for many of the complaints we end up getting about the current docs. They're not written with a beginner or larger context in mind because they're written by someone that's far too close to the code to write quality end-user documentation for it. I think there's definitely ways to solve the doc problems, but requiring docs along with contributions is, in my opinion, not the optimal solution -- it will result in improving the quantity of documentation, but not increase the quality, which as I see it, needs to be our priority.

Again, this thread is getting off topic from my intent of planning ZF3.0 development. "Better docs" has definitely been noted and agreed upon, but let's move the discussion on the specifics over to the "How to improve the docs" thread.

--

Evan Coury

Jumping into the shark pit, here. Not sure if it'd be better directed towards the other thread, but I have a few remarks to make on the issue of documentation.

It should be noted that the old refrain of "make the developers do it!" is completely and totally ineffective. Firstly, developers *suck* at writing their own documentation. The reasons for this are plentiful.
Even extremely talented programmers can be poor communicators. They are not always equipped with the skills to write effective and useful documentation.
The person writing the code often has *too much* context on what the code does, to be able to discern where confusion may arise. A "fresh perspective" is very important in writing effective documentation.
When you force developers to write their own documentation, they do it as an afterthought, and usually resentfully, instead of considering it a contribution unto itself.
Some developers simply will refuse. It's easy to say "We'll just reject their contributions" in that case, but the reality is that those developers are often excellent contributors to the codebase, and rather crappy documentation writers.

In my experience, the *best* documentation is that written by dedicated documentation editors. This is how the PHP manual is written. It does make it *much harder* to find documentation contributors, but I would argue that having *more* documentation people isn't necessarily so important as having *good* documentation people.

Is anyone against this idea of putting together a dedicated docs team? I think this is actually a good idea if we can find the right people. I've spoken to Justin on IRC, and I think within reason, he'd be more than happy to help organize such an effort. I think it would be a really positive step in the right direction.

 

I have a number of suggestions regarding specific ways we can improve the documentation, and would be more than willing to assist in the process. However, I'll leave those suggestions to another thread where the passion of this thread isn't present. :)

Let's hear them, Justin. :) 

--

Evan Coury

[Nathan Garlington]

On Mon, Jun 24, 2013 at 3:04 PM, Spabby [via Zend Framework Community] <[hidden email]> wrote:

I'm all for a docs team

In my company, when assembling a team to conquer issues with inventory, personnel, etc, the paradigm used is to select the team members from departments that have nothing to do/little experience with the issues at hand. For example, for a team to reduce inventory by 30%, we might select an accountant, an office manager, an HR person, and maybe the janitor along with the systems manager (who's responsibility is inventory). The idea is to explain the problem, get fresh eyes on it with fresh perspectives, and in my experience some amazing things happen. I've seen some very unique and effective solutions to various areas of concern come out of collaborations like these.

I am curious if a similar method can be used to tackle documentation improvements. Sometimes the best perspectives come from those with little to no experience.

--regards,
nathan

[Mike Willbanks]

Agreed.  Let's get that going :)

On Mon, Jun 24, 2013 at 11:52 AM, Gary Hockin <[hidden email]> wrote:

+1000

I'm all for a docs team.

G

On Mon, Jun 24, 2013 at 7:49 PM, Evan Coury <[hidden email]> wrote:

This was posted in the other thread but I'd like to continue the discussion here...

On Mon, Jun 24, 2013 at 8:47 AM, Justin Martin <[hidden email]> wrote:

On 13-06-24 07:17 AM, Evan Coury wrote:

I agree, this would be nice in a "perfect world" where all contributors are also great, English-speaking technical writers, but it's simply not the case.

As I mentioned earlier in this thread, this is largely (though not exclusively) already the case -- most of the component docs we have today, were indeed, written by the contributor(s)/author(s) for those components. However, I also believe that this practice is actually partially to blame for many of the complaints we end up getting about the current docs. They're not written with a beginner or larger context in mind because they're written by someone that's far too close to the code to write quality end-user documentation for it. I think there's definitely ways to solve the doc problems, but requiring docs along with contributions is, in my opinion, not the optimal solution -- it will result in improving the quantity of documentation, but not increase the quality, which as I see it, needs to be our priority.

Again, this thread is getting off topic from my intent of planning ZF3.0 development. "Better docs" has definitely been noted and agreed upon, but let's move the discussion on the specifics over to the "How to improve the docs" thread.

--

Evan Coury

Jumping into the shark pit, here. Not sure if it'd be better directed towards the other thread, but I have a few remarks to make on the issue of documentation.

It should be noted that the old refrain of "make the developers do it!" is completely and totally ineffective. Firstly, developers *suck* at writing their own documentation. The reasons for this are plentiful.
Even extremely talented programmers can be poor communicators. They are not always equipped with the skills to write effective and useful documentation.
The person writing the code often has *too much* context on what the code does, to be able to discern where confusion may arise. A "fresh perspective" is very important in writing effective documentation.
When you force developers to write their own documentation, they do it as an afterthought, and usually resentfully, instead of considering it a contribution unto itself.
Some developers simply will refuse. It's easy to say "We'll just reject their contributions" in that case, but the reality is that those developers are often excellent contributors to the codebase, and rather crappy documentation writers.

In my experience, the *best* documentation is that written by dedicated documentation editors. This is how the PHP manual is written. It does make it *much harder* to find documentation contributors, but I would argue that having *more* documentation people isn't necessarily so important as having *good* documentation people.

Is anyone against this idea of putting together a dedicated docs team? I think this is actually a good idea if we can find the right people. I've spoken to Justin on IRC, and I think within reason, he'd be more than happy to help organize such an effort. I think it would be a really positive step in the right direction.

 

I have a number of suggestions regarding specific ways we can improve the documentation, and would be more than willing to assist in the process. However, I'll leave those suggestions to another thread where the passion of this thread isn't present. :)

Let's hear them, Justin. :) 

--

Evan Coury

[localheinz]

> Agreed.  Let's get that going :)

Thumbs up!

As mentioned to Gary, I'd like to get involved, too.

[Ben Scholzen 'DASPRiD']

CONTENTS DELETED

The author has deleted this message.

[バートレット理路]

Hey Guys,

   I've heard both sides of the isle argue about how "good" coders are "awful" at documentation while the opponents claim coders should know their code & context better than anyone. However, zero documentation or lack of a simple comment on context would lead to either slow adoption or poor usage of given code. Worst case is the "awesome" code would be ignored or butchered. Then there's the support of such code. A barrage of complaints from new-comers that don't understand the code. I've been there and done that. In the past, if I didn't understand the source code, I ignored it and wrote my own. This is far from optimal. Even if the "good" coders would write the basics of their logic, that would assist the doc-writing later on.

   In other projects where the entire framework is sponsored and has dedicated resources, the documentation is written by not only the dev-team but also a support team that creates examples and use-cases that are easy for newbies to consume. Case in point, ExtJS by SenchaLabs. They include the documentation directly in their frameworks source code and use JSDuck to parse it into a very beautiful and easy-to-read API doc (web page). While this framework is not free, it has (IMHO) the best JavaScript framework on the market -- far better than JQuery etc.

   My point here is for ZendFramework to gain a larger audience with greater acceptance, we should model what Sencha has done well at... Create beautiful and easily consumed documents much in the same manner that Sencha presents it. PHP.net's documentation is not the worst, but not the best either. I have found Sencha (thus far) to provide the best. But they don't separate their docs from the code. Rather, it's all inclusive. Rather than run multiple projects (code-base, docs, parsers, composer-based installers, etc.), perhaps the community should consider using something similar to JSDuck to parse the library/components and automate the document (API webpage) creation process?

  Just to clarify one point, while I would prefer that the original coder create the documentation... I don't require it for as long as the context of the code is consumable. At some point, someone needs to write the doc and express the context of the component. As far as the world is concerned: no doc, no acceptance. I tend to agree.

Richie Bartlett Jr (バートレット理路)

On Tue, Jun 25, 2013 at 8:16 AM, Ben Scholzen 'DASPRiD' <[hidden email]> wrote:

On <a href="tel:24.06.2013%2022" value="[phone]">24.06.2013 22:20, Andreas Möller wrote:
>> Agreed.  Let's get that going :)
>
> Thumbs up!
>
> As mentioned to Gary, I'd like to get involved, too.

Great idea, let's do this.

--
Ben Scholzen 'DASPRiD'
Community Review Team Member | [hidden email]
Zend Framework               | http://www.dasprids.de

[weierophinney]

On Mon, Jun 24, 2013 at 8:47 PM, バートレット理路 <[hidden email]> wrote:
>    My point here is for ZendFramework to gain a larger audience with greater
> acceptance, we should model what Sencha has done well at... Create beautiful
> and easily consumed documents much in the same manner that Sencha presents
> it.

The question is: who will write it? That's the deeper issue that is
being debated. Nobody is arguing that we should do nothing at this
point; the question is who has the appropriate skill and time to do
it.

Consider this: the amount of time spent in these threads arguing we
should have better docs could have been spent improving and/or
creating new documentation...


--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

[aromatix]

what do you think to provide the possibility to easily translate the
documentation because ZF2 is used by people from many countries and
beginning with ZF2 means also spending some time to learn new coding style
and practices, new patterns, new designs for the first time (what is not
often easy when not read in once language)

so i'm willing to get involved in translating the documentation in french

i'd like to add that i think the difficult thing is not to understand ZF2.
the difficult thing is to implement common or complex use cases when using
it.
So that could be very useful to provide a *cookbook* in addition to the
documentation.
many people read the doc because the want to do something

the documentation as it is now doesn't need so much refactoring if a
cookbook is provided with it

[xoops]

Matthew said it.

Get ability and enthusiasm and start to write docs you will find tools/format is not that critically issue compared to documentation itself.

On Tue, Jun 25, 2013 at 9:08 PM, Matthew Weier O'Phinney <[hidden email]> wrote:

On Mon, Jun 24, 2013 at 8:47 PM, バートレット理路 <[hidden email]> wrote:
>    My point here is for ZendFramework to gain a larger audience with greater
> acceptance, we should model what Sencha has done well at... Create beautiful
> and easily consumed documents much in the same manner that Sencha presents
> it.

The question is: who will write it? That's the deeper issue that is
being debated. Nobody is arguing that we should do nothing at this
point; the question is who has the appropriate skill and time to do
it.

Consider this: the amount of time spent in these threads arguing we
should have better docs could have been spent improving and/or
creating new documentation...


--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

--

Taiwen Jiang (aka D.J.)

Pi Engine based Zend Framework 2: http://pi-engine.org

Role oriented web and mobile application engine

[localheinz]

> The question is: who will write it? That's the deeper issue that is
> being debated. Nobody is arguing that we should do nothing at this
> point; the question is who has the appropriate skill and time to do
> it.
>
> Consider this: the amount of time spent in these threads arguing we
> should have better docs could have been spent improving and/or
> creating new documentation…

How about this:

I often feel that it is easier to improve existing code rather than writing awesome code from scratch.

Therefore, rather than not writing code at all because it's too difficult to write awesome code, I find it's better to start with something, even if it's not perfect (write now, refactor later with the excellent tools you have at hand).

Can't this be applied to documentation as well?


Best regards,

Andreas

[localheinz]

Hello all,

   In other projects where the entire framework is sponsored and has dedicated resources, the documentation is written by not only the dev-team but also a support team that creates examples and use-cases that are easy for newbies to consume. Case in point, ExtJS by SenchaLabs. They include the documentation directly in their frameworks source code and use JSDuck to parse it into a very beautiful and easy-to-read API doc (web page). While this framework is not free, it has (IMHO) the best JavaScript framework on the market -- far better than JQuery etc.

I've thought about this on the way to work, too and wanted to throw in this:

* http://www.yiiframework.com/doc/api/

I find the documentation is very good and it's easy to find documentation for components with the search they provide.

Maybe it's really the best idea to improve the documentation *within* the code. Then the documentation would be as close to the code as possible and it would be a lot easier to review PRs both in terms of documentation and code provided.

What do you think?

In the light of a documentation build like that, there would only be a demand for documentation in tutorial style after all, I guess.

Best regards,

Andreas

[Frank Brückner]

Short notice:
You can find a nice looking api-doc of ZF on http://apigen.juzna.cz/ 
(ApiGen Generator)

http://apigen.juzna.cz/doc/zendframework/zf2/


Kind regards,
Frank

Am 26.06.2013, 09:54 Uhr, schrieb Andreas Möller <[hidden email]>:

> Hello all,
>
>
>>    In other projects where the entire framework is sponsored and has  
>> dedicated resources, the documentation is written by not only the  
>> dev-team but also a support team that creates examples and use-cases  
>> that are easy for newbies to consume. Case in point, ExtJS by  
>> SenchaLabs. They include the documentation directly in their frameworks  
>> source code and use JSDuck to parse it into a very beautiful and  
>> easy-to-read API doc (web page). While this framework is not free, it  
>> has (IMHO) the best JavaScript framework on the market -- far better  
>> than JQuery etc.
>
> I've thought about this on the way to work, too and wanted to throw in  
> this:
>
> * http://www.yiiframework.com/doc/api/
>
> I find the documentation is very good and it's easy to find  
> documentation for components with the search they provide.
>
> Maybe it's really the best idea to improve the documentation *within*  
> the code. Then the documentation would be as close to the code as  
> possible and it would be a lot easier to review PRs both in terms of  
> documentation and code provided.
>
> What do you think?
>
> In the light of a documentation build like that, there would only be a  
> demand for documentation in tutorial style after all, I guess.
>
>
> Best regards,
>
> Andreas

[Spabby]

Alternatively use the official api documentation here:

http://framework.zend.com/apidoc/2.2/

On Wed, Jun 26, 2013 at 9:09 AM, Frank Brückner <[hidden email]> wrote:

Short notice:
You can find a nice looking api-doc of ZF on http://apigen.juzna.cz/ (ApiGen Generator)

http://apigen.juzna.cz/doc/zendframework/zf2/


Kind regards,
Frank

Am 26.06.2013, 09:54 Uhr, schrieb Andreas Möller <[hidden email]>:

Hello all,

   In other projects where the entire framework is sponsored and has dedicated resources, the documentation is written by not only the dev-team but also a support team that creates examples and use-cases that are easy for newbies to consume. Case in point, ExtJS by SenchaLabs. They include the documentation directly in their frameworks source code and use JSDuck to parse it into a very beautiful and easy-to-read API doc (web page). While this framework is not free, it has (IMHO) the best JavaScript framework on the market -- far better than JQuery etc.

I've thought about this on the way to work, too and wanted to throw in this:

* http://www.yiiframework.com/doc/api/

I find the documentation is very good and it's easy to find documentation for components with the search they provide.

Maybe it's really the best idea to improve the documentation *within* the code. Then the documentation would be as close to the code as possible and it would be a lot easier to review PRs both in terms of documentation and code provided.

What do you think?

In the light of a documentation build like that, there would only be a demand for documentation in tutorial style after all, I guess.


Best regards,

Andreas

[Frank Brückner]

Am 26.06.2013, 10:21 Uhr, schrieb Gary Hockin <[hidden email]>:

> Alternatively use the official api documentation here:
>
> http://framework.zend.com/apidoc/2.2/


My opinion: The official api doc is horrible.

[Pavel Kačer]

Andreas Möller <[hidden email]> writes:
> Maybe it's really the best idea to improve the documentation *within*
> the code. Then the documentation would be as close to the code as
> possible and it would be a lot easier to review PRs both in terms of
> documentation and code provided.

This is what I wrote about a month ago to this mailing list and it got
quite unnoticed. This is the best way to document separated components.

--
Pavel Kačer
QA Automation Engineer
SUSE
[hidden email]
([phone]

Be polite to everyone. You never know when your life or life of
someone close to you might depend on this person.

[settermjd]

Seems like a good idea. 

Kind regards,

Matthew Setter / Malt Blue
Professional web application development from people you trust
http://www.maltblue.com | [hidden email]

http://twitter.com/maltblue | http://linkedin.com/in/MatthewSetter

On Wed, Jun 26, 2013 at 11:17 AM, Pavel Kačer <[hidden email]> wrote:

Andreas Möller <[hidden email]> writes:
> Maybe it's really the best idea to improve the documentation *within*
> the code. Then the documentation would be as close to the code as
> possible and it would be a lot easier to review PRs both in terms of
> documentation and code provided.

This is what I wrote about a month ago to this mailing list and it got
quite unnoticed. This is the best way to document separated components.

--
Pavel Kačer
QA Automation Engineer
SUSE
[hidden email]
<a href="tel:%28%2B420%29%20284%20084%20221" value="[phone]">([phone]

Be polite to everyone. You never know when your life or life of
someone close to you might depend on this person.