Proposal: Project Pink Book

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
45 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ralph Johnson
One of the big advantages of SUnit and its ilk are that tests are "just code".  They can be versioned, inspected, refactored, released, announced, etc just like code, because they are code.

So, I think it is great that you are trying to put documentation on the same level.

It looks to me like you are thinking of several tools here.  One converts documentation into HTML.   This might be a web site that just displays what is in the image, or it might be a tool that goes through the image and creates HTML, writing it out to the disk for display later.

Another is a way of including more tutorial-style documentation in the image, and you are thinking about HelpSystem, right?

I assume you would like the material in HelpSystem to be on the web, too.

-Ralph




Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Hannes Hirzel
On 4/21/10, Ralph Johnson <[hidden email]> wrote:
> One of the big advantages of SUnit and its ilk are that tests are "just
> code".  They can be versioned, inspected, refactored, released, announced,
> etc just like code, because they are code.
>
> So, I think it is great that you are trying to put documentation on the same
> level.

Yes, that is actually what Andreas and Torsten are doing right now.

> It looks to me like you are thinking of several tools here.

Yes.

> One converts
> documentation into HTML.   This might be a web site that just displays what
> is in the image, or it might be a tool that goes through the image and
> creates HTML, writing it out to the disk for display later.

Yes.

> Another is a way of including more tutorial-style documentation in the
> image, and you are thinking about HelpSystem, right?

Yes.


> I assume you would like the material in HelpSystem to be on the web, too.

Yes.
> -Ralph


And we need an agreement on the kind of text format the 'original' of
the documentation is stored in.
The selection of a lightweight markup language
http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-April/149201.html

It is not so important which one as long as we use a common subset and
have converters between the various approaches. Somebody suggested
'reStructuredText'
http://docutils.sourceforge.net/rst.html

What is currently in use is plain text (Torsten B. / HelpSystem) and
the Smalltalk text format (Andreas R. / Help menu)

--Hannes

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Josh Gargus
In reply to this post by Bert Freudenberg

On Apr 21, 2010, at 3:35 AM, Bert Freudenberg wrote:

> On 21.04.2010, at 12:27, Michael Haupt wrote:
>
> We don't actually disagree after all :)  It's just that the links people were excited about (Python, PHP, Ruby) were all of the API doc kind. And *that* needs to be generated from the source code IMHO.


Actually, the Python link that Andreas sent was to the Python Tutorial, which isn't of the "API doc kind".  It's quite impressive.

Cheers,
Josh


>
> - Bert -
>
>
>


Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

K. K. Subramaniam
In reply to this post by Andreas.Raab
On Wednesday 21 April 2010 11:13:55 am Andreas Raab wrote:
> * The most helpful documentation I've used in recent years is this:
>         http://www.google.com/search?q=python+tuple
>         http://www.google.com/search?q=php+explode
While we are on the topic of helpful documents, I want to point out Qt's
integrated documents at:
   http://qt.nokia.com/developer

It makes good use of hyperlinks and RSS to tie together API indices,
reference, tutorials, blogs, video clips. e.g.

  http://labs.trolltech.com/blogs/2010/04/09/the-future-continued

Subbu

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ian Trudel-2
In reply to this post by Casey Ransberger-2
Hello Casey,

A short plan is the step in the right direction. I believe our
community needs more sense of direction. I'd like to bring few things
that seems to be missing in your proposal, for your consideration (and
everyone else).

There is no inclusion of additional tools in order to make sure we
have quality documentation. For example, why not having hunspell [1]
integrated? A good spell checker will make a huge difference. I would
also consider versioning documentation important since our wiki
suffers from the lack of it (shall we learn from our past mistakes?).

[1] http://hunspell.sourceforge.net/

I would much more consider contribute on documentation provided
editing and formatting tools are available, ability to include
screenshots, and other goodies. I don't care about the internal
format. I am a big fan of LaTeX and I don't use it anymore because
editing softwares nowadays do it much faster and it's way easier.
Faster and easier mean more contributions.

Your plan is overenthusiastic in my opinion. I don't think our
community can undertake everything listed. It would be much better to
look at what is the most needed in term of documentation and have
people to focus on it. It will reduce the risks of failure. We can
build around this documentation and slowly move on other parts. We
need something usable for the largest segment of the community.

