On 02/05/2016 08:55 AM, David Ashley wrote: > After reading all the comments so far I finally have something to say. > And it has nothing to do about the technical end of producing > documentation. I want to talk about people and community. > > We are a community of volunteers who produce documentation. That is the > bottom line. Thus, standards are not exactly something that can be > forced down the throat of a volunteer. All of us come to the table with > differing skill sets and backgrounds. And as a volunteer we are not > really willing to learn something new or change the way we do things > when there is no reward except the satisfaction of a job well done. > > The real question we should be asking is how do we best make use of > these diverse skill sets to produce documentation that is organized and > contains great content. If we can agree that this is the real question > before us then we can begin discussions on how to solve the problem. > Otherwise we will be spinning our wheels and wasting valuable resources. > > one solution put forward was to figure out how to accept a variety of > input formats into a process that produces the output we want. Obviously > some conversion of the input will need to be performed so that a common > output can be maintained. > > The above process would be very nice and could probably be built, but it > also has a big issue. In our volunteer environment, the maintainer is > usually not the original writer and their skill sets may not match. So > another big question is how do we solve this problem? Do we force the > maintainer to learn the document's original format? Do we perform > maintenance in a common format? This would be an additional feature to add to our checklist when vetting a solution: dynamic conversion of the *input* document to allow maintainers to contribute to existing docs in the format of their choice. Atlassian Confluence is the only solution I'm aware of - anecdotally - that does this, and it's not an option for us. It would be nice to have, but if a writer wants to own an iteration of a document that's currently written in asciidoc, and they really would prefer to edit in docbook, I think it should be reasonable for that writer to perform their conversion outside of the buildsystem. > I think you can see from the above discussion that we have a really > tough problem to solve. And the root of that problem is the people who > volunteer their time and resources. In our case, diversity of skills is > the key issue. Until we can come to an agreement that this is the real > problem we will never solve the technical problem. We have to design a > process and a set of governance rules that solves our people problem. > > Technical problems can almost always be solved, people issues are harder. > > W. David Ashley > -- The current organizational process would be something like this: 1. Needs are discussed 2. Solutions are suggested that meet some or all of the needs 3. Needs not met by a proposed solution are re-evaluated 4. A sufficiently adequate solution is planned in detail, openly 5. The solution is implemented, or not, by either clear consensus or vote. I don't see governance issues coming in until the last step, and we're hovering somewhere between step 1 and step 1.5. I didn't find any prebaked solutions that fit the needs I felt were important, especially with regard to CICD functionality, so I started creating one with mostly prebaked components. This doesn't preclude concurrent work of other solutions. Otherwise, I'm not sure what kind of organizational or policy type changes would help; can you elaborate? -- Pete -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
