On Feb 5, 2016 09:41, "John J. McDonough" <wb8rcr@xxxxxxxx> wrote:
>
> On Fri, 2016-02-05 at 08:55 -0600, David Ashley wrote:
> >
> > 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.
>
> I think this is key. But there is something else we seem to be
> ignoring; we need a way to produce reasonable hardcopy output.
>
> Much of the time you NEED the documentation you don't have access to a
> computer or the Internet. When you look something up a lot of the time
> the small chunk is very handy. But when you are in deep doo-doo you
> often need to be holding a piece of paper in your hot little hands.
> Even when things haven't totally gone south, a lot of processes leave
> you without access part of the time, and you either need to scribble
> down the next steps or have a good memory.
>
> And there is another dimension that could help (and maybe this again
> has to do with conversion); it is handy if hardcopy output is dense.
> Even our current model produces documents that perhaps focus more on
> form than function. That is, they look nice but contain a lot of wasted
> space. For the hardcopy output, you really want a minimum number of
> pages in preference to looking pretty.
>
> Man pages are pretty nice this way, although when they get a little
> longer they tend to become more opaque. And the main problem with man
> pages is that you need to know the answer ahead of time. One very nice
> feature of man pages is that you can print them and get something
> usable.
>
> Online documents almost want to be the opposite. You would like plenty
> of whitespace to help organize and highlight the content. But when you
> try to print a wiki you get a huge pile of useless paper.
>
> We were pretty close with translation of the wiki to docbook, but mw-
> render wasn't kept up to date, and not a lot of folks used it because
> it only did a 95% job. I guess whatever we have has to be polished.
>
> Stickster mentioned that we should look to existing tools, and I like
> that idea, *IF* we can find something that works. Our history is
> littered with tools that looked like they mostly did the job but were
> eventually discarded because they couldn't really do what we expected.
>
> Someone earlier mentioned a git-based wiki sort of tool that sounded
> close, but that appeared to be closed source so I didn't look too hard,
> but given all the expectations we have, I'm skeptical.
>
> On the flip side, as David mentioned, we are a group of volunteers, and
> as such, tend to be kind of fluid. I have little doubt that Pete or
> myself could grok together something that works, but then even if we
> are still around a few more releases, real life will interfere with
> needed maintenance.
>
> Not sure of the answer - lots of dimensions. But don't loose sight of
> the features we already have when looking for new ones.
>
> --McD
hmm... I'm taking two solid 'requirements' bullet points from this:
- Accommodate long and short form works
In the tooling context, I read this as needing a document table of contents, and multipage document support, in addition to a site-global toc for single page articles. This is a must have to use the existing books.
- Ensure the capacity for alternative output formats.
And perhaps a nice-to-have: when rendering ie pdf or epub, provide the capacity for styling/templating/structure that's more appropriate for that format, instead of ie 'print webpage to pdf'. That's probably a long term thing, but anything with modular output capability makes it possible.
--Pete
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: http://lists.fedoraproject.org/admin/lists/docs@xxxxxxxxxxxxxxxxxxxxxxx
