On 2/5/2016 2:32 PM, Pete Travis wrote:
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
"hi
Speaking from someone who has contributed to fedora's docs before, the
process isn't easy but it isn't difficult. I've been meaning to
apologize for the tone of my message earlier. I got to thinking about it
and it sounded a little too demanding when I really thought about it.
I'll rephrase it a bit. I want to become a member of fedora's docs
community, so I can maintain the accessibility guide, which is mostly
up to date, but there are sections that sound a little too ... stiff
and formal. If we could settle on a format I could understand, that
would make my job easier, but I am willing to write in plain text or odf
and send this to someone for conversion if necessary. Some form of
markdown would be nice, since I know a little about it and headings,
lists, etc aren't too difficult to make. Does publican understand
markdown? I really don't understand the tool that well, but I believe it
takes a config file and xml, and uses that to convert the docs into
various other output formats (pdf, html, txt, epub?) Pete is right
though. This is a volunteer effort, so you can't expect everyone to
settle on a rigidly defined set of standards. A loose one might work
though. It's also worth pointing out that whatever solution we use must
be free software. Publican is, I think. I'm a little confused. Are we
thinking about switching software we use to compile the docs?
Thanks
Kendell clark"
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
