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 _______________________________________________ Fedora-electronic-lab-list mailing list Fedora-electronic-lab-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/fedora-electronic-lab-list