Squeak Documentation Team is all right for a name. Let's stick to
simple. Simple usually works better. :P

Best regards,
Ian.
--
http://mecenia.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Casey Ransberger-2
One thing I didn't do, that I probably should have done, is to explicitly list what I think our priorities should be regarding documentation. As much as it pains me that we don't have a spell checker, for example, I'd put that waaay behind a cleanup effort for class comments; I'd put *all* tool work behind that.

I've thought a lot about how best to limit scope such that a documentation project can deliver quickly. For a first shot, I'd like to limit scope to what's in the image after one does 'Smalltalk unloadAllKnownPackages'. Of course we should have great documentation for everything that comes in a standard Squeak image, but knowing that our resources are limited, in a triage I would call out everything in a core image as priority-1, with the contents of a standard image as priority-2.

So here's my top three priorities (you may of course disagree:)

1. Get a process running around using HelpSystem.
2. A useful, current comment for every class.
3. Consider first method comments which show up in tools that can extract them.

On Fri, Apr 30, 2010 at 2:24 AM, Ian Trudel <[hidden email]> wrote:
Hello Casey,

A short plan is the step in the right direction. I believe our
community needs more sense of direction. I'd like to bring few things
that seems to be missing in your proposal, for your consideration (and
everyone else).

There is no inclusion of additional tools in order to make sure we
have quality documentation. For example, why not having hunspell [1]
integrated? A good spell checker will make a huge difference. I would
also consider versioning documentation important since our wiki
suffers from the lack of it (shall we learn from our past mistakes?).

[1] http://hunspell.sourceforge.net/

I would much more consider contribute on documentation provided
editing and formatting tools are available, ability to include
screenshots, and other goodies. I don't care about the internal
format. I am a big fan of LaTeX and I don't use it anymore because
editing softwares nowadays do it much faster and it's way easier.
Faster and easier mean more contributions.

Your plan is overenthusiastic in my opinion. I don't think our
community can undertake everything listed. It would be much better to
look at what is the most needed in term of documentation and have
people to focus on it. It will reduce the risks of failure. We can
build around this documentation and slowly move on other parts. We
need something usable for the largest segment of the community.

Squeak Documentation Team is all right for a name. Let's stick to
simple. Simple usually works better. :P

Best regards,
Ian.
--
http://mecenia.blogspot.com/




--
Casey Ransberger


Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ian Trudel-2
2010/4/30 Casey Ransberger <[hidden email]>:
> One thing I didn't do, that I probably should have done, is to explicitly
> list what I think our priorities should be regarding documentation. As much
> as it pains me that we don't have a spell checker, for example, I'd put that
> waaay behind a cleanup effort for class comments; I'd put *all* tool work
> behind that.

I completely disagree on this one. I would concede that editing and
formatting tools may not be as high priority as a spell checker.
However, a spell checker should be mandatory. Many in our community
are non-native English speakers.

Let's imagine there is a documentation frenzy without a spell checker.
People contribute like crazy and we are on a roll. Great you say.
Great it is. Then we realize that we have more documentation but with
poor quality, it's hardly readable. We will be forced to rework all
texts. It sounds like documenting twice the same system! :O

> So here's my top three priorities (you may of course disagree:)
> 1. Get a process running around using HelpSystem.

I believe in the HelpSystem. It needs some tweaking but it's a good
system to begin with. A mechanism for content contribution and
distribution, as you called it, should be put in place quickly. Trunk
style. Perhaps even integrated to the trunk. It has to be available
everywhere to ensure a good stream of contributions.

> 2. A useful, current comment for every class.

This could be a good start. One of the thing that should be higher in
priority than #3 is usage examples. It is sometimes time consuming to
figure out how to properly use some classes.

> 3. Consider first method comments which show up in tools that can extract
> them.

Another suggestion: we should have something to tell us how much
documentation coverage we have. This set an objective to our
community: having 100% coverage.

Ian.
--
http://mecenia.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Casey Ransberger-2
Ian, thanks. Comments inline.

