[Fedora-electronic-lab] User documentation (was Re:Dead Upstream what should we do ?)
On Fri, Dec 4, 2009 at 7:50 PM, Shakthi Kannan wrote:
Just want to discuss this further as our list of packages is growing
day-by-day:
Yes userguides are currently one of your weaknesses. Let's create
another thread for this as we definitely got to find a suitable
solution for the long term.
1. Whatever documentation made for a particular software can be
pushed
upstream, so we keep track of only one set of sources. We will do
documentation in LaTeX or DocBook, so we abstract content with
presentation, and it will greatly help us in the long run.
+1 documentation should be pushed to upstream
I would tend to opt for LaTex as most of our upstream developers like
to keep their documentation in text format.
Having that said, what should we do for other tools which upstream
ships loads of documentation in OOo formats e.g kicad-doc ?
As we know Latex gives one the opportunity to create documents in any
type of format e.g pdf, dvi, ps ...
If we are to ship the same contents in different formats, we should
also bundle all the plugins for these formats. In FEL-12, I didn't
think about this and by default (on the livedvd) one cannot read .dvi
files with evince, because I missed the package evince-dvi on the
livedvd (sorry by the way :) ). The more we add such type of
dependencies to the livedvd the more
* time we have to allocate for the livedvd's testing
* time we have to allocate for package reviews
* the size the livedvd will be.
* the more dependencies they will pull.
So here a decision should be made. If it was for me, pdf format is
enough. What do you think ?
2. In Yelp, we can provide links to all relevant installed package
documentation? If that can be done, it will only be linking to the
respective files? or else we will need something similar in the lines
of .desktop files that can simply pin-point to where the doc/, man/,
info/ pages for each software/tool that is shipped, and are
independent of desktop environments.
I have no idea if linking to specific files is possible.
In the wiki pages I'm editing on
https://fedorahosted.org/fedora-electronic-lab/wiki/Digital, I'm
pointing to these type of commands :
$ man XXXXX
or
$ rpm -qd XXXXXX
example in : https://fedorahosted.org/fedora-electronic-lab/wiki/Digital/iverilog
Pointing to specific files would be great for the user, but hard on
us. Each time upstream add/remove docs, the packager will have to
update this yelp correctly.
3. We will also need to provide documentation on suggested workflows
with various tools that are shipped, so people can follow it.
This is coupled with your #2. Either we do it in
* latex directly and output one big PDF which we can package
separately so that it can be shipped on the livedvd and be updated as
any other package, ( we could possibly add the release notes and the
flyer in that package as well)
* or in yelp as in #2.
If in #1, we choose latex, I would favour latex here too. What do you think ?
"Design flows" is one of FEL's strengths. It would be difficult to
push this upstream as many tools of different upstreams will fall in
different flows. Hence we have to maintain it ourselves in our git.
However we have to ensure it can also easily available so that other
distributions can use that "Design flows" doc as reference.
Chitlesh