Need some reviews, please

Need some reviews, please

[R. W. Rodolico]

[-- Attachment #1: Type: text/plain, Size: 1898 bytes --]

When I first decided to pay back some of the benefit I received from
this project, I realized I do not have the dedication or time to be a
developer. So, I test and document.

When I first started doing any documentation, I was scared to change
anything, and I believe I caused the development team more trouble
fixing my messups than I actually helped. Because of this, I started
looking more closely at the "how do we document the project" idea.

I reorganized http://wiki.ipfire.org/projects/docs/start slightly to put
articles about "How to write articles" in the bottom section, "Wiki
guideline".

At Mr. Tremer's suggestion, I then read (kind of), an original document
at http://wiki.ipfire.org/test. It is in German!

NOTE: I do not speak German. I speak three languages; English, Bad
English and Very, Very Bad Spanish. You'll note that German is not
listed there at all. Learning to count to 29 on my grandmothers knee
does not count as speaking German. Nor does 6 weeks of German class in
college. This was all about Google Translate and guessing. That article
(in Bad English) is at
http://wiki.ipfire.org/projects/docs/quick_syntax_overview and
desperately needs review.

Finally, I decided we needed some quick guidelines, so I wrote
http://wiki.ipfire.org/projects/docs/basic_documentation_guidelines.
Again, this definitely is not a finished project, and it is mainly
filled with guesses at what our basic guidelines should be. I did try to
read some of the other articles to see what these guidelines should be,
but feel free to tell me I'm way off base.

Feedback??? Please! I have very thick skin, so tons of negative feedback
will not hurt my feelings. I just want someplace we can send new
documenters to and say "here, read this if you want to know how we do
things."

Rod
-- 
Rod Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
214.827.2170
http://www.dailydata.net

Re: Need some reviews, please

[Michael Tremer]

[-- Attachment #1: Type: text/plain, Size: 2560 bytes --]

Hi,

On Tue, 2016-09-13 at 00:24 -0500, R. W. Rodolico wrote:
> When I first decided to pay back some of the benefit I received from
> this project, I realized I do not have the dedication or time to be a
> developer. So, I test and document.

Always welcome, you know that.

> When I first started doing any documentation, I was scared to change
> anything, and I believe I caused the development team more trouble
> fixing my messups than I actually helped. Because of this, I started
> looking more closely at the "how do we document the project" idea.
> 
> I reorganized http://wiki.ipfire.org/projects/docs/start slightly to put
> articles about "How to write articles" in the bottom section, "Wiki
> guideline".
> 
> At Mr. Tremer's suggestion, I then read (kind of), an original document
> at http://wiki.ipfire.org/test. It is in German!

Can we merge all of this into the new doc guidelines and get rid of this old
document?

> NOTE: I do not speak German. I speak three languages; English, Bad
> English and Very, Very Bad Spanish. You'll note that German is not
> listed there at all. Learning to count to 29 on my grandmothers knee
> does not count as speaking German. Nor does 6 weeks of German class in
> college. This was all about Google Translate and guessing. That article
> (in Bad English) is at
> http://wiki.ipfire.org/projects/docs/quick_syntax_overview and
> desperately needs review.

"Bad English" is quite good I think if that means simple and short. This doesn't
have to sound like Shakespear and we have many readers for which English is only
a second language, so the simpler, the better. Technical documentation is
probably never too exciting to read :)

> Finally, I decided we needed some quick guidelines, so I wrote
> http://wiki.ipfire.org/projects/docs/basic_documentation_guidelines.
> Again, this definitely is not a finished project, and it is mainly
> filled with guesses at what our basic guidelines should be. I did try to
> read some of the other articles to see what these guidelines should be,
> but feel free to tell me I'm way off base.
> 
> Feedback??? Please! I have very thick skin, so tons of negative feedback
> will not hurt my feelings. I just want someplace we can send new
> documenters to and say "here, read this if you want to know how we do
> things."

I just read over it very quickly, but I like what I see.

Maybe try dividing it into multiple pages when it becomes longer and to
demonstrate the namespaces :)

Best,
-Michael

> 
> Rod

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Need some reviews, please

[R. W. Rodolico]