On Fri, Apr 30, 2010 at 1:36 PM, Ian Trudel <[hidden email]> wrote:
2010/4/30 Casey Ransberger <[hidden email]>:
> One thing I didn't do, that I probably should have done, is to explicitly
> list what I think our priorities should be regarding documentation. As much
> as it pains me that we don't have a spell checker, for example, I'd put that
> waaay behind a cleanup effort for class comments; I'd put *all* tool work
> behind that.

I completely disagree on this one. I would concede that editing and
formatting tools may not be as high priority as a spell checker.
However, a spell checker should be mandatory. Many in our community
are non-native English speakers.

Let's imagine there is a documentation frenzy without a spell checker.
People contribute like crazy and we are on a roll. Great you say.
Great it is. Then we realize that we have more documentation but with
poor quality, it's hardly readable. We will be forced to rework all
texts. It sounds like documenting twice the same system! :O


Somehow I doubt we'll have a documentation-frenzy. That would be a momentous day in software history, and a great problem to have.

Okay, I would love to have a spell checker in Squeak. It would need to be:

 - Easy to install. I'm thinking, MC package. Requiring a VM primitive would set the barrier for contribution too high IMHO. 
 - It should be easily unloadable (many of us probably have no use for a spell checker in our images.)

I don't know of a spell checker implementation for Squeak. Is there one out there? If not, can you implement one and then get back to me right away? :P

> So here's my top three priorities (you may of course disagree:)
> 1. Get a process running around using HelpSystem.

I believe in the HelpSystem. It needs some tweaking but it's a good
system to begin with. A mechanism for content contribution and
distribution, as you called it, should be put in place quickly. Trunk
style. Perhaps even integrated to the trunk. It has to be available
everywhere to ensure a good stream of contributions.


Agreed. I just sent another message about this. 

> 2. A useful, current comment for every class.

This could be a good start. One of the thing that should be higher in
priority than #3 is usage examples. It is sometimes time consuming to
figure out how to properly use some classes.


I think examples raise the quality of class comments. Absolutely.
 
> 3. Consider first method comments which show up in tools that can extract
> them.

Another suggestion: we should have something to tell us how much
documentation coverage we have. This set an objective to our
community: having 100% coverage.


This is actually something that I thought about doing. I'd call it a strong nice-to-have. This one seems like it wouldn't be that hard to pull off, either. 

Coverage is kind of a funny metric though. 100% coverage is great to have, but doesn't tell you anything about the quality of your coverage.
 

Thanks for your feedback!

--
Casey Ransberger


Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ian Trudel-2
2010/4/30 Casey Ransberger <[hidden email]>:
> Ian, thanks. Comments inline.

My pleasure, I like plans. :)

> Somehow I doubt we'll have a documentation-frenzy. That would be a momentous
> day in software history, and a great problem to have.

That's not what your plan said. As I wrote, it's a bit
overenthusiastic for a period of one year. My point was simply that a
spellchecker is important and it will make a difference over time. We
both agree on this. Fine. :)

> Okay, I would love to have a spell checker in Squeak. It would need to be:
>  - Easy to install. I'm thinking, MC package. Requiring a VM primitive would
> set the barrier for contribution too high IMHO.
>  - It should be easily unloadable (many of us probably have no use for a
> spell checker in our images.)

The easiest approach would probably be to use an existing system, such
as hunspell. It has been used with many systems (OO.o, Firefox, Opera)
and many programming languages. There are probably all the compiled
libraries needed to interface with. It comes with many dictionaries in
various languages.

> I don't know of a spell checker implementation for Squeak. Is there one out
> there? If not, can you implement one and then get back to me right away? :P

Neither do I know.


> Agreed. I just sent another message about this.

Yes, great. :)

>> > 3. Consider first method comments which show up in tools that can
>> > extract
>> > them.
>>
>> Another suggestion: we should have something to tell us how much
>> documentation coverage we have. This set an objective to our
>> community: having 100% coverage.
>
> This is actually something that I thought about doing. I'd call it a strong
> nice-to-have. This one seems like it wouldn't be that hard to pull off,
> either.
> Coverage is kind of a funny metric though. 100% coverage is great to have,
> but doesn't tell you anything about the quality of your coverage.

You're correct about quality. My idea is to set an objective first and
foremost. We could define basic requirements for comments. I see
online help often have something to rate the help page they have been
reading (“How useful this entry was?” 1 – Useless, 5 – Excellent). We
could consider something along this line.

