Thanks for the more extensive write-up, Pete. I was not thinking of static/dynamic content in the manner you described it; now I understand that a bit better.
Maybe we should first produce a list of capabilities our solution must have in order to satisfy our needs. We can discuss and hone those down until they're really well understood, and that'll make it much easier to determine the best solution. Paul seems to me to be focusing on the right things, and his proposals seem right to me, such as:
(1) the model of smaller,more modular docs; (2) tooling that worked like a git/pull-requestmodel?
And there are lots of choices before us which meet those two requirements, so the problem is clearly in meeting additional criteria as well. What we've seen so far in this conversation is that, although Paul's two points above address documentation maintenance, community development, and end-user preferences/needs, Pete has said that he hasn't found a solution that can handle those items along with providing static content and support for a variety of markup styles. Additionally, it seems enforcing a consistent structure in the documentation is difficult?
Does that seem like a fair synopsis of our discussion so far? I'll look into that history to which Pete directed me and see if I can reconstruct capabilities required of the solution in a simplified manner, but Pete, if you think you can already do that (or have already done that; is the list of four items (plus the enforcement of documentation structure?) you provided sufficiently thorough or representative of the issue?), then you're probably better for the job than I, but if not, I'll be glad to give it a shot.
In my estimation, we need to:
- Properly identify the capabilities required of our solution (that involves scrutinizing demands and perhaps removing or lowering priority of those which are less critical).
- Evaluate our current solution's handling of those capabilities
- Either remediate our current solution's issues (if the solution is capable of providing what we need) or seek a different solution.
That way, we can eliminate the risk of people involved in this conversation not being on the same page, or failing to address widely-known-but-unspoken issues, etc.
I hate to just spontaneously pop out of the woodwork like this, and I don't want to step on any toes or anything, so please let me know if there's a superior alternate approach, but I think we can solve this problem and really revolutionize Fedora Docs, at least in terms of accessibility and community development. If a good list of capabilities has already been generated or there's additional documentation I should look over, please let me know.
-Dylan
On Fri, Feb 5, 2016 at 7:33 AM, Paul W. Frields <stickster@xxxxxxxxx> wrote:
On Fri, Feb 05, 2016 at 10:18:20AM +1000, Jeff Fearn wrote:
> On 05/02/16 08:33, Jeff Fearn wrote:
> > On 04/02/16 20:54, Paul W. Frields wrote:
> >> For instance, AsciiDoc has really been embraced
> >
> > FYI it is easy to convert a Publican book to AsciiDoc.
> >
> > $ publican build --formats xml --langs en-US
> > $ cd tmp/en-US/xml
> > $ xmllint --xinclude $main.xml --output escape_xml_hell.xml
> > $ pandoc --to=asciidoc --from=docbook escape_xml_hell.xml -o foo.txt
> > $ a2x -f xhtml foo.txt
> > $ firefox foo.html
> >
> > Fly my pretties, FLY!
> >
> > Cheers, Jeff.
> >
>
> P.S. You can then use po4a to get POT/PO files from the AsciiDoc.
So for example, moving to smaller content/other tools/different markup
doesn't mean losing existing content. Brilliant!
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
The open source story continues to grow: http://opensource.com
--
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
