Hello to all, maybe I´m a little bit off-topic, but I need some suggestions/ideas: I´m working in a smaller signal processing company and we want to reorganise our documentation system. Until now we used mostly MS Word for that, but in my eyes that´s really cra*** software. I used LATEX for my master thesis back in the old days on university, but I don´t think that my colleges want to use that. So what systems do you use for documentation and writing manuals (for your sw, libraries and so on). Which benefits have they and which drawbacks. I´m mostly looking for a system a little bit easier to handle than LATEX but which (source)files can also be read by an text editor and where the reference system works at least so good as in LATEX. Thanks for suggestions, Markus www.two-pi.com
Documentation
Started by ●February 21, 2008
Reply by ●February 21, 20082008-02-21
Hi, I am using open document text of star office. It has a open document drawing too. i have not used open document. The advantage with star office is it is free. Not tried the equation editor. Regards Bharat Arithos Designs www.Arithos.com
Reply by ●February 21, 20082008-02-21
"mboigner" <mboigner@two-pi.com> writes:> Hello to all, > > maybe I´m a little bit off-topic, but I need some suggestions/ideas: > > I´m working in a smaller signal processing company and we want to > reorganise our documentation system. Until now we used mostly MS Word for > that, but in my eyes that´s really cra*** software. I used LATEX for my > master thesis back in the old days on university, but I don´t think that > my colleges want to use that. > > So what systems do you use for documentation and writing manuals (for your > sw, libraries and so on). Which benefits have they and which drawbacks. > I´m mostly looking for a system a little bit easier to handle than LATEX > but which (source)files can also be read by an text editor and where the > reference system works at least so good as in LATEX. > > Thanks for suggestions, > MarkusHi Markus, I still use LaTeX. What's wrong with that? -- % Randy Yates % "Remember the good old 1980's, when %% Fuquay-Varina, NC % things were so uncomplicated?" %%% 919-577-9882 % 'Ticket To The Moon' %%%% <yates@ieee.org> % *Time*, Electric Light Orchestra http://www.digitalsignallabs.com
Reply by ●February 21, 20082008-02-21
>Hi Markus, > >I still use LaTeX. What's wrong with that? >-- >% Randy Yates % "Remember the good old 1980's, when >%% Fuquay-Varina, NC % things were so uncomplicated?" >%%% 919-577-9882 % 'Ticket To The Moon' >%%%% <yates@ieee.org> % *Time*, Electric Light Orchestra >http://www.digitalsignallabs.com >Hello Randy, for me nothing, but I think it will be nearly impossible to get this as standard in the whole company. So I´m looking for something easier to use to implement as standard documentation/manual writing sw with similar capabilities as LATEX (=> that means always good working!) concerning cross-references, enumerations and formula editing and the possibility of reading the source files with a text editor. Most of the people here are used to use MS word so I think I´ll get though fight tomorrow in our discussion. So I´m looking if there are more choices than MS word, OO, Latex which are used outside in the wild. That are my motives for this thread. Fine regards, Markus www.two-pi.com
Reply by ●February 21, 20082008-02-21
mboigner wrote:> Hello to all, > > maybe I´m a little bit off-topic, but I need some suggestions/ideas: > > I´m working in a smaller signal processing company and we want to > reorganise our documentation system. Until now we used mostly MS Word for > that, but in my eyes that´s really cra*** software. I used LATEX for my > master thesis back in the old days on university, but I don´t think that > my colleges want to use that. > > So what systems do you use for documentation and writing manuals (for your > sw, libraries and so on). Which benefits have they and which drawbacks. > I´m mostly looking for a system a little bit easier to handle than LATEX > but which (source)files can also be read by an text editor and where the > reference system works at least so good as in LATEX. > > Thanks for suggestions, > Markus > > www.two-pi.comWhat about OpenOffice? You can download it at http://www.openoffice.org -= Mr. Raffa =-
Reply by ●February 21, 20082008-02-21
On 2008-02-21 10:31:51 -0400, "mboigner" <mboigner@two-pi.com> said:> >> Hi Markus, >> >> I still use LaTeX. What's wrong with that? >> -- >> % Randy Yates % "Remember the good old 1980's, when >> %% Fuquay-Varina, NC % things were so uncomplicated?" >> %%% 919-577-9882 % 'Ticket To The Moon' >> %%%% <yates@ieee.org> % *Time*, Electric Light Orchestra >> http://www.digitalsignallabs.com >> > > Hello Randy, > > for me nothing, but I think it will be nearly impossible to get this as > standard in the whole company. So I´m looking for something easier to use > to implement as standard documentation/manual writing sw with similar > capabilities as LATEX (=> that means always good working!) concerning > cross-references, enumerations and formula editing and the possibility of > reading the source files with a text editor. > > Most of the people here are used to use MS word so I think I´ll get > though fight tomorrow in our discussion. So I´m looking if there are more > choices than MS word, OO, Latex which are used outside in the wild. > > That are my motives for this thread. > > Fine regards, > Markus > > www.two-pi.comTechnical documentation is often done using FrameMaker. It is commercial, now from Adobe. It started out as the way to do serious manuals like those for commercial airliners when it was on Unix workstations. Now on Windows and Unix. I beleive that Apple uses it for their manuals. Some Microsoft manuals list it in their colophons.
Reply by ●February 21, 20082008-02-21
mboigner <mboigner@two-pi.com> wrote:> Hello to all, > > maybe I´m a little bit off-topic, but I need some suggestions/ideas: > > I´m working in a smaller signal processing company and we want > toreorganise our documentation system. Until now we used mostly MS Word > forthat, but in my eyes that´s really cra*** software. I used LATEX for > mymaster thesis back in the old days on university, but I don´t think > thatmy colleges want to use that. > > So what systems do you use for documentation and writing manuals (for > yoursw, libraries and so on). Which benefits have they and which > drawbacks. I´m mostly looking for a system a little bit easier to handle > than LATEXbut which (source)files can also be read by an text editor and > where thereference system works at least so good as in LATEX.No personal experience of it, but I believe DocBook is the kind of thing you're looking for. (And the price is right :-) -- TimH pull tooth to reply by email
Reply by ●February 21, 20082008-02-21
On Thu, 21 Feb 2008 15:58:10 GMT, Gordon Sande <g.sande@worldnet.att.net> wrote:>On 2008-02-21 10:31:51 -0400, "mboigner" <mboigner@two-pi.com> said: > >> >>> Hi Markus, >>> >>> I still use LaTeX. What's wrong with that? >>> -- >>> % Randy Yates % "Remember the good old 1980's, when >>> %% Fuquay-Varina, NC % things were so uncomplicated?" >>> %%% 919-577-9882 % 'Ticket To The Moon' >>> %%%% <yates@ieee.org> % *Time*, Electric Light Orchestra >>> http://www.digitalsignallabs.com >>> >> >> Hello Randy, >> >> for me nothing, but I think it will be nearly impossible to get this as >> standard in the whole company. So I´m looking for something easier to use >> to implement as standard documentation/manual writing sw with similar >> capabilities as LATEX (=> that means always good working!) concerning >> cross-references, enumerations and formula editing and the possibility of >> reading the source files with a text editor. >> >> Most of the people here are used to use MS word so I think I´ll get >> though fight tomorrow in our discussion. So I´m looking if there are more >> choices than MS word, OO, Latex which are used outside in the wild. >> >> That are my motives for this thread. >> >> Fine regards, >> Markus >> >> www.two-pi.com > >Technical documentation is often done using FrameMaker. It is commercial, >now from Adobe. It started out as the way to do serious manuals like >those for commercial airliners when it was on Unix workstations. Now >on Windows and Unix. I beleive that Apple uses it for their manuals. >Some Microsoft manuals list it in their colophons.Markus, Word is the default because more people are likely to have access to it, so document sharing is more seamless. If you want to use something less widely used, like LaTex, it just makes it much more difficult to share the document or collaborate with people who don't have it. There's a learning curve associated with LaTex, so getting people to convert will be difficult, especially since they'll only be able to use those skills with other people using LaTex. Word does have it's limitations, especially with very large documents, and Gordon is correct that in many cases FrameMaker is commonly used when Word can't handle the job. For review purposes, Word has edit tracking features that are very nice and many people know how to use. If you use a different tool like LaTex, it'll be more difficult for non-LaTex users to collaborate. Perhaps the advantages in your case outweigh the disadvantages, but if I were in the room I'd be arguing for Word just because in the long run in my experience it results in far less hassle and aggravation. Eric Jacobsen Minister of Algorithms Abineau Communications http://www.ericjacobsen.org
Reply by ●February 21, 20082008-02-21
mboigner wrote:> Hello to all, > > maybe I�m a little bit off-topic, but I need some suggestions/ideas: > > I�m working in a smaller signal processing company and we want to > reorganise our documentation system. Until now we used mostly MS Word for > that, but in my eyes that�s really cra*** software. I used LATEX for my > master thesis back in the old days on university, but I don�t think that > my colleges want to use that. > > So what systems do you use for documentation and writing manuals (for your > sw, libraries and so on). Which benefits have they and which drawbacks. > I�m mostly looking for a system a little bit easier to handle than LATEX > but which (source)files can also be read by an text editor and where the > reference system works at least so good as in LATEX.You need a decent documentation and (it seems) project administration tool. LaTex or Word are suited for creating documents, but not really suited for group working. The old fashioned way to go about project administration and documentation (if at all) is to have a more or less structured file directory system on a central server, where code, code documentation, protocols, manuals, papers, articles, etc. are stored. The project content is spread across different directories, different file types, barely searchable and often good ideas are lost because nobody documented them (sometimes a single sentence is a good idea - where to put a single sentence in a file directory tree?). The modern solution to this is to use a Wiki. I'm specifying DokuWiki with almost every project I'm starting new nowadays, and also for personal information content management. So far, I have only had good experiences. Here are some advantages (sometimes specific to Dokuwiki, sometimes generic to Wikis): - A Wiki is webbased, therefore the whole content is accessible to any project member from any computer worlwide (requiring no VPN installation or the like). This includes (apart from the normal written Wiki content) shared internet links, shared electronic references (documents), pictures, etc. all nicely grouped according to project (or work group, or whatever). - Pages can be edited and viewed with a standard webbrowser (no propriety software needed for editing or reading content). The syntax is of markup-type (highest obstacle against Word users), but the pages look good and structured. - All pages / access is completely configurable (read/write access by user, group). Configure your wiki to be open or closed as the project dictates. - Every edit and every page is under version control (any state can be reconstructed). - Documents can be uploaded and downloaded by anyone from anywhere (if you don't apply restrictions). - Protocols / Draft don't have to be sent around by e-mail, edited by everybody, and the edits conglomerated into one document again. There is one active version, which can be edited by the group. No version salads. - Completely searchable. - SVN plug-in to support viewing SVN repositories. - LaTex plug-in allows to include LaTex-Code to have nice formulas in standard Wiki pages. The list goes on and I am running out of time. Regards, Andor
Reply by ●February 21, 20082008-02-21
On 21 Feb, 17:51, Eric Jacobsen <eric.jacob...@ieee.org> wrote:> Perhaps the advantages in your case outweigh the disadvantages, but if > I were in the room I'd be arguing for Word just because in the long > run in my experience it results in far less hassle and aggravation.Whatever opinions one might have about MSOffice, the fact of the matter is that some 95% of people use it and have access to it, so one should have very strong reasons to use something else. You will need to have it no matter what you choose to do internally, for no other reason that your customers use it. That being said, there is apparently a version which lets you access XML files through word. XML files work much like LaTeX in that the different types of information in a file is tagged, such that files can be parsed and formatted automatically. Whatever solution you end up with, you should make sure to use something that can exploit the XML format. Rune