Ian.
--
http://mecenia.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Michael Haupt-3
Hi,

sorry for being late, but week-ends are for relaxing sometimes. :-)


Regarding spell checking and the upcoming documentation frenzy, I
don't think poor spelling will be that much of a problem for two
reasons. First, I don't believe that so many people speak and write
such a poor English that it deserves utmost attention. Second, if the
documentation process allows for trunk-like quick pushes to the
repository, glitches and unclear formulations can be quickly mended by
anyone interested in doing so.

Given that the number of people who are actually willing to commit to
the documentation thingy can be expected to be low (yup, call me a
pessimist), we can nevertheless expect high interest in good
documentation in those who contribute. So - let's not worry about the
spelling issues right now.

In a nutshell, I think that getting a possibly external spell checker
to work in Squeak may be an interesting project, but it's not really
of immediate help with regard to the documentation plans. (If the
above observations are correct.)


Regarding quality of documentation (more precisely: of class
comments), I would expect the best quality from those who know most
about the classes in question. But will those people write the most?
Not necessarily. So how about this: someone writes the documentation
for a class and commits it, and the next thing is to ask those three
people who had the most commits to that very class for their opinion
on the documentation.


Best,

Michael

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ian Trudel-2
Hi Michael,

It is an unexpected comment from a German. My experience in the German
market made it clear Germans demand high-quality writings — in German
that is. The companies I have worked for were paying top dollars for
near-perfect German writings, from advertisement to documentation.

The English market is more lax but I have seen its limits. Poor
quality documentation turned against one software vendor I worked for
few years ago. It did undermine sales and the broken English
documentation made the top 3 most complains.

Squeak is a product that happens to be free-of-charge. I wrote that once. :)

My point is that we have more to gain to do it right from the ground
up. The efforts required to interface with a spellchecker library is
much less now than rewriting documentation later. I like your idea
about asking code contributors for their opinion but it's difficult to
get feedback from others in our community at the moment. Plus, barely
few want to write documentation along their code. Nobody rewrite
documentation. :O

What we will be writing will be stuck for years in our documentation
system with little chances for update assuming that documentation gets
some attention from a small part of our community (and no more). I am
all about increasing our chances of success. :)

Question. Does HelpSystem support syntax highlight? It would be great
to insert piece of codes properly formatted. In fact, if you guys look
at my recent article on my blog, this is the kind of visual elements
we might need to provide an appealing documentation.

Ian.
--
http://mecenia.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Michael Haupt-3
Hi Ian,

On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> wrote:
> It is an unexpected comment from a German. My experience in the German
> market made it clear Germans demand high-quality writings — in German
> that is. The companies I have worked for were paying top dollars for
> near-perfect German writings, from advertisement to documentation.

see, that's what stereotypes are for: being reconsidered. :-)

I think it is much more important to get some documentation available.
Polishing is always possible. There is no business contract involved
here, and no $$$ lurking. At least not for me.

> My point is that we have more to gain to do it right from the ground
> up. The efforts required to interface with a spellchecker library is
> much less now than rewriting documentation later. ...

Correct spelling alone doesn't make good quality, does it?

Best,

Michael

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ian Trudel-2
2010/5/2 Michael Haupt <[hidden email]>:
> Hi Ian,

Hi Michael,

> On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> wrote:
>> It is an unexpected comment from a German. My experience in the German
>> market made it clear Germans demand high-quality writings — in German
>> that is. The companies I have worked for were paying top dollars for
>> near-perfect German writings, from advertisement to documentation.
>
> see, that's what stereotypes are for: being reconsidered. :-)

I see. Companies however collect demographic data and it makes sense
to consider such feedback. The important is to make a decision in a
knowledgeable manner. Spell checker could be entirely excluded but at
least it would be a decision taken in knowledge of its advantages and
disadvantages. :)

> I think it is much more important to get some documentation available.
> Polishing is always possible. There is no business contract involved
> here, and no $$$ lurking. At least not for me.

Some documentation is already available: http://wiki.squeak.org/squeak

Polishing did not happen.

o_O

>> My point is that we have more to gain to do it right from the ground
>> up. The efforts required to interface with a spellchecker library is
>> much less now than rewriting documentation later. ...
>
> Correct spelling alone doesn't make good quality, does it?

