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
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
-----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
documentation@lists.ipfire.org
-
Michael Tremer -
R. W. Rodolico