On 07/16/2018 03:18 PM, Joshua D. Drake wrote:
> On 07/16/2018 03:07 PM, Tim Cross wrote:
>>
>> I think encouraging user developed docs is a great idea.
>>
>> However, I'm not sure how your proposal really addresses the issue. How
>> would your proposal deal with the "but let's be honest, writing a
>> blog/article/howto in a wiki is a pain in the butt" issue? Writing
>> decent documentation or clear examples is hard and the only thing worse
>> than no documentation is misleading or confusing documentation.
>
> Well I threw all this out there to start a discussion on how best this
> could be done. What *I* would do is either create a series of templates
> to be followed that we would push to HTML and PDF. That could be done
> with a form and TinyMCE or we could use LibreOffice/Office templates.
> However, I don't know that the community would buy into the office
> template idea (thus seeking feedback).
>> My only real concern would be to further fracture the PG user base. If
>> there are barriers preventing users from adding documentation to the
>> existing documents or wiki, perhaps it would be better to try and
>> address those first?
>
> First, my assumption is that this project would be done within the .Org
> infrastructure and if the community thinks that we should just use
> DocBook that is certainly an option (although adhering to something like
> Docbook Simple may be best).
All the above is cool and everything, but is putting the cart before the
horse. To me to make this work the following needs to happen:
1) Create an editorial board. This group of people would determine the
answers to the questions above. They would also develop the framework
for what needs covered. This would be based on what users want to see.
Then a call for contributors could be made.
2) The other thing the editorial board would do is create list of
qualified peer reviewers. These folks would then review the
contributions and give feedback. On successfully passing a review a
contribution would go into the documentation.
3) Some combination of the editorial board/peer reviewers/other
volunteers would periodically go over existing documentation to
remove/update stale content.
>
> Thanks,
>
> JD
>
>>
>> Tim
>>
>
--
Adrian Klaver
adrian.klaver@aklaver.com