You're right. Every detail matters to make good quality. *grin*

> Best,
>
> Michael

Quality is something I take at heart and I usually refrain from
releasing anything that does not match a minimum quality standard as
far as open source contribution goes and I release commercial work
only when it matches my highest quality standard. A spell checker is
among the tools I use to write documentation, articles, etc. I will
survive if it's not in our HelpSystem but I know it will become an
additional hurdle to me. I will probably end up writing in OpenOffice
and transfer back in Squeak. Painful.

Anyway, when are we getting HelpSystem integrated to the trunk again?
We could be typing in there instead. :)))

Ian.
--
http://mecenia.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Michael Haupt-3
Hi Ian,

On Sun, May 2, 2010 at 3:21 PM, Ian Trudel <[hidden email]> wrote:
> Some documentation is already available: http://wiki.squeak.org/squeak
>
> Polishing did not happen.
>
> o_O

I knew this would be next as soon as I had hit the "send" button. :-)
Of course I mean in-image documentation. I know I know, there are also
many unpolished places in there, but hey, this whole documentation
initiative has just started, right?

> You're right. Every detail matters to make good quality. *grin*

Ah well. Let there be a spell checker or not, I don't care. All I
wanted to say is that we don't need one to get started.

> Anyway, when are we getting HelpSystem integrated to the trunk again?

What is actually keeping us from doing it?

Best,

Michael

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Bert Freudenberg
In reply to this post by Ian Trudel-2
On 02.05.2010, at 15:21, Ian Trudel wrote:
>
> A spell checker is
> among the tools I use to write documentation, articles, etc. I will
> survive if it's not in our HelpSystem but I know it will become an
> additional hurdle to me.

I guess nobody would mind having a spell checker, just don't rely on anyone else to make this her highest priority :)

> Anyway, when are we getting HelpSystem integrated to the trunk again?

Err, you *do* know where the inbox is, right? ;)

- Bert -



Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Ian Trudel-2
My apologies Michael. This new initiative is indeed a good thing. :)

2010/5/2 Bert Freudenberg <[hidden email]>:
> I guess nobody would mind having a spell checker, just don't rely on anyone else to make this her highest priority :)
>
>> Anyway, when are we getting HelpSystem integrated to the trunk again?
>
> Err, you *do* know where the inbox is, right? ;)
>
> - Bert -

Bert,

I have installed the HelpSystem with the instructions from Torsten but
I believe it uses SqueakSource. I will check in the inbox. The reason
I would prefer contributing with the HelpSystem in the trunk is
because it ensures my contribution is not in vain.

Am I allowed to put things into perspective once more? I have been
writing often lately. I don't want to come off as annoying and
everything I write is in all due respect.

What you are saying is that our community has a self-serving mentality
(e.g. nobody will make such improvement a priority because it's not
*their* priority) and you are suggesting me to do an unselfish act by
writing documentation with unsuitable tools. A contradiction in logic.
Or, let's say for the sake of the argument, I could be also
self-serving and write articles about Squeak on my blog where I can do
proper formatting, spell checking, include images, etc. and get
instant popularity! **Blogger is the winner!**

That's basically how self-serving mentality works. The shortest and
easiest path wins. Contributing on my blog would be good for Squeak
(as a side effect) but doing so in-image documentation is better (best
and direct). I am all right with contributing unselfishly because I
believe a community cannot progress on the basis of selfishness. It's
food-for-thoughts, right?

Ian.
--
http://mecenia.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Michael Haupt-3
In reply to this post by Bert Freudenberg
Hi Bert,

On Sun, May 2, 2010 at 3:28 PM, Bert Freudenberg <[hidden email]> wrote:
> Err, you *do* know where the inbox is, right? ;)

so ... I've been a bit busy and am just uploading four packages to the Inbox:

* Morphic-mha.433
  insert Help Browser in Help menu (if it is present in the image)
* HelpSystem-Core
  the core, without popping up the Help Browser after installation,
but with updating the docking bar menus
* HelpSystem-Tests
  just for good style
* Squeak-Project-Help
  because it belongs