[-- Attachment #1: Type: text/plain, Size: 3655 bytes --]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1



On 09/13/2016 09:26 AM, Michael Tremer wrote:
> Hi,
> 
> On Tue, 2016-09-13 at 00:24 -0500, R. W. Rodolico wrote:
>> When I first decided to pay back some of the benefit I received
>> from this project, I realized I do not have the dedication or
>> time to be a developer. So, I test and document.
> 
> Always welcome, you know that.

Yes, I feel very welcome. I want others who are thinking about helping
to understand what I have found out; helping with the documentation
can be very fulfilling also.

> 
>> When I first started doing any documentation, I was scared to
>> change anything, and I believe I caused the development team more
>> trouble fixing my messups than I actually helped. Because of
>> this, I started looking more closely at the "how do we document
>> the project" idea.
>> 
>> I reorganized http://wiki.ipfire.org/projects/docs/start slightly
>> to put articles about "How to write articles" in the bottom
>> section, "Wiki guideline".
>> 
>> At Mr. Tremer's suggestion, I then read (kind of), an original
>> document at http://wiki.ipfire.org/test. It is in German!
> 
> Can we merge all of this into the new doc guidelines and get rid of
> this old document?

Yes. I'll look at it and see if we can't streamline the guidelines.
I'm fairly certain the document I created is fairly close to the
original. As long as no one spots any errors, I'll be happy to remove
the original doc (the German one).

> 
>> NOTE: I do not speak German. I speak three languages; English,
>> Bad English and Very, Very Bad Spanish. You'll note that German
>> is not listed there at all. Learning to count to 29 on my
>> grandmothers knee does not count as speaking German. Nor does 6
>> weeks of German class in college. This was all about Google
>> Translate and guessing. That article (in Bad English) is at 
>> http://wiki.ipfire.org/projects/docs/quick_syntax_overview and 
>> desperately needs review.
> 
> "Bad English" is quite good I think if that means simple and short.
> This doesn't have to sound like Shakespear and we have many readers
> for which English is only a second language, so the simpler, the
> better. Technical documentation is probably never too exciting to
> read :)
> 
>> Finally, I decided we needed some quick guidelines, so I wrote 
>> http://wiki.ipfire.org/projects/docs/basic_documentation_guidelines.
>>
>> 
Again, this definitely is not a finished project, and it is mainly
>> filled with guesses at what our basic guidelines should be. I did
>> try to read some of the other articles to see what these
>> guidelines should be, but feel free to tell me I'm way off base.
>> 
>> Feedback??? Please! I have very thick skin, so tons of negative
>> feedback will not hurt my feelings. I just want someplace we can
>> send new documenters to and say "here, read this if you want to
>> know how we do things."
> 
> I just read over it very quickly, but I like what I see.
> 
> Maybe try dividing it into multiple pages when it becomes longer
> and to demonstrate the namespaces :)

Yes, it would be better to split it up. I was doing a quick and dirty
at the time, trying to get it translated as best I could.

I hope to have some time this weekend, and if that is the case, I'll
work on cleaning up the docs namespace a little.


> 
> Best, -Michael
> 
>> 
>> Rod

- -- 
Rod Rodolico
Daily Data, Inc.
POB 140465
Dallas TX 75214-0465
214.827.2170
http://www.dailydata.net
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAlfaLxMACgkQuVY3UpYMlTQwPgCfa1hNamiQVbmABn8mwGWn5855
8ZUAn1+NCWexKnOc+YQ6F5an0l2OK61X
=PCsy
-----END PGP SIGNATURE-----

Need some reviews, please

[Carlo Fusco]

[-- Attachment #1: Type: text/plain, Size: 2259 bytes --]

On Tue, Sep 13, 2016 at 7:24 AM, R. W. Rodolico <rodo(a)dailydata.net> wrote:
[cut]
>
> When I first started doing any documentation, I was scared to change
> anything, and I believe I caused the development team more trouble
> fixing my messups than I actually helped. Because of this, I started
> looking more closely at the "how do we document the project" idea.


thank you for doing that, as a newbie I appreciate very much this work.

>
> I reorganized http://wiki.ipfire.org/projects/docs/start slightly to put
> articles about "How to write articles" in the bottom section, "Wiki
> guideline".


from the point of view of a newbie can I make a suggestion? Can you
incorporate in the main text what is now in the link

http://wiki.ipfire.org/en/edit

In other words, make it explicit what to do. Something along this
line, Do you want to contribute to improve the documentations? First
read these links and then open an account etc..

> At Mr. Tremer's suggestion, I then read (kind of), an original document
> at http://wiki.ipfire.org/test. It is in German!
>
> NOTE: I do not speak German. I speak three languages; English, Bad
> English and Very, Very Bad Spanish. You'll note that German is not
> listed there at all. Learning to count to 29 on my grandmothers knee
> does not count as speaking German. Nor does 6 weeks of German class in
> college. This was all about Google Translate and guessing. That article
> (in Bad English) is at
> http://wiki.ipfire.org/projects/docs/quick_syntax_overview and
> desperately needs review.


I don't understand, what's wrong with this:
http://wiki.ipfire.org/wiki/syntax

which I believe is part of the standard documentation of DokuWIki. Did
you want a more synthetic document?
Regardless, I think that the links to the documentation in German
should be removed.

>
> Finally, I decided we needed some quick guidelines, so I wrote
> http://wiki.ipfire.org/projects/docs/basic_documentation_guidelines.


That's very, very nice. Thank you for doing this. As I said, as a
newbie I really appreciate this work. I didn't know about the
namespace issues you described so well, clear and to the point. I like
it.

Thanks again, including for all your help and encouragement.

-- 
Carlo Fusco



-- 
Carlo Fusco