I don't know if I have broken any invariants. I know that Torsten
primarily uses SqueakSource, so integration is a topic. Still, that
step has been done.

(I'll send this message to the list once more to avoid it gets lost in
the depths of this thread.)

Best,

Michael

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Bert Freudenberg
In reply to this post by Ian Trudel-2
On 02.05.2010, at 15:55, Ian Trudel wrote:

>
> My apologies Michael. This new initiative is indeed a good thing. :)
>
> 2010/5/2 Bert Freudenberg <[hidden email]>:
>> I guess nobody would mind having a spell checker, just don't rely on anyone else to make this her highest priority :)
>>
>>> Anyway, when are we getting HelpSystem integrated to the trunk again?
>>
>> Err, you *do* know where the inbox is, right? ;)
>>
>> - Bert -
>
> Bert,
>
> I have installed the HelpSystem with the instructions from Torsten but
> I believe it uses SqueakSource. I will check in the inbox. The reason
> I would prefer contributing with the HelpSystem in the trunk is
> because it ensures my contribution is not in vain.

Maybe you misunderstood. I was merely suggesting that the way to get HelpSystem into the trunk is by submitting it to the inbox first.

> Am I allowed to put things into perspective once more? I have been
> writing often lately. I don't want to come off as annoying and
> everything I write is in all due respect.
>
> What you are saying is that our community has a self-serving mentality
> (e.g. nobody will make such improvement a priority because it's not
> *their* priority) and you are suggesting me to do an unselfish act by
> writing documentation with unsuitable tools. A contradiction in logic.

I did not suggest any such thing. I just said you cannot *rely* on anyone else writing stuff for you. It may still happen. But as you could see from the comments of others, not everyone thinks that a missing spell-checker would block in-image documentation.

> Or, let's say for the sake of the argument, I could be also
> self-serving and write articles about Squeak on my blog where I can do
> proper formatting, spell checking, include images, etc. and get
> instant popularity! **Blogger is the winner!**
>
> That's basically how self-serving mentality works. The shortest and
> easiest path wins. Contributing on my blog would be good for Squeak
> (as a side effect) but doing so in-image documentation is better (best
> and direct). I am all right with contributing unselfishly because I
> believe a community cannot progress on the basis of selfishness. It's
> food-for-thoughts, right?

Not really, because we're not actually in disagreement I believe.

Everyone acts in their own interest. But we share some of the interests. That makes us a community. I like to think that our's works by the idea of reciprocity - the idea that if one gives freely, other will be inclined to do likewise. But it's the giving that counts, and it has to be unconditional. Even our license says so. Reciprocity does not involve demanding others give something first before one gives something back.

- Bert -



Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Casey Ransberger-2
In reply to this post by Ian Trudel-2
Quality in general is *always* better served by a proofreader than by
automatic spelling / grammar tools. This is part of why I want to do
documentation in the trunk: because the trunk model gives us
gatekeeping and peer review.

If someone finds something in one of my commits which reduces the
quality of the docs, I'd treat that as build breakage, hamburger-hat
and all.

If you want integrated spell checking, you're probably going to have
to do the development work yourself, as it doesn't seem to be a
priority to anyone else.

One thing I keep learning with software is YAGNI.
http://c2.com/xp/YouArentGonnaNeedIt.html

On Sunday, May 2, 2010, Ian Trudel <[hidden email]> wrote:

> 2010/5/2 Michael Haupt <[hidden email]>:
>> Hi Ian,
>
> Hi Michael,
>
>> On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> wrote:
>>> It is an unexpected comment from a German. My experience in the German
>>> market made it clear Germans demand high-quality writings — in German
>>> that is. The companies I have worked for were paying top dollars for
>>> near-perfect German writings, from advertisement to documentation.
>>
>> see, that's what stereotypes are for: being reconsidered. :-)
>
> I see. Companies however collect demographic data and it makes sense
> to consider such feedback. The important is to make a decision in a
> knowledgeable manner. Spell checker could be entirely excluded but at
> least it would be a decision taken in knowledge of its advantages and
> disadvantages. :)
>
>> I think it is much more important to get some documentation available.
>> Polishing is always possible. There is no business contract involved
>> here, and no $$$ lurking. At least not for me.
>
> Some documentation is already available: http://wiki.squeak.org/squeak
>
> Polishing did not happen.
>
> o_O
>
>>> My point is that we have more to gain to do it right from the ground
>>> up. The efforts required to interface with a spellchecker library is
>>> much less now than rewriting documentation later. ...
>>
>> Correct spelling alone doesn't make good quality, does it?
>
> You're right. Every detail matters to make good quality. *grin*
>
>> Best,
>>
>> Michael
>
> Quality is something I take at heart and I usually refrain from
> releasing anything that does not match a minimum quality standard as
> far as open source contribution goes and I release commercial work
> only when it matches my highest quality standard. A spell checker is
> among the tools I use to write documentation, articles, etc. I will
> survive if it's not in our HelpSystem but I know it will become an
> additional hurdle to me. I will probably end up writing in OpenOffice
> and transfer back in Squeak. Painful.
>
> Anyway, when are we getting HelpSystem integrated to the trunk again?
> We could be typing in there instead. :)))
>
> Ian.
> --
> http://mecenia.blogspot.com/
>
>

--
Casey Ransberger

Reply | Threaded
Open this post in threaded view
|

Re: Proposal: Project Pink Book

Michael Haupt-3
Casey,

you made my point much better than I could. Thanks. Special thanks for
the YAGNI pointer - I should have remembered that one. :-)

Best,

Michael

On Sun, May 2, 2010 at 8:48 PM, Casey Ransberger
<[hidden email]> wrote:

> Quality in general is *always* better served by a proofreader than by
> automatic spelling / grammar tools. This is part of why I want to do
> documentation in the trunk: because the trunk model gives us
> gatekeeping and peer review.
>
> If someone finds something in one of my commits which reduces the
> quality of the docs, I'd treat that as build breakage, hamburger-hat
> and all.
>
> If you want integrated spell checking, you're probably going to have
> to do the development work yourself, as it doesn't seem to be a
> priority to anyone else.
>
> One thing I keep learning with software is YAGNI.
> http://c2.com/xp/YouArentGonnaNeedIt.html
>
> On Sunday, May 2, 2010, Ian Trudel <[hidden email]> wrote:
>> 2010/5/2 Michael Haupt <[hidden email]>:
>>> Hi Ian,
>>
>> Hi Michael,
>>
>>> On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> wrote:
>>>> It is an unexpected comment from a German. My experience in the German
>>>> market made it clear Germans demand high-quality writings — in German
>>>> that is. The companies I have worked for were paying top dollars for
>>>> near-perfect German writings, from advertisement to documentation.
>>>
>>> see, that's what stereotypes are for: being reconsidered. :-)
>>
>> I see. Companies however collect demographic data and it makes sense
>> to consider such feedback. The important is to make a decision in a
>> knowledgeable manner. Spell checker could be entirely excluded but at
>> least it would be a decision taken in knowledge of its advantages and
>> disadvantages. :)
>>
>>> I think it is much more important to get some documentation available.
>>> Polishing is always possible. There is no business contract involved
>>> here, and no $$$ lurking. At least not for me.
>>
>> Some documentation is already available: http://wiki.squeak.org/squeak
>>
>> Polishing did not happen.
>>
>> o_O
>>
>>>> My point is that we have more to gain to do it right from the ground
>>>> up. The efforts required to interface with a spellchecker library is
>>>> much less now than rewriting documentation later. ...
>>>
>>> Correct spelling alone doesn't make good quality, does it?
>>
>> You're right. Every detail matters to make good quality. *grin*
>>
>>> Best,
>>>
>>> Michael
>>
>> Quality is something I take at heart and I usually refrain from
>> releasing anything that does not match a minimum quality standard as
>> far as open source contribution goes and I release commercial work
>> only when it matches my highest quality standard. A spell checker is
>> among the tools I use to write documentation, articles, etc. I will
>> survive if it's not in our HelpSystem but I know it will become an
>> additional hurdle to me. I will probably end up writing in OpenOffice
>> and transfer back in Squeak. Painful.
>>
>> Anyway, when are we getting HelpSystem integrated to the trunk again?
>> We could be typing in there instead. :)))
>>
>> Ian.
>> --
>> http://mecenia.blogspot.com/
>>
>>
>
> --
> Casey Ransberger
>
>

123